Run kestrel or its ks alias without a command to open the interactive
terminal client. Command mode provides focused operations that can also be used
from scripts.
Invocation and aliases
kestrel is canonical and ks is its interactive alias. Command mode returns process exit status; commands that advertise JSON or files keep structured output separate from human-readable diagnostics.
Command-mode families
| Command | Current usage | Purpose |
|---|---|---|
model | kestrel model <show or search or set-provider or set> ... | Inspect or change the configured model |
status | kestrel status | Show Local Core and local configuration status |
core | kestrel core <status or restart> [--wait] | Inspect build compatibility or safely restart the Local Core daemon |
workspace | kestrel workspace <status or list> | Resolve the current workspace or list registered workspaces |
web | kestrel web [--host <host>] [--port <port>] [--token <token>] | Expose Local Core to a trusted local server over authenticated HTTP |
job | kestrel job <preflight or run> --json-in <file> --json-out <file> | Prove compatibility, then run non-interactive work with strict JSON input and output |
operator | kestrel operator <resume-wait or approve or retry-delegation or doctor-export> ... | Respond to waits, approvals, delegations, and diagnostic exports |
runtime | kestrel runtime <replay or doctor> <query> [--json] | Inspect recorded runtime evidence |
runtime bundle | kestrel runtime bundle <query> --out <file> | Export a diagnostic bundle |
setup | kestrel setup [--profile <id>] [--approval-pack <dev, ci_bot, or production>] [--full] | Check or configure a local installation |
uninstall | kestrel uninstall plan --scope <current, software, or complete> | Plan or apply a macOS uninstall with blockers, typed confirmations, and final verification |
job preflight resolves and registers an immutable execution profile and writes
job_preflight_v1. It does not create a job, thread, run, repository checkout,
or worktree. A ready V2 preflight binding is mandatory for V2 job run; binding
drift writes job_run_rejection_v1 and stops before dispatch. Existing direct
clients may continue to submit job_input_v1 to job run.
Both commands require --json-in and --json-out. Kestrel continues to use
KESTREL_HOME for isolated state. It does not implement --state-dir.
Interactive commands
Inside kestrel, use /help for the complete current list. Common groups
include:
- sessions and navigation:
/start,/new,/sessions,/switch,/resume - inspection:
/status,/workspace,/tasks,/checkpoint,/assembly - configuration:
/profiles,/model,/mode,/mcp,/code,/skill - operator control:
/approve,/deny,/reply,/retry,/steer,/queue,/stop - recovery:
/snapshot,/restore,/operator
Local state
Local Core stores product data under the platform data directory and adds the active state epoch:
| Platform | Default product root |
|---|---|
| macOS | ~/Library/Application Support/Kestrel |
| Windows | %LOCALAPPDATA%\\Kestrel |
| Linux | $XDG_DATA_HOME/kestrel, or ~/.local/share/kestrel |
KESTREL_CORE_HOME selects an explicit Local Core product root.
KESTREL_HOME selects an isolated Kestrel home, primarily for development and
testing. In either case, Local Core resolves the active state/<epoch> below
that root.
Projects, sessions, and Mission Control
Workspace commands resolve local projects; interactive session commands preserve conversation identity. /tasks and related project views are Mission Control projections in 0.8, while operator commands control active or waiting runs.
Scheduling status
The separate kcron executable can install, start, stop, and inspect its local
service and evaluate registered workspaces. Workspace execution is not
available: an enabled workspace is recorded with the deferred outcome until
the central scheduler is implemented. See kcron availability.
Exit codes and structured output
Treat zero as successful command completion and nonzero as a typed command/setup/runtime failure. For job run, read the required JSON output file and its terminal outcome rather than scraping terminal prose.