reference.md

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
Open settings while keeping the composer draft	F3 (inside settings: Save and close); /config also works
Open or close scrollable workspace/session details	F4 (Alt-I / Shift-F2 also work); click F4 details in the rail
Scroll details / close without submitting	Up/Down, PageUp/PageDown, Home/End, mouse wheel / Esc or Enter
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
Expand or collapse focused activity	Ctrl-O
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	F5 (Alt-P also works); resume later with /task continue
Open latest checkpoint restore	Ctrl-R; Enter restores, F forks, Esc closes
Branch from a completed conversation turn	Alt-B; Up/Down selects, Enter branches, Esc closes. While editing, Alt-B keeps word navigation.
Comment on recorded changes	Alt-R; select a checkpoint, file and line range, Enter adds a comment, Ctrl-S sends or queues the batch
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
Import a completed conclusion into the current conversation	Saved-session actions, K; select and read a conclusion, then Enter imports without sending
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 the current task list, thinking, or activity	Click the task overflow row or press 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>`
`/agent rename <child-id	current> `
`/agent cancel <child-id	current>`
/queue	Show advanced follow-up controls
`/queue next	edit
/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>`
`/effort <low	medium
/compact	Generate, validate, and activate one recoverable context checkpoint
/control-log preview · /control-log confirm <preview-digest>	Preview damaged command history, then explicitly confirm sealing the old history and opening a new generation; original pending commands retain their identities
`/update [check	refresh
/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]`
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 "" [--connection --model ] [--output text	json
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 --config <path> acp	Serve ACP v1 over stdio for an editor; keeps shared approval, cancellation and session recovery semantics
`sigil update check [--channel current	stable
`sigil update apply --yes [--channel current	stable
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. The run envelope uses protocol_version: 2; there is no V1 output mode. Result status preserves succeeded, failed, cancelled, interrupted, blocked, paused, awaiting_user_input, and awaiting_plan_decision separately. Exit codes are 0 success, 1 failure/interruption/block/pause, 2 invalid invocation/configuration, 3 awaiting a plan decision, 4 awaiting user input, and 130 cancellation. Read the result status when a script needs the precise reason for a non-success exit.

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>.
• Exiting restores the terminal before stopping work and cleaning up resources. After 5 seconds, Sigil reports that cleanup is still in progress. Successful cleanup exits normally; actual cleanup failures remain errors.
• /task continue continues the latest unfinished task when one exists.

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

Command Execution

Commands start through the unified exec_command tool. The interface shows the redacted command once its arguments are complete; long commands can be expanded, with a short output preview. A command may keep running after a wait returns. The agent uses the same execution ID to wait, read output, send input, or cancel. Actual exit and cleanup determine the final state.

Next: Return to the User Guide.