简体中文

On this page

Command And Key Reference

Docs home · User guide · Configuration Reference · 简体中文

Use this page for exact user-facing commands, keys, paths, outputs, and recovery behavior.

TUI Keys

Action	Key
Open help / slash selector	`F1` / `/`
Submit	`Enter`
Show or hide info rail	`F2`
Switch visible rail compact/detail	`Shift-F2`
Scroll transcript	`PageUp/PageDown`, `Ctrl-U/D`, `Ctrl-Home/End`
Cycle default permission mode	`Shift-Tab`
Insert composer newline	`Ctrl-J`; `Shift-Enter` / `Alt-Enter` when supported
Move composer cursor	`Ctrl-A/E`, `Ctrl-B/F`, `Alt-B/F`, arrows
Delete composer text	`Backspace/Delete`, `Ctrl-H/W`, modified Backspace/Delete
Kill/yank line tail	`Ctrl-K/Y`
Restore the last draft cleared with `Esc`	`Ctrl-Z`
Select and copy transcript text	Drag and release; copies automatically and excludes the info rail
Retry selected transcript copy	`Ctrl-C` when a failed selection remains active
Copy selection, or latest assistant reply when no selection is active	`Ctrl-L`; info rail is excluded
Cancel current run / close overlay	`Ctrl-C` with no selection / `Esc`
Focus and move through activity	`Ctrl-G`, `Alt-J` / `Alt-K`
Read the next bounded page from focused saved tool output	`Alt-N`
Search a bounded literal in focused saved tool output	`Alt-F`
Focus task verification	`Alt-V`; `Enter` runs, `I` inspects
Pause the exact running task at a safe boundary	`Alt-P`; resume later with `/task continue`
Open latest checkpoint restore	`Ctrl-R`; `Enter` restores, `F` forks, `Esc` closes
Open Intent Stack review	`Alt-S`; `Up/Down` selects, `D` previews Drop, `Enter` confirms
Open saved-session actions	Select `/resume` row, then `Ctrl-O` or right-click
Toggle latest Mermaid source	`Ctrl-O` when no saved-session, tool-card, or other higher-priority action is active
Cycle visible agent transcript	Agent panel, `Alt-A`, `Shift-Alt-A`
Expand/collapse thinking or activity	`Ctrl-T`
Run diagnostics on changed source	`Alt-D`
Cancel focused terminal task	`Alt-X`

Up/Down first handles composer history or multiline movement. Ctrl-Z restores one cleared draft; it is not a general undo stack.

Slash Commands

Command	Purpose
`/config`	Open configuration
`/doctor`	Run diagnostics
`/feedback`	Preview and export a local support report
`/new`	Start a fresh session
`/resume`	Select a saved session
`/agent <main\|child-id>`	Switch visible transcript
`/agent rename <child-id\|current> <name>`	Name a child transcript
`/agent cancel <child-id\|current>`	Cancel a running child with a live handle
`/queue`	Show advanced follow-up controls
`/queue next\|interrupt\|edit\|delete [item]`	Reorder, interrupt for, edit, or remove a follow-up
`/plan [prompt]`	Run a read-only plan; accept its card to start a task
`/task <task>`	Start multi-step execution
`/task continue`	Continue the latest unfinished task
`/model <model-id\|connection-id/model-id>`	Continue the current idle session on an exact ready route; in the selector, `D` changes only the saved default
`/effort <low\|medium\|high\|max>`	Change reasoning effort for the next run
`/compact`	Generate, validate, and activate one recoverable context checkpoint
`/update [check\|refresh\|apply]`	Check the current channel, bypass the cached check, or explicitly apply an admitted update
`/intents`	Review durable intent status, artifacts, conflicts, and exact Drop previews
`/quit`	Quit the TUI

Aliases: /m for /model, /e for /effort, and /q or /exit for /quit. Candidate commands use Up/Down, Tab, and Enter.

CLI Commands

Command	Use
`sigil`	Open the TUI with a fresh session in the current workspace
`sigil doctor [--output text\|json]`	Run local diagnostics
`sigil mcp add <name> -- <command> [args...]`	Add a local stdio MCP server
`sigil mcp add <name> --url <https-url>`	Add a remote Streamable HTTP MCP server
`sigil mcp list` / `get <name>` / `remove <name>`	Inspect or remove configured MCP servers
`sigil run "<task>" [--connection <id> --model <id>] [--output text\|json\|jsonl]`	Run a non-interactive task; connection and model must appear together
`sigil resume [session-id]`	Restore the exact session, or the latest session when omitted
`sigil intent --session <session-id> inspect`	Emit the bounded durable Intent Stack for one exact session
`sigil intent --session <session-id> drop-preview --intent-id <id> --intent-version <n>`	Build an exact read-only Drop preview
`sigil intent --session <session-id> drop --operation-id <id> --stack-version <n> --preview-digest <digest>`	Confirm and execute the exact preview
`sigil serve`	Start the authenticated loopback-only local service
`sigil update check [--channel current\|stable\|beta] [--refresh] [--output text\|json]`	Check for a release without changing the installation
`sigil update apply --yes [--channel current\|stable\|beta] [--output text\|json]`	Explicitly install an admitted standalone update or print the owning package-manager command
`sigil --version`	Print the installed version
`sigil --config <path> doctor`	Diagnose an explicit config

