Skip to content
last verified against v0.1.26 verified 2026-10-16

CLI reference

Every command of the released ks client (v0.1.26), grouped the way ks --help groups it. Each one runs in a terminal as ks <command> and inside the app as /<command>, with the window's session and agent filled in; four do not run in the app, and the table says why. The table is generated from the client's own command manifest, so a command missing here is one the client does not have. ks <command> --help (or /<command> --help) prints a command's options and examples and changes nothing.

In the app

  • The same command. The window runs the same ks binary with the same arguments and shows its output in the conversation.
  • Context is filled in. The "In the app" column says what the window adds: this session (--session, or a session argument you left out), and this agent (an agent argument you left out on an agent command, or --agent). A new name, as in /agent create, is never filled in.
  • Nothing prompts. A / command runs with --no-input, so a step that asks for confirmation names the flag to pass instead (see Confirmations). It gets no standard input either.
  • Short forms such as /stop and /results run one command each; the slash commands page lists them with the window's own commands.

Confirmations

A step that changes or removes something is confirmed by naming exactly what was shown, never by a bare yes:

You confirm withUsed by
--confirm <digest>result apply, cruise apply, cruise draft approve, cruise proposal approve, session migrate, project configure
--confirm <name>agent stop (the agent), adviser connect (session/agent), session use (the session)
--plan, then --execute <plan>agent remove; session delete also takes --confirm <session>
--plan, then --execute <digest> --plan-id <plan>session fork
--preview, then --confirm <queue revision>agent queue cancel
--confirm <hash>check trust
--yeskey delete, after it shows its plan

Global options

Every command takes these:

OptionWhat it does
--jsonstable JSON on stdout: schema_version, request_id, data or error; progress stays on stderr
--plainone fact per line, no alignment or colour (the human output is already plain; this pins it)
--no-colorno colour codes (this release prints none; accepted so scripts can pass it)
--quietno progress lines on stderr; results and errors still print
--no-inputnever prompt or open a browser; a decision that needs you fails with exit 2 and the flag to pass
--yesskip a displayed confirmation when every input is already exact; never a grant, budget, approval or trust, and of the deletion plans only ks key delete's, which it shows first
--wait-timeout DURATIONhow long to wait for an accepted operation before reporting it as continuing; default 120s

Agents

CommandIn the appArguments and optionsWhat it does
ks advice list /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
ks advice show /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
ks adviser connect /adviser connect; fills in this agent and this session <adviser> [--session ID] [--agent NAME] [--confirm SESSION/AGENT] [--expires DURATION] [--max-consultations N] [--max-tokens N] [--max-output-tokens N]
  • --session ID: the session of the agent that will ask; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --agent NAME: the agent that will ask (default main)
  • --confirm SESSION/AGENT: confirm the adviser without a prompt; it must name the adviser shown, as session/agent or by its id
  • --expires DURATION: how long the connection lasts (default 24h, at most 720h)
  • --max-consultations N: how many consultations the connection carries; default the service's (50)
  • --max-tokens N: input plus output tokens admitted per consultation; default the service's: one turn of the adviser's model, its context plus the output the runner asks for
  • --max-output-tokens N: output tokens admitted per consultation; default the service's: the output one turn of the adviser's model asks for
 let an agent consult another agent of yours, after you have seen both ends and confirmed the adviser by name
ks adviser disconnect /adviser disconnect <grant> withdraw a connection: every future consultation over it stops at once
ks adviser discover /adviser discover [name] [--project ID]
  • --project ID: one project you may read instead of your own account
 the existing agents you may consult: selector, availability, the runner each reported, last seen; creates and grants nothing
ks adviser list /advisers (also /adviser list); fills in this agent and this session [--session ID] [--agent NAME]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --agent NAME: the agent (default main)
 an agent's adviser connections, live, revoked and expired, in both directions
ks agent approve (also ks approval approve) /agent approve; fills in this session <request> [--session ID]
  • --session ID: the session the request belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 approve one permission request an agent is waiting on, by its id
ks agent ask /agent ask; fills in this agent and this session <name> <question> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 ask one of an agent's connected advisers a question, as a person, and wait for its answer: "@<adviser> <question>"
ks agent create /agent create; fills in this session <name> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 create the primary agent of a session that has none
ks agent deny (also ks approval deny) /agent deny; fills in this session <request> [--session ID]
  • --session ID: the session the request belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 deny one permission request an agent is waiting on, by its id
