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.
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 |
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 run --json-in <file> --json-out <file> [--profile <id>] | 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 run is the protocol-native non-interactive surface. Its required
--json-in and --json-out files keep request and result handling explicit.
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.
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.