Machine Output And Local Server

sigil run --output json writes one result to stdout. jsonl writes ordered events followed by one result or error. Human progress and safe network notices stay on stderr. Exit codes are 0 success, 1 execution failure, 2 invalid invocation/configuration, and 130 cancellation.

sigil intent writes exactly one versioned JSON result or safe typed error to stdout. It resolves only an exact durable session id from the current workspace catalog; it does not accept a session path or client-supplied permission/approval authority. Build a fresh preview before Drop. Preview and execute fail closed while the durable session still has an active foreground run.

Start the local service with a high-entropy environment token:

export SIGIL_HTTP_TOKEN="$(openssl rand -hex 32)"
sigil serve

The service prints its selected loopback address. GET /health is unauthenticated; OpenAPI, disclosure, session, run, event, cancellation, approval, and historical catalog routes require Authorization: Bearer <token>. It is not a remote or multi-user service, does not use cookie auth or wildcard CORS, and shuts down on Ctrl-C.

Trusted local launchers can request a one-line, secret-free readiness object and tie the child lifetime to a private stdin pipe:

sigil serve --startup-output json --shutdown-on-stdin-close

The authenticated GET /server-info response uses the same versioned schema. Run one server per workspace; the bearer token belongs in the child environment, never in arguments or logs. Closing the owner pipe starts the same graceful drain as Ctrl-C; without the flag, terminal stdin does not control server lifetime.

GET /sessions lists live handles owned by the current server process. For restart-durable workspace history, use GET /session-catalog?limit=50&q=...&provider=...&pinned=true&state=ready. The catalog returns an OpenAPI-defined allowlist of compact, safely projected metadata with an opaque next_cursor; storage hashes, record checksums, active runs, approvals, and progress are not part of this response. If history changes between pages, a 409 stale_cursor response means the client must restart from the first page. The catalog is a rebuildable index over session logs, so a catalog failure does not stop runs or session recording.

To continue a ready catalog entry after a server restart, send its relative session_ref and expected durable session_id to authenticated POST /sessions/open. The server revalidates the session log rather than trusting SQLite, creates no run or provider request, and returns one process-local session handle. Repeating the same open in one server process returns that same handle. Missing, non-ready, or identity-changed sources fail closed; clients should query the catalog again instead of constructing filesystem paths.

Config Resolution

Sigil uses --config <path> when supplied; otherwise it loads ~/.sigil/sigil.toml. A workspace-root sigil.toml is not loaded automatically.

Important Paths

Path	Meaning
State root `workspaces/<workspace-id>/sessions/`	Session logs
State root `workspaces/<workspace-id>/input-history.jsonl`	Composer history
State root `workspaces/<workspace-id>/artifacts/`	Terminal and change artifacts
Cache root `workspaces/<workspace-id>/tmp/`	`$SIGIL_SCRATCH_DIR` base; each session gets its own owner-only `tmp/sessions/<session-id>/` namespace with a size quota and TTL reclamation
User config `~/.sigil/sigil.toml`	Default local config
`.sigil/agents`, `.sigil/commands`, `.sigil/skills`, `.sigil/plugins`	Native workspace resources
`.agents/skills`, `.codex/agents`, `.opencode/{skills,commands,agents}`, `.claude/{skills,commands,agents}`	Compatibility resources discovered by default and covered by workspace trust; commands use slash-prefixed names, agents use `@name`
`SIGIL.md`, `AGENTS.md`, `SIGIL.local.md`	Workspace instructions

Do not commit real secrets in config or local instruction files.

Web Tool Inputs

Tool	Input	Boundary
`websearch`	`query`; optional `max_results`	Uses the selected provider-hosted, configured MCP, or bundled route.
`webfetch`	observed `source_id`; optional `format`, `max_content_bytes`	Opens only a URL already observed in the current session.

Both also follow [web].network_mode. deny blocks them; an unresolved ask cannot proceed headlessly.

Approval Outcomes

Outcome	Meaning
`allow`	Run the action
`deny`	Reject it
`timeout`	Deny after no decision
`approval_required`	A non-interactive run needed a decision it could not request

Session Recovery Facts

Restart restores supported visible session and task state.
An unfinished tool returns as interrupted and is not silently rerun.
/new starts a fresh session; /resume selects an older one.
Saved-session actions include resume, conversation fork, safe export, pin/unpin, and reviewed delete.
Retention cleanup requires an explicit preview and confirmation under /config → Storage.
Exiting prints the session id and sigil resume <session-id>.
/task continue continues the latest unfinished task when one exists.

Provider credentials belong in Providers; config fields belong in Configuration Reference.

Next: Return to the User Guide.