ks agent history /agent history; fills in this agent and this session <name> [--session ID] [--last N]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --last N: only the last N entries
 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
ks agent list /agents (also /agent list); fills in this session [--session ID]
  • --session ID: the session the agents live in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 the agents of a session: name, id, activity, role, current task
ks agent logs /logs (also /agent logs); fills in this session [--session ID] [--follow] [--cursor CURSOR] [--limit N]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --follow: keep reading new lines from the cursor until the service says following ends (a session that pauses ends it) or Ctrl-C
  • --cursor CURSOR: start after this cursor (from a previous page)
  • --limit N: at most N lines per page
 the session's setup log and its agent's log from a cursor, safe to print; --follow polls until the service says it ends
ks agent open not in the app: you are in the agent's window already; /home, then Enter, opens another <name> [--session ID] [--take-control] [--view] [--no-follow] [--resume] [--project PROJECT]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --take-control: take the control lease from the window that holds it; without it a held agent is refused, never taken
  • --view: open a watching window: it follows the agent and steers nothing, so it opens beside a window that holds control and never takes it
  • --no-follow: print the window's current state and exit, following nothing
  • --resume: if the session is saved and stopped, resume it (runtime is charged again) and then open; without it a stopped session is never woken
  • --project PROJECT: narrow a search by name to one project (without --session)
 the agent window: its state, then its events as they happen
ks agent pause /pause (also /agent pause); fills in this agent and this session <name> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 save the session an agent lives in and park it, waiting until it is parked
ks agent queue cancel /agent queue cancel; fills in this agent and this session <name> [--session ID] [--preview] [--confirm QREV] [--states STATES] [--reason TEXT]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --preview: show exactly what would be cancelled, and the queue revision a confirmation must name; changes nothing
  • --confirm QREV: cancel exactly what the preview at this queue revision showed; if the queue changed since, nothing is cancelled
  • --states STATES: queued, held, or queued,held (default both)
  • --reason TEXT: why, recorded with each cancellation
 cancel an agent's pending instructions in bulk: previewed first, then confirmed by naming the preview's queue revision
ks agent queue hold /agent queue hold; fills in this agent and this session <name> [--session ID] [--finding TEXT]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --finding TEXT: what you established about the blocked instruction; required, and recorded with the decision
 record that an agent's queue stays held, and what you established
ks agent queue list /agent queue list; fills in this agent and this session <name> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 an agent's pending work in dispatch order, the instruction executing now apart, and the queue revision a move names
ks agent queue resume /agent queue resume; fills in this agent and this session <name> [--session ID] [--finding TEXT]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --finding TEXT: what you established about the blocked instruction; required, and recorded with the decision
 continue the instructions held behind a failed or unresolved one; that one is never restarted
ks agent queue show /queue (also /agent queue show); fills in this agent and this session <name> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 why an agent's queue is not moving: what blocks it, what waits behind it, what each choice would do
ks agent remove /agent remove; fills in this agent and this session <name> [--session ID] [--plan] [--execute PLAN]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --plan: plan only: what removal would cancel, release and keep; changes nothing
  • --execute PLAN: remove the agent by this plan
 remove an agent through a plan: what it cancels and keeps, then the removal naming that plan
ks agent rename /agent rename; fills in this agent and this session <name> <new-name> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 rename an agent by id; its tasks, approvals and adviser connections keep resolving
ks agent resume /resume (also /agent resume); fills in this agent and this session <name> [--session ID]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 resume the parked session an agent lives in, waiting out a save that is still completing
ks agent status /agent status; fills in this agent and this session <name> [--session ID] [--watch]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --watch: read it again every 2 seconds until Ctrl-C, which stops watching and changes nothing
 one agent's activity, queue depth and current task
ks agent stop /stop (also /agent stop); fills in this agent and this session <name> [--session ID] [--confirm NAME] [--reason TEXT]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --confirm NAME: confirm by naming the agent (required without a terminal; never implied by --yes)
  • --reason TEXT: why, recorded with the stop
 stop an agent: its instruction in flight is asked to stop and its queue is held; the session keeps running Note: in the app, name the agent to confirm: /stop --confirm <agent>.
