Command measurements
Evidence:proven in the stated test
The ks client is public and MIT-licensed: curl -fsSL keepstate.ai/install.sh | sh, or the install page for Homebrew, npm, and checksums. Latest release v0.1.26; releases carry SHA256SUMS and build-provenance attestations, and ks update verifies before trusting.
This page is a dated evidence record, not the reference: what each command needed, what it charged at the moment it ran and what it printed, when it was run on a disposable account (client v0.1.8, 2026-09-17). A command that run did not reach says not measured rather than describing output nobody observed. The current commands, in their terminal and in-app forms, are on the CLI reference.
Complete CLI reference: commands, flags and exit codes
| verb | usage | what it does | permission | billable effect | expected output | access tier | evidence context |
|---|---|---|---|---|---|---|---|
| ks login | ks login [--ctl URL] | sign in (browser device flow) | none to start; the device flow signs the account in read from the client source, not run | not measured | not measured | not measured | record |
| ks run | ks run [--image I] [--budget-tokens N] [--agent] [--name NAME] [--agent-name NAME] [--key KEY] [--task TEXT] [--open] [--model MODEL] [--harness HARNESS] | start a hosted session; with --agent, an agent session whose main agent is running and supervised | valid token; free tier allows ONE running session at a time | none | hosted session <id>: image=base state=running (on https://ctl.keepstate.ai) <id> | free and paid, measured on a free-tier account | record |
| ks checkpoint (save) | ks checkpoint <session> [--stop] | save the session (durably); --stop parks it | valid token; own running session | none | checkpointed <id> | free and paid, measured on a free-tier account | record |
| ks wake (resume) | ks wake <session> | resume a parked session (mid-sentence) | valid token; own stopped session | none | hosted session <id> resumed <id> | free and paid, measured on a free-tier account | record |
| ks kill | ks kill <session> [--force] | destroy a session (guarded: checkpoint first) | valid token; own session | none | killed <id> | free and paid, measured on a free-tier account | record |
| ks meter | ks meter <session> | spend, budget, key sources | valid token; own session | none | session <id> · spent 0 / budget 500,000 tokens · billed calls 0 · key source(s): [] | free and paid, measured on a free-tier account | record |
| ks exec | ks exec [--shell] <session> [--] <command...> | run one command in the session | valid token; own running session | none | measured | free and paid, measured on a free-tier account | record |
| ks attach | ks attach <session> | interactive terminal into a running session (tmux) · relays the guest tmux over a control-plane upgrade tunnel; live resize is a v1 limitation | valid token, own running session read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks fork | ks fork <session> [-n N] [--steer FILE] | branch a checkpoint into diverging children · paid plans only; each child is another running session | valid token; PAID PLAN only; refused on the free tier | none | error: fork creates additional concurrent sessions, which the free tier does not allow (one session at a time). Forking is available on a paid plan. | paid plan only, measured: refused on the free tier | No per-command gate record linked here. |
| ks cruise init | ks cruise init [--allow PATH...] [--goal TEXT] [--tests CMD] [--check RUNNER] [--paths GLOB...] [--ladder family:model,...] [--spend USD] | draft the acceptance manifest from the repository into .keepstate/cruise.json · makes no request and never calls a model; a repository with no check is refused with exit 2 and nothing written | none; works signed out; makes no request | none | <digest> manifest: .keepstate/cruise.json (draft, version 1) goal: make the inventory tests pass check: python3 -m pytest -q (detected; override with --tests) tests | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise approve | ks cruise approve [--key PROVIDER=KEY] | lock the draft, binding the upload selection, the check's inputs and one provider key per ladder provider into the digest · makes no request; refused when the workspace changed since init | none; works signed out; makes no request; locks the draft | none | <digest> approved: .keepstate/cruise.lock locks manifest version 1 at 2026-09-17T12:29:37Z next: ks cruise run | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise run | ks cruise run [--separate-upload] | upload the workspace and the locked manifest; start the job | valid token; a provider key in the account's vault (measured: refused 402 ks_no_inference_key without one); refuses before any request without a lock, with changed tests, or over 50 MiB | the job it starts: spend unavailable on the ledger (the gateway ledger carries tokens, not money) by its terminal state (accepted); the ledger delta at submit time is none | job <id> queued: spend ceiling $2.00, 2 rungs, 1,465 bytes packed (on https://ctl.keepstate.ai) <id> | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise status | ks cruise status [job] [--watch] | the job (or the newest): state, rung, each attempt, save points, spend, verdict, artifact · --watch reads GET /api/jobs/{id}/status, served by production ctl 4f9b4ad (build 8a22c753). | valid token; own job | none | job <id> state queued goal: make the inventory tests pass rung 1 of 2 (claude-haiku-4-5-20251001) save points: unavailable spent $0.00 of $2.00 ceiling verdict: unavailable artifact: unavailable record: unavailable upda | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise logs | ks cruise logs <job> | the event stream, one event per line: seq, ts, type, detail | valid token; own job | none | 1 2026-09-17T12:29:38.533314296Z job.queued {"ladder":[{"family":"anthropic","model":"claude-haiku-4-5-20251001"},{"family":"anthropic","model":"claude-sonnet-5"}],"manifest_sha":"2c93103eb323803ebf8672625c616c0cae42079a | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise cancel | ks cruise cancel <job> | cancel a job · Reads the job's review first (GET /api/jobs/{id}/status, served by production ctl 4f9b4ad) and shows the option's effect before acting; against an older control plane it says so and acts as before. | valid token; own job | none | job <id> cancelled <id> | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise resume | ks cruise resume <job> [--ladder family:model,...] | resume a job from review, on the same or a wider ladder · Reads the job's review first (GET /api/jobs/{id}/status, served by production ctl 4f9b4ad) and shows the option's effect before acting; against an older control plane it says so and acts as before. | valid token; own job in review only; refused otherwise (ks_job_state) | none | error: resume is legal only from review (state: queued) (ks_job_state) | not measured | No per-command gate record linked here. |
| ks cruise artifact | ks cruise artifact <job> [--out FILE] | download the accepted tarball · Where the job status serves a verified result (production ctl 4f9b4ad does), the bytes are also re-checked against the verified candidate tree and the badge is shown as served; otherwise only the sha256 check applies and the download is not shown as verified. | valid token; own accepted job; the digest is verified before the file is written | none | artifact <id>: 1,498 bytes, sha256 <id> verified <temp path> | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks cruise models | ks cruise models [--cached] | the model catalog: exact ids, family, provider route, rung, runner compatibility as stated, price standing and your key route | valid token | none | model table v1 (from https://ctl.keepstate.ai) anthropic (provider anthropic): claude-haiku-4-5-20251001, claude-sonnet-5 openai (provider openrouter): openai/gpt-4o-mini, openai/gpt-4o default ladder: anthropic:clau | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks doctor | ks doctor | connectivity, token, version | none; works signed out; reports the account id and cohort | none | ok control plane reachable (https://ctl.keepstate.ai) ok token valid (account <account>, cohort ) ok up to date (v0.1.8) | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks update | ks update [--require-provenance] | self-update (checksum-verified, provenance-checked with gh) | none; replaces the binary read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks logout | ks logout | remove the stored token | none; works signed out; deletes the local credential only | none | Signed out. The server-side token can also be revoked from your account page. | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks uninstall | ks uninstall | how to remove ks completely | none; works signed out; prints the removal command; removes nothing | none | To remove ks completely (one line): rm -f <temp path> && rm -rf <temp path> | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks version | ks version [--verify] | print the version; with --verify, check this binary's build provenance | none; works signed out | none | ks v0.1.8 | free and paid, measured on a free-tier account | No per-command gate record linked here. |
| ks operation show | ks operation show <operation> | read an operation back by its id or key: state, result, timestamps | valid token; runs only where the control plane reports operations.idempotent available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks operation wait | ks operation wait <operation> | wait, within the bound, for an operation to finish and print its result | valid token; runs only where the control plane reports operations.idempotent available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks completion | ks completion <shell> | print a shell completion script generated from the command schema | none; runs locally read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks reference | ks reference | print the command reference as a Markdown table generated from the command schema | none; runs locally read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session list (ls) | ks session list [--state STATE] [--all] | your sessions, newest activity first: state (the console's word beside the raw state), agent, task, last activity, last save; ended sessions in a final group | valid token; runs only where the control plane reports session.list available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session show | ks session show <session> | one session in full; a short id is accepted when it is unique among yours | valid token; runs only where the control plane reports session.list available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise preview (workspace preview) | ks cruise preview [--allow PATH...] | what an upload would carry and what it would not, with reasons: names and sizes, never content | none; runs locally read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session key set | ks session key set <session> [--key KEY] | bind a session's provider to one of your keys by id; that key is used or nothing is | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks key list | ks key list | your keys: id, provider, alias, last four characters, enabled or disabled | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks key show | ks key show <key> | one key's metadata | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks key add | ks key add [--provider PROVIDER] [--alias NAME] | store a provider key read from standard input; it is never an argument and never comes back | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks key enable | ks key enable <key> | allow new admissions with a key | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks key disable | ks key disable <key> | refuse new admissions with a key; in-flight usage is reconciled | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks key delete | ks key delete <key> | plan a key deletion, then execute it with --yes | valid token; runs only where the control plane reports keys.inventory available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks preflight | ks preflight [--provider PROVIDER] [--mode MODE] [--check COMMAND] [--ladder FAMILIES] | what a run needs and what is missing: identity, keys, credit, capabilities, and the local upload preview; starts nothing | valid token; runs only where the control plane reports preflight available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent list | ks agent list [--session ID] | the agents of a session: name, id, activity, role, current task · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent open | ks agent open <name> [--session ID] [--take-control] [--view] [--no-follow] [--resume] [--project PROJECT] | the agent window: its state, then its events as they happen · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent status | ks agent status <name> [--session ID] [--watch] | one agent's activity, queue depth and current task · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent tell | ks agent tell <name> <instruction> [--session ID] [--resume] | queue one instruction for an agent from outside any window · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent queue show | ks agent queue show <name> [--session ID] | why an agent's queue is not moving: what blocks it, what waits behind it, what each choice would do · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent queue resume | ks agent queue resume <name> [--session ID] [--finding TEXT] | continue the instructions held behind a failed or unresolved one; that one is never restarted · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent queue hold | ks agent queue hold <name> [--session ID] [--finding TEXT] | record that an agent's queue stays held, and what you established · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task resume | ks task resume <instruction> [--session ID] [--checkpoint ID] [--finding TEXT] [--accept-affected DIGEST] | run one blocked instruction again as a new attempt from a saved point you name; it never continues the rest of the queue instead · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available. Measured: with no --checkpoint it lists the session's restorable saved points and refuses, sending nothing; with one it restores from THAT saved point only, never substituting another, and it releases no held instruction on any path | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent approve (approval approve) | ks agent approve <request> [--session ID] | approve one permission request an agent is waiting on, by its id · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent deny (approval deny) | ks agent deny <request> [--session ID] | deny one permission request an agent is waiting on, by its id · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent pause | ks agent pause <name> [--session ID] | save the session an agent lives in and park it, waiting until it is parked · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent resume | ks agent resume <name> [--session ID] | resume the parked session an agent lives in, waiting out a save that is still completing · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task list (task ls) | ks task list [--session ID] [--agent NAME] | the instructions of a session's agents, in the order they were committed · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task show | ks task show <instruction> [--session ID] | one instruction in full: where it sits, what it says, what it last reported and what attempt exists · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session checkpoints | ks session checkpoints <session> | the saved points a restore or a fork may name: whether each is usable now and its position, boundary, state, scope and manifest identity · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task cancel | ks task cancel <instruction> [--session ID] [--reason TEXT] | end one instruction: it will not run, and the instructions held behind it stay held · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task reconcile | ks task reconcile <instruction> [--session ID] [--finding TEXT] | record that a running attempt's outcome could NOT be established, after the service refused its close · the binary dispatches this verb; it runs only where the control plane reports the agent.workspace capability available, and refuses with that reason where it does not | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks adviser connect | ks adviser connect <adviser> [--session ID] [--agent NAME] [--confirm SESSION/AGENT] [--expires DURATION] [--max-consultations N] [--max-tokens N] [--max-output-tokens N] | let an agent consult another agent of yours, after you have seen both ends and confirmed the adviser by name | valid token; runs only where the control plane reports advisers.connect available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks adviser list | ks adviser list [--session ID] [--agent NAME] | an agent's adviser connections, live, revoked and expired, in both directions | valid token; runs only where the control plane reports advisers.connect available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks adviser disconnect | ks adviser disconnect <grant> | withdraw a connection: every future consultation over it stops at once | valid token; runs only where the control plane reports advisers.connect available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session use | ks session use [session] [--clear] [--trust-repo] [--confirm SESSION] | bind this project to a session, so commands without --session mean it: per account, project root and control plane | valid token; runs only where the control plane reports session.list available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session rename | ks session rename <session> <new-name> | rename a session by id; its id and everything in it are unchanged | valid token; runs only where the control plane reports api.v2.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent rename | ks agent rename <name> <new-name> [--session ID] | rename an agent by id; its tasks, approvals and adviser connections keep resolving | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks result list | ks result list [--task ID] [--session ID] [--agent NAME] | the results of one task, or of a session's tasks: name, size, sha256, task, verification | valid token; runs only where the control plane reports tasks.results available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks result show | ks result show <result> | one result: size, sha256, task and attempt, the producer's checks, the task's verification, provenance | valid token; runs only where the control plane reports tasks.results available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks result download | ks result download <result> [--out FILE] [--force] [--extract DIR] [--task ID] [--grant-ttl DURATION] [--keep-partial] | download a result, verify its size and sha256, and place it without replacing anything | valid token; runs only where the control plane reports tasks.results available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent logs | ks agent logs [--session ID] [--follow] [--cursor CURSOR] [--limit N] | the session's setup log and its agent's log from a cursor, safe to print; --follow polls until the service says it ends | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks file list | ks file list [path] [--session ID] | one directory of a session's workspace: type, mode, size, name; secret files marked redacted | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks file show | ks file show <path> [--session ID] [--max-bytes N] [--out FILE] | one workspace file, at most 1 MiB, printed as safe text or written to a new file | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent queue list | ks agent queue list <name> [--session ID] | an agent's pending work in dispatch order, the instruction executing now apart, and the queue revision a move names | valid token; runs only where the control plane reports tasks.queue_edit available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task move | ks task move <instruction> [--session ID] [--before TASK] [--after TASK] [--queue-revision QREV] | move one queued instruction before or after another pending one of the same agent, against a queue revision | valid token; runs only where the control plane reports tasks.queue_edit available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks approval list | ks approval list [--session ID] [--all] | a session's permission requests with the instruction each was asked for, what it touches and what deciding costs | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks approval show | ks approval show <request> [--session ID] | one permission request in full: the action, its instruction, what it touches, the cost, expiry and decision | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent queue cancel | ks agent queue cancel <name> [--session ID] [--preview] [--confirm QREV] [--states STATES] [--reason TEXT] | cancel an agent's pending instructions in bulk: previewed first, then confirmed by naming the preview's queue revision | valid token; runs only where the control plane reports tasks.queue_edit available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks task replace | ks task replace <instruction> [--session ID] [--text TEXT] [--queue-revision QREV] [--reason TEXT] | replace one pending instruction: it is cancelled with its content kept and a new one takes its place, against a queue revision | valid token; runs only where the control plane reports tasks.queue_edit available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise proposal list | ks cruise proposal list [--session ID] | a session's proposed Cruise jobs, newest first: state, goal, manifest digest and the job each became | valid token; runs only where the control plane reports cruise.proposals available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise proposal show | ks cruise proposal show <proposal> | one proposed job: its manifest in full, the digest the service states and the digest computed here, and its job | valid token; runs only where the control plane reports cruise.proposals available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise proposal approve | ks cruise proposal approve <proposal> [--confirm DIGEST] | run a proposed job by confirming the digest of the exact manifest shown | valid token; runs only where the control plane reports cruise.proposals available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise proposal decline | ks cruise proposal decline <proposal> [--reason TEXT] | decline a proposed job; it never runs | valid token; runs only where the control plane reports cruise.proposals available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise draft create | ks cruise draft create [--dir FOLDER] [--archive FILE] [--session SESSION] [--root FOLDER] [--proposal PROPOSAL] [--goal TEXT] [--paths GLOB...] [--check RUNNER] [--allow PATH...] [--ladder family:model,...] [--spend USD] [--key PROVIDER=KEY] | a hosted draft from a folder (packed here by init's own selection), a .zip, .tar.gz or .tar archive, one of your sessions, or an agent's proposal: what was found and the digest computed here · a folder is packed by the same selection ks cruise init uses; the paths it leaves out are named, never sent. The service keeps its copy unbilled until approval, discard or expiry | valid token; runs only where the control plane reports cruise.drafts available; sends a folder packed by init's own selection, an archive, or the name of one of your sessions or an agent's proposal; the service keeps a copy of the selected files for this draft only, unbilled, until it is approved, discarded or expires; nothing runs read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise draft list | ks cruise draft list | the account's open drafts, newest first: state, goal, files, manifest digest and how long each is kept | valid token; runs only where the control plane reports cruise.drafts available; reads the account's open drafts; nothing is approved, created or run read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise draft show | ks cruise draft show <draft> [--manifest] [--verify] | one draft: what was read and left out, the check, the terms and the digest computed here; --verify recomputes every digest from its archive | valid token; runs only where the control plane reports cruise.drafts available; reads one draft (with --verify, its archive too) and recomputes its digests locally; nothing is approved, created or run read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise draft set | ks cruise draft set <draft> [--goal TEXT] [--paths GLOB...] [--any-file] [--check RUNNER] [--ladder family:model,...] [--spend USD] [--key PROVIDER=KEY] | change a ready draft's goal, paths, check, ladder, spend limit or keys; the manifest and its digest are drafted again | valid token; runs only where the control plane reports cruise.drafts available; changes a ready draft's terms at the revision read just before; the digest changes with them and nothing runs read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise draft approve | ks cruise draft approve <draft> [--confirm DIGEST] | run a draft by confirming the digest of the exact manifest shown, computed here · confirmed by the manifest digest computed here from the manifest the service returned; --yes does not approve | valid token; runs only where the control plane reports cruise.drafts available; confirmed by the manifest digest computed here; once confirmed, creates one Cruise job from exactly the archive the draft holds, which runs and spends against your key and credit read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise draft discard | ks cruise draft discard <draft> | discard a draft; its copy of the files is deleted and it never runs | valid token; runs only where the control plane reports cruise.drafts available; deletes the draft's copy of the files; nothing runs or is spent read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session usage | ks session usage <session> | a session's model use, runtime and storage, apart, with units, source and whether each figure is actual, estimated or unavailable | valid token; runs only where the control plane reports budget.admission available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks check define | ks check define [--session ID] [--agent NAME] [--input PATH] [--artifact PATH] [--workdir PATH] [--kind KIND] [--timeout SECONDS] [--max-output BYTES] <name> [--] <argv...> | store a check: an argument vector with no shell, the files it depends on, its artifacts and bounds; runs nothing | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks check list | ks check list [--session ID] [--agent NAME] | an agent's checks: the exact action, the definition hash and the input sets you trusted | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks check run | ks check run <check> | request a run of a check; it executes only over inputs you trusted | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks check show | ks check show <run> | one run: state, inputs seen, exit status, output, artifacts' digests, the action to trust | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks check trust | ks check trust <run> [--confirm HASH] | trust the exact action a run stopped at: this definition over the inputs it saw | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session fork | ks session fork <session> [--plan] [--checkpoint CHECKPOINT] [--children N] [--execute DIGEST] [--plan-id ID] | plan a fork of a named saved point, then execute exactly that plan by its digest | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session restore | ks session restore <session> [--checkpoint CHECKPOINT] [--reason TEXT] [--accept-affected DIGEST] | restore a session from a named saved point, and say exactly what continues from it | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent view | ks agent view <name> [--session ID] [--choose N] [--confirm CHOICE] | the live window's model: header, runner, footer counts and the KS menu, as the service gives them, within 80x24 | valid token; runs only where the control plane reports agents.view available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent stop | ks agent stop <name> [--session ID] [--confirm NAME] [--reason TEXT] | stop an agent: its instruction in flight is asked to stop and its queue is held; the session keeps running | valid token; runs only where the control plane reports agents.stop available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent create | ks agent create <name> [--session ID] | create the primary agent of a session that has none | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent remove | ks agent remove <name> [--session ID] [--plan] [--execute PLAN] | remove an agent through a plan: what it cancels and keeps, then the removal naming that plan | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks result diff | ks result diff <result> [--content] | what an attempt's ks-changeset.json says it changed, against its recorded base, with every path escaped | valid token; runs only where the control plane reports tasks.results available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks result apply | ks result apply [result] [--dir DIR] [--confirm DIGEST] [--recover] | apply an attempt's changeset to this project, only onto the recorded base, transactionally | valid token; runs only where the control plane reports tasks.results available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session idle | ks session idle <session> | a session's idle policy and where it stands: counting, warned with the park time and countdown, deferred with the reason | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks project configure | ks project configure [--project ID] [--session ID] [--file PATH] [--confirm DIGEST] | propose .keepstate/project.json as the project's defaults, see the exact changes, and trust that digest only if you confirm it | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session checkpoint-policy | ks session checkpoint-policy <session> [--on] [--off] [--interval MINUTES] | a session's automatic-save policy and where it stands; --on/--off changes it against the session's revision | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session delete | ks session delete <session> [--plan] [--execute PLAN] [--confirm SESSION] | delete a session record through a plan; the runtime's stop and the content's standing are reported apart | valid token; runs only where the control plane reports deletion.plans available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks adviser discover | ks adviser discover [name] [--project ID] | the existing agents you may consult: selector, availability, the runner each reported, last seen; creates and grants nothing | valid token; runs only where the control plane reports agent.workspace available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise upload | ks cruise upload <job> [--from FILE] | send a queued job's workspace as its own upload, from the archive kept when the job was created (or --from FILE), checked against the job's manifest first | valid token read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks advice list | ks advice list <instruction> | every consultation one instruction raised: who was asked, who replied, who is pending or unavailable (named), whether the set is complete, current or history · Gated on the registry's advisers.advice row (available since ctl 2026-09-28); the verb refuses with that row's reason wherever it reads otherwise. The agent.workspace row decides only for an older registry that has no advisers.advice row. | valid token; runs only where the control plane reports advisers.advice available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks advice show | ks advice show <consultation> | one consultation in full: who asked whom, when it was asked, taken up and answered, the context it was asked with, and the adviser's own words · Gated on the registry's advisers.advice row (available since ctl 2026-09-28); the verb refuses with that row's reason wherever it reads otherwise. The agent.workspace row decides only for an older registry that has no advisers.advice row. | valid token; runs only where the control plane reports advisers.advice available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise review | ks cruise review <job> | a job in review: why it stopped, every attempt with its exact check result and cost, what remains of the ceiling, and each option with its effect · Reads GET /api/jobs/{id}/status (served by production ctl 4f9b4ad, build 8a22c753; an unauthenticated request answers 401). | valid token read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise result | ks cruise result <job> [--download] [--out FILE] | an accepted job's result: the badge exactly as served, the provenance chain, and every limitation · Reads GET /api/jobs/{id}/status (served by production ctl 4f9b4ad, build 8a22c753; an unauthenticated request answers 401). | valid token read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks cruise apply | ks cruise apply <job> [--dir DIR] [--confirm DIGEST] | apply an accepted job's result to this project file by file, only onto the base each file was changed from, transactionally · Reads GET /api/jobs/{id}/status and GET /api/jobs/{id}/changeset (both served by production ctl 4f9b4ad, build 8a22c753; unauthenticated requests answer 401). | valid token read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session migrate | ks session migrate <session> [--confirm DIGEST] | turn a legacy session into an agent session through a preview you review: runner, keys, saved points, what each legacy command does afterwards, what is preserved, the rollback point · Reads GET /api/v2/sessions/{id}/migration and sends POST /api/v2/sessions/{id}/migrate; gated on the registry's session.migration row (available since ctl 2026-09-28), else agent.workspace. | valid token; runs only where the control plane reports session.migration available read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session model | ks session model <session> [model] | the model a session's agents call; with a model, change it while the session is paused, in effect from its next resume · Reads GET /api/v2/sessions/{id} and sends PATCH /api/v2/sessions/{id} with runner_model and expected_revision; gated on agent.workspace. The service accepts the change while the session is parked or has no machine yet (ks_session_not_paused otherwise, ks_session_killed once it has ended) and only a model GET /api/v2/models offers (ks_model_invalid names the offered ones). | valid token; reads the session record; a change is accepted only while the session is paused or has no machine yet, with the record's revision read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent ask | ks agent ask <name> <question> [--session ID] | ask one of an agent's connected advisers a question, as a person, and wait for its answer: "@<adviser> <question>" | valid token; runs only where the control plane reports advisers.advice available (agent.workspace where that capability is not reported); the question goes to an adviser a person connected read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks agent history | ks agent history <name> [--session ID] [--last N] | an agent's conversation so far, in any session state, with the whole text of every entry: your instructions, its words, its tools, questions over its connections; newest last | valid token; runs only where the control plane reports agent.workspace available; reads the session's journal in any session state and wakes nothing read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session harness | ks session harness <session> [harness] [--model MODEL] | the runner a session's agents work inside; with a harness, switch it while the session is paused: its files stay, and the next instruction starts a new conversation · Reads GET /api/v2/sessions/{id} and sends PATCH /api/v2/sessions/{id} with harness, an optional runner_model and expected_revision; gated on agent.workspace. The service accepts the switch while the session is parked or has no machine yet (ks_session_not_paused otherwise), for a harness GET /api/v2/models offers (ks_harness_unavailable) and the session's own image carries (ks_harness_not_in_image), with a model of that harness (ks_model_harness_mismatch) and, for a harness that calls another provider, an enabled key for it (ks_no_inference_key). | valid token; runs only where the control plane reports agent.workspace available; with no harness it reads the session's harness, model and whether it can switch now; with a harness it switches the record against the revision just read, accepted only while the session is paused or has no machine yet, for a harness the catalog offers and the session's image carries, with an enabled key of its provider read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
| ks session brief | ks session brief <session> | the handoff brief of the session's latest harness switch, as the new agent received it: KeepState's record of the work so far, who wrote its narrative on whose key, its size and its checks · Reads GET /api/v2/sessions/{id}/handoff-brief; gated on agent.workspace. The brief of the session's latest harness switch, as the new agent received it: written by KeepState from its records, with a narrative by the outgoing harness's smallest model on the session's own key, checked by code (citations of the journal, an order no person gave dropped, secrets redacted). ks_not_found when the session never switched its harness. Changes nothing. | valid token; runs only where the control plane reports agent.workspace available; reads the handoff brief of the session's latest harness switch and changes nothing read from the client source, not run | not measured | not measured | not measured | No per-command gate record linked here. |
Where a command was run, these columns report observations on client v0.1.8 (public release asset, checksum c9ff6d5df6e4a1e8), 2026-09-17. The billable effect is what the command itself charged when it ran; a session it starts then accrues session time until it is paused or deleted (usage and costs). Unrun commands are marked not measured; source-derived permission requirements are identified separately. 94 verbs were not run and say so in every measured column: login, attach and update were NOT run: login is an interactive device flow, attach is an interactive terminal that would not return, and update self-replaces the binary under test. Their permission is read from the client source rather than measured, and their output and billable effect are left unmeasured rather than guessed. The 32 verbs the v0.1.9 manifest added were NOT run either: the measurements above were taken on v0.1.8, and these verbs have not yet been run against the production control plane. Their permission is read from the v0.1.9 client source, including the capability each one needs the control plane to report, and their output and billable effect are left unmeasured rather than guessed. When that was written the agent and task verbs refused on production, because the control plane did not report agent.workspace; since 2026-09-28 it does, and they were not re-run for this file. The 48 verbs added through v0.1.13 were NOT run either: their permission is read from the v0.1.13 client source, including the capability each one needs the control plane to report, and their output and billable effect are left unmeasured rather than guessed. Of them, cruise review, cruise result, cruise apply, cruise upload, session use, session rename, session usage and session delete are available on production. Since client v0.1.14 (2026-09-28) the agent, adviser, advice, session-migration and cruise-proposal verbs are available as well: the control plane reports agent.workspace and each verb's own capability available. None of them was run for this file.
What the client refuses to do
Each refusal below carries its source and the date it was last confirmed.
-
ks kill
Refuses a session that has no saved checkpoint, because killing it would destroy unsaved work, and names both ways out:
ks checkpoint <id> --stopsaves and stops it,ks kill <id> --forcedestroys it anyway.Confirmed 2026-09-09, DEC-01 command gate, released client against a disposable account. The guard is enforced by the daemon, not the client, so it holds for every caller including the console.
-
ks cruise run
Refuses, before any request: a draft without a lock (run
ks cruise approve), a workspace over 50 MiB (.git and .keepstate excluded), a test file changed since approve (the tests_digest differs), a draft changed since approve, and a workspace changed since approve.Confirmed 2026-09-16, cruise_test.go (TestCruiseRunRefusals) against a recording control plane: each refusal exits non-zero with zero requests.
-
ks cruise artifact
Verifies the download's sha256 against the job's artifact_sha before the named file exists; a mismatch is refused and nothing is written.
Confirmed 2026-09-16, cruise_test.go (TestCruiseArtifactVerifiesBeforeWriting) against a control plane serving a tampered artifact.
-
ks cruise upload
Refuses, before any upload: a job that is not queued, a job whose workspace is already stored (nothing is sent), no kept archive and no --from (it never re-packs), and an archive whose sha256 or size differs from the job's manifest.
Confirmed 2026-09-26, cruise_upload_test.go (TestCruiseUploadRefusalsSendNothing) against a recording control plane: each local refusal sends no PUT; the service's 403 exits 3 and its 409 exits 5.
The default session budget
A session stops at its token budget rather than running until someone notices. The default is per tier, and the two figures do not have the same standing, so each says where it came from.
| tier | default budget | how we know |
|---|---|---|
| free | 500,000 tokens | measured on client v0.1.8 (public release asset, checksum c9ff6d5df6e4a1e8), 2026-09-17, against a disposable free-tier account; the ratified price book states the same figure |
| paid | 2,000,000 tokens | stated by the ratified price book and the control plane that applies it. Not measured: no paid account was exercised. |
Override it per session with ks run --budget-tokens N.
What to read next
- CLI reference: every current command, in the terminal and in the app.
- Limits: what is not possible yet.