ks agent tell /agent tell; fills in this agent and this session <name> <instruction> [--session ID] [--resume]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --resume: if the session is parked, resume it after the instruction is accepted; without it a parked session is never woken and the instruction waits, held
 queue one instruction for an agent from outside any window
ks agent view /agent view; fills in this agent and this session <name> [--session ID] [--choose N] [--confirm CHOICE]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --choose N: perform menu item N through the request the service names for it
  • --confirm CHOICE: the dialog choice that performs an item that changes the session (never preselected, never implied by --yes)
 the live window's model: header, runner, footer counts and the KS menu, as the service gives them, within 80x24
ks approval list /approvals (also /approval list); fills in this session [--session ID] [--all]
  • --session ID: the session the request belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --all: every request, decided ones too, with who decided and when
 a session's permission requests with the instruction each was asked for, what it touches and what deciding costs
ks approval show /approval show; fills in this session <request> [--session ID]
  • --session ID: the session the request belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 one permission request in full: the action, its instruction, what it touches, the cost, expiry and decision
ks check define /check define; fills in this agent and this session [--session ID] [--agent NAME] [--input PATH] [--artifact PATH] [--workdir PATH] [--kind KIND] [--timeout SECONDS] [--max-output BYTES] <name> [--] <argv...>
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --agent NAME: the agent the check belongs to (default main)
  • --input PATH: a workspace file the check's behaviour depends on (repeatable; at least one); a change to any of them needs your trust again
  • --artifact PATH: a workspace file the check produces, whose digest is recorded (repeatable)
  • --workdir PATH: the workspace directory it runs in (default the workspace root)
  • --kind KIND: check or setup (default check)
  • --timeout SECONDS: the deadline, after which its process group is killed (default 600, at most 3600)
  • --max-output BYTES: the output kept (default 256 KiB, at most 1 MiB)
 store a check: an argument vector with no shell, the files it depends on, its artifacts and bounds; runs nothing
ks check list /check list; fills in this agent and this session [--session ID] [--agent NAME]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --agent NAME: the agent the check belongs to (default main)
 an agent's checks: the exact action, the definition hash and the input sets you trusted
ks check run /check run <check> request a run of a check; it executes only over inputs you trusted
ks check show /check show <run> one run: state, inputs seen, exit status, output, artifacts' digests, the action to trust
ks check trust /check trust <run> [--confirm HASH]
  • --confirm HASH: the action hash you were shown (all of it, or the 12 characters shown); required without a terminal, never implied by --yes
 trust the exact action a run stopped at: this definition over the inputs it saw
ks file list /file list; fills in this session [path] [--session ID]
  • --session ID: the session whose workspace to read; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 one directory of a session's workspace: type, mode, size, name; secret files marked redacted
ks file show /file show; fills in this session <path> [--session ID] [--max-bytes N] [--out FILE]
  • --session ID: the session whose workspace to read; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --max-bytes N: read at most N bytes (default and maximum 1 MiB)
  • --out FILE: write the bytes to this NEW file instead of printing them
 one workspace file, at most 1 MiB, printed as safe text or written to a new file
ks result apply /apply (also /result apply) [result] [--dir DIR] [--confirm DIGEST] [--recover]
  • --dir DIR: the project root to apply to (default this project's root)
  • --confirm DIGEST: the changeset's digest (the 12 characters shown, or all of it); required without a terminal, never implied by --yes
  • --recover: put every path an interrupted apply touched back as it was
 apply an attempt's changeset to this project, only onto the recorded base, transactionally
ks result diff /diff (also /result diff) <result> [--content]
  • --content: also show the new text of each changed text file (escaped)
 what an attempt's ks-changeset.json says it changed, against its recorded base, with every path escaped
ks result download /result download <result> [--out FILE] [--force] [--extract DIR] [--task ID] [--grant-ttl DURATION] [--keep-partial]
  • --out FILE: where to place it; default the result's own file name in this directory
  • --force: replace an existing file at the target (atomically, and only with verified bytes)
  • --extract DIR: unpack a tar, tar.gz or zip result into this NEW directory after every entry passes the C09 checks
  • --task ID: refuse unless the result belongs to this task
  • --grant-ttl DURATION: how long the download grant lives (1s to 1h; default the service's 10m)
  • --keep-partial: keep an interrupted download's incomplete bytes (.ks-partial-<result>) so the same command can resume; without it they are removed
 download a result, verify its size and sha256, and place it without replacing anything
ks result list /results (also /result list); fills in this agent and this session [--task ID] [--session ID] [--agent NAME]
  • --task ID: one instruction's results
  • --session ID: every task of this session's agents; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --agent NAME: only this agent's tasks (with --session)
 the results of one task, or of a session's tasks: name, size, sha256, task, verification
ks result show /result show <result> one result: size, sha256, task and attempt, the producer's checks, the task's verification, provenance
ks task cancel /task cancel; fills in this session <instruction> [--session ID] [--reason TEXT]
  • --session ID: the session the instruction belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --reason TEXT: why you are cancelling it; optional, and recorded with the request
 end one instruction: it will not run, and the instructions held behind it stay held
ks task list (also ks task ls) /tasks (also /task list); fills in this agent and this session [--session ID] [--agent NAME]
  • --session ID: the session whose instructions to read; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --agent NAME: read one agent's queue instead of every agent's
 the instructions of a session's agents, in the order they were committed
ks task move /task move; fills in this session <instruction> [--session ID] [--before TASK] [--after TASK] [--queue-revision QREV]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --before TASK: place it just before this pending instruction
  • --after TASK: place it just after this pending instruction
  • --queue-revision QREV: the queue revision of the view you decided from (ks agent queue list prints it); without it the queue is read now and shown first
 move one queued instruction before or after another pending one of the same agent, against a queue revision
ks task reconcile /task reconcile; fills in this session <instruction> [--session ID] [--finding TEXT]
  • --session ID: the session the instruction belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --finding TEXT: what you established about the attempt; required, and recorded with the decision
 record that a running attempt's outcome could NOT be established, after the service refused its close
ks task replace /task replace; fills in this session <instruction> [--session ID] [--text TEXT] [--queue-revision QREV] [--reason TEXT]
  • --session ID: the session the agent lives in; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --text TEXT: the replacement instruction (at most 64 KiB)
  • --queue-revision QREV: the queue revision of the view you decided from; without it the queue is read now and shown first
  • --reason TEXT: why, recorded with the replacement
 replace one pending instruction: it is cancelled with its content kept and a new one takes its place, against a queue revision
ks task resume /task resume; fills in this session <instruction> [--session ID] [--checkpoint ID] [--finding TEXT] [--accept-affected DIGEST]
  • --session ID: the session the instruction belongs to; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
  • --checkpoint ID: the saved point to start the new attempt from; required, and never chosen for you
  • --finding TEXT: why you are running it again; required, and recorded with the restore
  • --accept-affected DIGEST: the digest the service printed with the exact list of other work a restore would return to that moment; consent is bound to that list and never to the word yes
 run one blocked instruction again as a new attempt from a saved point you name; it never continues the rest of the queue instead
ks task show /task show; fills in this session <instruction> [--session ID]
  • --session ID: refuse unless the instruction belongs to this session; optional, and only ever a guard
 one instruction in full: where it sits, what it says, what it last reported and what attempt exists

Sessions

CommandIn the appArguments and optionsWhat it does
ks attach not in the app: it takes over the terminal itself: run ks attach outside the app <session> interactive terminal into a running session (tmux)
ks checkpoint (also ks save) /checkpoint; fills in this session <session> [--stop]
  • --stop: park the session after the save succeeds
 save the session (durably); --stop parks it
ks exec /exec; fills in this session [--shell] <session> [--] <command...>
  • --shell: send the one argument verbatim for the session's shell to interpret (pipes, globs, variables); without it every argument reaches the program exactly as typed
 run one command in the session Note: refused in an agent session: an agent session has no shell.
ks fork /fork; fills in this session <session> [-n N] [--steer FILE]
  • -n N: how many children to branch; default 1
  • --steer FILE: a steer file applied to every child
 branch a checkpoint into diverging children
ks kill /kill; fills in this session <session> [--force]
  • --force: destroy it even without a saved checkpoint
 destroy a session (guarded: checkpoint first) Refuses: Refuses a session that has no saved checkpoint, because killing it would destroy unsaved work, and names both ways out: `ks checkpoint <id> --stop` saves and stops it, `ks kill <id> --force` destroys it anyway.
ks meter /meter; fills in this session <session> spend, budget, key sources
ks run /run [--image I] [--budget-tokens N] [--agent] [--name NAME] [--agent-name NAME] [--key KEY] [--task TEXT] [--open] [--model MODEL] [--harness HARNESS]
  • --image I: the image of a plain session; default your onboarding choice (not with --agent)
  • --budget-tokens N (also --budget): the session's token budget; default per tier (500,000 free, 2,000,000 paid); zero and negative are refused
  • --agent: start an agent session: a session, its primary agent and a machine, Ready only when the agent says so
  • --name NAME: the agent session's name (with --agent); default run-<UTC time>
  • --agent-name NAME: the primary agent's name (with --agent); default main
  • --key KEY: the provider key the agent calls with, by id or alias (with --agent); default your one enabled key for the agent's provider
  • --task TEXT: a first task for the agent, submitted once the agent is supervised (with --agent)
  • --open: open the agent's window once the agent is supervised (with --agent)
  • --model MODEL: the model the agent calls, by its exact id: one ks cruise models lists as offered (with --agent); default the service's first rung, or the harness's default model
  • --harness HARNESS: the runner the agent works inside (with --agent): claude-code, or another the catalog offers (codex calls your OpenAI key); default claude-code
 start a hosted session; with --agent, an agent session whose main agent is running and supervised
ks session brief /session brief; fills in this session <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
ks session checkpoint-policy /session checkpoint-policy; fills in this session <session> [--on] [--off] [--interval MINUTES]
  • --on: turn automatic saves on
  • --off: turn automatic saves off
  • --interval MINUTES: how often, with --on (5 to 120; default the service's 5)
 a session's automatic-save policy and where it stands; --on/--off changes it against the session's revision
ks session checkpoints /checkpoints (also /session checkpoints); fills in this session <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
ks session delete /session delete; fills in this session <session> [--plan] [--execute PLAN] [--confirm SESSION]
  • --plan: plan only: what deletion would remove, stop and retain; changes nothing
  • --execute PLAN: delete by this plan
  • --confirm SESSION: the session's id, confirming the deletion (never implied by --yes)
 delete a session record through a plan; the runtime's stop and the content's standing are reported apart
ks session fork /session fork; fills in this session <session> [--plan] [--checkpoint CHECKPOINT] [--children N] [--execute DIGEST] [--plan-id ID]
  • --plan: plan only: what the fork would do and cost; creates nothing
  • --checkpoint CHECKPOINT: the saved point to branch (with --plan); never chosen for you
  • --children N: how many children (with --plan; 1 to 8, default 1)
  • --execute DIGEST: execute the plan with this digest
  • --plan-id ID: the plan the digest belongs to (with --execute)
 plan a fork of a named saved point, then execute exactly that plan by its digest
ks session harness /session harness; fills in this session <session> [harness] [--model MODEL]
  • --model MODEL: the model on the new harness, one of its models (ks cruise models); default the harness's default 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
ks session idle /session idle; fills in this session <session> a session's idle policy and where it stands: counting, warned with the park time and countdown, deferred with the reason
ks session key set /session key set; fills in this session <session> [--key KEY]
  • --key KEY: the key's id or alias
 bind a session's provider to one of your keys by id; that key is used or nothing is
ks session list (also ks ls) /session list [--state STATE] [--all]
  • --state STATE: only running, parked or dead
  • --all: accepted for the scripts that pass it: ended sessions are listed by default now, in a final Ended group
 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
ks session migrate /session migrate; fills in this session <session> [--confirm DIGEST]
  • --confirm DIGEST: the preview's digest (the 12 characters shown, or all of it); required without a terminal, never implied by --yes
 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
ks session model /session model; fills in this session <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
ks session rename /session rename; fills in this session <session> <new-name> rename a session by id; its id and everything in it are unchanged
ks session restore /restore (also /session restore); fills in this session <session> [--checkpoint CHECKPOINT] [--reason TEXT] [--accept-affected DIGEST]
  • --checkpoint CHECKPOINT: the saved point; never chosen for you
  • --reason TEXT: why, recorded with the restore (required)
  • --accept-affected DIGEST: consent to the exact list of work the service said the restore affects
 restore a session from a named saved point, and say exactly what continues from it
ks session show /session show; fills in this session <session> one session in full; a short id is accepted when it is unique among yours
ks session usage /usage (also /session usage); fills in this session <session> a session's model use, runtime and storage, apart, with units, source and whether each figure is actual, estimated or unavailable
ks session use /session use [session] [--clear] [--trust-repo] [--confirm SESSION]
  • --clear: remove this project's binding
  • --trust-repo: adopt the session this repository's .keepstate/session.json names, once you confirm it with --confirm
  • --confirm SESSION: the id of the session the repository names; required with --trust-repo, never implied by --yes
 bind this project to a session, so commands without --session mean it: per account, project root and control plane
ks wake (also ks resume) /wake; fills in this session <session> resume a parked session (mid-sentence) Note: in the app /resume is ks agent resume; type /wake for a plain session.

Cruise

CommandIn the appArguments and optionsWhat it does
ks cruise apply /cruise apply <job> [--dir DIR] [--confirm DIGEST]
  • --dir DIR: the project root to apply to (default this project's root)
  • --confirm DIGEST: the changeset's digest (the 12 characters shown, or all of it); required without a terminal, never implied by --yes
 apply an accepted job's result to this project file by file, only onto the base each file was changed from, transactionally Note: in the app /apply is ks result apply; type /cruise apply in full.
ks cruise approve /cruise approve [--key PROVIDER=KEY]
  • --key PROVIDER=KEY: the key to bind for a provider with several enabled keys (repeatable)
 lock the draft, binding the upload selection, the check's inputs and one provider key per ladder provider into the digest
ks cruise artifact /cruise artifact <job> [--out FILE]
  • --out FILE: where to write it; default JOB.tar.gz
 download the accepted tarball Refuses: Verifies the download's sha256 against the job's artifact_sha before the named file exists; a mismatch is refused and nothing is written.
ks cruise cancel /cruise cancel <job> cancel a job
ks cruise draft approve /cruise draft approve <draft> [--confirm DIGEST]
  • --confirm DIGEST: the manifest digest you reviewed (all of it, or the 12 characters shown); required without a terminal, never implied by --yes
 run a draft by confirming the digest of the exact manifest shown, computed here
ks cruise draft create /cruise draft create; fills in this session [--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]
  • --dir FOLDER: the folder to send: packed here by the selection ks cruise init uses; what the policy leaves out is named and never sent
  • --archive FILE: a .zip, .tar.gz, .tgz or .tar to send as it is (at most 100 MiB); one top folder holding everything is removed by the service
  • --session SESSION: one of your sessions, running or paused: the service copies its workspace's files (a short id is accepted when it is unique among yours)
  • --root FOLDER: with --session: the folder of the session's workspace the job works on (default the workspace itself)
  • --proposal PROPOSAL: a job an agent proposed: the service copies the files of the proposal's session and drafts the job on the proposal's terms, every digest recomputed
  • --goal TEXT: the goal the agent is given
  • --paths GLOB...: the paths an attempt may change; default every file except the check's files and .keepstate
  • --check RUNNER: the check to pin and run: pytest, go or node; needed when tests of more than one ecosystem are found
  • --allow PATH...: review a sensitive or ignored path into the job (repeatable); fixed for the draft's life
  • --ladder family:model,...: the rungs in order; default the model table's default ladder
  • --spend USD: the spend limit in dollars; default 2
  • --key PROVIDER=KEY: the key a provider of the ladder uses, when it has several enabled keys (repeatable)
 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
ks cruise draft discard /cruise draft discard <draft> discard a draft; its copy of the files is deleted and it never runs
ks cruise draft list /cruise draft list · the account's open drafts, newest first: state, goal, files, manifest digest and how long each is kept
ks cruise draft set /cruise draft set <draft> [--goal TEXT] [--paths GLOB...] [--any-file] [--check RUNNER] [--ladder family:model,...] [--spend USD] [--key PROVIDER=KEY]
  • --goal TEXT: the goal the agent is given
  • --paths GLOB...: the paths an attempt may change
  • --any-file: any file may change, except the check's files and .keepstate
  • --check RUNNER: the check to pin and run: pytest, go or node
  • --ladder family:model,...: the rungs in order
  • --spend USD: the spend limit in dollars
  • --key PROVIDER=KEY: the key a provider of the ladder uses (repeatable)
 change a ready draft's goal, paths, check, ladder, spend limit or keys; the manifest and its digest are drafted again
ks cruise draft show /cruise draft show <draft> [--manifest] [--verify]
  • --manifest: print the manifest's canonical bytes, the bytes its digest is taken over
  • --verify: download the draft's archive and recompute its sha256, tree, selection, check inputs, tests and configuration digests against the manifest
 one draft: what was read and left out, the check, the terms and the digest computed here; --verify recomputes every digest from its archive
ks cruise init /cruise init [--allow PATH...] [--goal TEXT] [--tests CMD] [--check RUNNER] [--paths GLOB...] [--ladder family:model,...] [--spend USD]
  • --allow PATH...: review a sensitive or ignored path into the upload (repeatable); see ks cruise preview
  • --goal TEXT: the goal the agent is given; without it, the draft's previous goal, else "make the check pass: CMD"
  • --tests CMD: the command that decides done, when init should not detect it (pytest, npm test, go test)
  • --check RUNNER: the check to pin and run: pytest, go or node; required when tests of more than one ecosystem are found
  • --paths GLOB...: the paths an attempt may change; default every tracked file except the tests and .keepstate
  • --ladder family:model,...: the rungs in order; default the model table's default ladder
  • --spend USD: the spend ceiling in dollars; default 2
 draft the acceptance manifest from the repository into .keepstate/cruise.json
ks cruise logs /cruise logs <job> the event stream, one event per line: seq, ts, type, detail Note: in the app /logs is ks agent logs; type /cruise logs in full.
ks cruise models /cruise models [--cached]
  • --cached: show the last catalog read, labelled CACHED with its version and served_at; makes no request
 the model catalog: exact ids, family, provider route, rung, runner compatibility as stated, price standing and your key route
ks cruise preview (also ks workspace preview) /cruise preview [--allow PATH...]
  • --allow PATH...: review a sensitive or ignored path into the upload (repeatable); never a symlink or .git
 what an upload would carry and what it would not, with reasons: names and sizes, never content
ks cruise proposal approve /cruise proposal approve <proposal> [--confirm DIGEST]
  • --confirm DIGEST: the manifest digest you reviewed (all of it, or the 12 characters shown); required without a terminal, never implied by --yes
 run a proposed job by confirming the digest of the exact manifest shown
ks cruise proposal decline /cruise proposal decline <proposal> [--reason TEXT]
  • --reason TEXT: why, recorded with the decline
 decline a proposed job; it never runs
ks cruise proposal list /cruise proposal list; fills in this session [--session ID]
  • --session ID: the session whose agents proposed; a short id is accepted when it is unique among yours; without it, this project's binding (ks session use)
 a session's proposed Cruise jobs, newest first: state, goal, manifest digest and the job each became
ks cruise proposal show /cruise proposal show <proposal> one proposed job: its manifest in full, the digest the service states and the digest computed here, and its job
ks cruise result /cruise result <job> [--download] [--out FILE]
  • --download: also download the artifact: its sha256 and, for a verified result, the tree it holds are checked against the candidate the receipt verified before anything is written
  • --out FILE: where --download writes; default JOB.tar.gz; an existing file is never written over
 an accepted job's result: the badge exactly as served, the provenance chain, and every limitation
ks cruise resume /cruise resume <job> [--ladder family:model,...]
  • --ladder family:model,...: the rungs to continue on, in order
 resume a job from review, on the same or a wider ladder
ks cruise review /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
ks cruise run /cruise run [--separate-upload]
  • --separate-upload: create the job without its workspace, then send the packed archive's raw bytes as its own upload (PUT /api/jobs/{id}/workspace); the job cannot start until the upload is stored, and the archive is kept until it is, so ks cruise upload JOB can send it again
 upload the workspace and the locked manifest; start the job Refuses: 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.
ks cruise status /cruise status [job] [--watch]
  • --watch: follow the job live: its plain state, the attempt in flight, a pending verifier result, the last save point, spend kept apart (unavailable is never $0) and the next actions, re-read as events arrive at the pace the service names; Ctrl-C ends only the watch
 the job (or the newest): state, rung, each attempt, save points, spend, verdict, artifact
ks cruise upload /cruise upload <job> [--from FILE]
  • --from FILE: the archive to send instead of the kept one; it must be the exact archive the job's manifest names (sha256 and size), or nothing is sent
 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 Refuses: 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.

Keys and setup

CommandIn the appArguments and optionsWhat it does
ks key add /key add [--provider PROVIDER] [--alias NAME]
  • --provider PROVIDER: anthropic, openai or openrouter
  • --alias NAME: a name for the key
 store a provider key read from standard input; it is never an argument and never comes back Note: reads the key from standard input, which a / command does not get: run it in a terminal outside the app.
ks key delete /key delete <key> plan a key deletion, then execute it with --yes
ks key disable /key disable <key> refuse new admissions with a key; in-flight usage is reconciled
ks key enable /key enable <key> allow new admissions with a key
ks key list /keys (also /key list) · your keys: id, provider, alias, last four characters, enabled or disabled
ks key show /key show <key> one key's metadata
ks preflight /preflight [--provider PROVIDER] [--mode MODE] [--check COMMAND] [--ladder FAMILIES]
  • --provider PROVIDER: the provider the run will use (default anthropic)
  • --mode MODE: what you are about to start: cruise (default) or agent
  • --check COMMAND: the acceptance check a Cruise job would run (default: the one in .keepstate/cruise.json)
  • --ladder FAMILIES: the model families a Cruise job would climb, comma-separated (default: the draft's ladder)
 what a run needs and what is missing: identity, keys, credit, capabilities, and the local upload preview; starts nothing
ks project configure /project configure; fills in this session [--project ID] [--session ID] [--file PATH] [--confirm DIGEST]
  • --project ID: the project (default: the project of --session or of this project's binding)
  • --session ID: a session of the project; without it, this project's binding (ks session use)
  • --file PATH: the defaults file (default .keepstate/project.json at the project root)
  • --confirm DIGEST: trust the proposal with this digest (the 12 characters shown, or all of it); never implied by --yes
 propose .keepstate/project.json as the project's defaults, see the exact changes, and trust that digest only if you confirm it

Account and this client

CommandIn the appArguments and optionsWhat it does
ks completion /completion <shell> print a shell completion script generated from the command schema
ks doctor /doctor · connectivity, token, version
ks login not in the app: signing in opens a browser: run ks login outside the app [--ctl URL]
  • --ctl URL: the control plane to sign in to; default https://ctl.keepstate.ai
 sign in (browser device flow)
ks logout not in the app: it removes the sign-in the app is using: run ks logout outside the app · remove the stored token
ks operation show /operation show <operation> read an operation back by its id or key: state, result, timestamps
ks operation wait /operation wait <operation> wait, within the bound, for an operation to finish and print its result
ks reference /reference · print the command reference as a Markdown table generated from the command schema
ks uninstall /uninstall · how to remove ks completely
ks update /update [--require-provenance]
  • --require-provenance: replace nothing unless gh verifies the new binary's build provenance
 self-update (checksum-verified, provenance-checked with gh)
ks version /version [--verify]
  • --verify: check this binary's GitHub build-provenance attestation with gh; without gh, or on any error, it reads NOT verified and exits non-zero
 print the version; with --verify, check this binary's build provenance

Agent sessions and plain sessions

The agent, task, result, approval and adviser commands work on agent sessions (ks run --agent, or n in the app). An agent session has no shell, so ks exec and ks attach are refused there. ks wake resumes it as ks agent resume (/resume) does, ks fork names ks session fork and its plan, and ks kill shows the session's deletion plan and, in a terminal, deletes it once you type the session's name, as ks session delete does. A plain session (ks run without --agent) is driven with the session commands in a terminal, and ks attach relays its terminal. See Runners.

Spotted an error on this page? Tell us, and we will correct it.

Report it
← previous Architecture and the state boundary next → API