CLI
kraft with no arguments starts the server. Every other command talks to a
running server. Verbs live in four groups: item acts, view reads, repo
manages repositories and their worktrees, and admin runs this machine's
server. Typing an old flat verb (kraft list) prints where it moved.
kraft <group> <verb> --help prints every flag for one verb. Each group page
describes its verbs and the flags that change what they do. Wherever a
command takes a work item ID, you can omit it when you run the command from
inside that item's worktree.
Find a verb by what you want to do
Each command links to its entry.
Filing work
| I want to | Command |
|---|---|
| Connect a repo to Kraft | kraft repo connect |
| Check that a repo's setup and test commands work | kraft repo connect --verify |
| Stop tracking a repo | kraft repo disconnect |
| File a work item | kraft item create "title" |
| File it with a spec or plan I wrote | kraft item create "title" --spec PATH --plan PATH |
| File it and start it at once | kraft item create "title" --autostart |
| Revise a spec or plan before the item starts | kraft item set-attachments |
| Switch the chain of an item that has not started | kraft item set-chain |
| Start an item that was filed paused | kraft item resume |
Watching
| I want to | Command |
|---|---|
| See the board | kraft view list |
| See where one item stands | kraft view show |
| Find a spec, plan or summary | kraft view search "query" |
| List an item's specs, plans and summaries, or read one | kraft view docs, kraft view doc ID |
| Follow the agent's log | kraft view logs -f |
| See what happened to an item, in order | kraft view events |
| Watch the board live | kraft view watch |
| See the repos Kraft knows | kraft repo list |
| Go to an item's worktree | kraft repo path or kraft repo open |
| See what the worktrees use, item by item | kraft view storage |
At a gate
| I want to | Command |
|---|---|
| Read the document the gate is about | kraft view artifact |
| Read the change | kraft view diff |
| Compare two attempts, or the change since my last review | kraft view compare |
| Approve | kraft item approve |
| Reject, and say why | kraft item reject --note "why" |
| Comment on a line of the change | kraft item comment |
| Send my comments with an outcome | kraft item review |
| List review threads | kraft view threads |
| Mark a thread resolved, or reopen it | kraft item resolve, kraft item reopen |
| Pass a gate without running it | kraft item skip |
| Label an item's merge request | kraft item mr-label |
When it stops
| I want to | Command |
|---|---|
| See why it stopped | kraft view show, then kraft view logs |
| Run the stopped node again | kraft item retry |
| Redo one step or task, or the whole chain | kraft item retry --path PATH, --restart |
| Give it more budget | kraft item raise-budget --usd N |
| Raise a time or token cap | kraft item set-policy |
| Steer an agent that is paused | kraft item resume --steer "..." |
| Pause a running item | kraft item pause |
| Ask an agent to help with the stop | kraft item escalate --message "..." |
| Skip the node it stopped on | kraft item skip |
| Pick another model or effort for it | kraft item set-overrides, or kraft item set-node-override |
| End it as done, or as cancelled | kraft item complete, kraft item cancel |
| Drop it and delete its worktree | kraft item abandon --yes |
Housekeeping
| I want to | Command |
|---|---|
| Archive finished items and free their worktrees | kraft item archive |
| Bring an archived item back under Done | kraft item restore |
| Check that the server is up | kraft admin health |
| Check the whole install | kraft admin doctor |
| Start, stop or restart the server | kraft admin start, stop, restart |
| Run Kraft as a service | kraft admin install-service |
| Install the newest release | kraft admin update |
| Reread the templates and policy after editing them | kraft admin reload |
| Check my chains | kraft admin templates lint |
| Read a chain or a library component | kraft admin templates show, templates library |
| See the harness profiles and what selects each | kraft admin harnesses |
| Rescan documents into the search index | kraft admin reindex |
| Register Kraft with an agent | kraft admin init |
kraft item progress and kraft item reply are called by a worker, not by you.
Output format
Every read and action verb accepts --json, which prints the raw API payload.
It is the same call the matching MCP tool makes, but not
always the same value:
kraft view show --jsonprints the item's full detail (its effective chain, worker sessions and stop), where theget_work_itemtool hands an agent a trimmed item.kraft item create --jsonprints a trimmed object, not the raw payload:id,statusandtitle, plusslots(when--autostartqueued the item),repo_warning,bead_warningorduplicate_warningwhen one applies.kraft view list --jsonis scoped to the repo you are in unless you pass--allor--repo;list_work_itemsis never scoped.
These verbs do not print the payload:
| Verb | Use instead |
|---|---|
view watch | kraft view events --json (watch redraws a board rather than returning a value) |
repo path | kraft view show --json (path prints one plain line meant for cd) |
admin start, stop, restart, update | None; these print status lines. |
admin install-service, uninstall-service | None. |
admin mcp, admin permission-hook | None; these speak a protocol on stdio. |
admin addon enable, disable | kraft admin addon list --json (these print one line). |
admin init | None. It accepts --json and ignores it; it prints one kraft: wrote PATH line per file. |
Without --json
| Verbs | What they print |
|---|---|
kraft item approve, reject, pause, unblock, resume, retry, raise-budget, skip, complete, cancel, escalate | One line saying what they did, most of them with where the item stands now, such as approved spec_approval on 4f2c…; the item is now running. |
kraft item review approve or request-changes at a pending gate | The same one line. |
kraft item review request-changes or comment, with no gate pending | The review's fields as key value lines. |
kraft item abandon, and every set-* verb except set-chain | The same key value lines. |
kraft item set-chain | The chain the item now runs. |
kraft item archive | The preview as a table with a total, then one line per item. |
kraft item restore | One line saying what was restored. |
kraft item comment, resolve, reopen | The thread and where it sits. |
The item itself is in --json, or in kraft view show.
The reads you script against print as follows: view list, view show, repo list, admin health, admin doctor and item create. With --json, all but item create print the API's own answer: see the HTTP API pages.
kraft view logs --json and kraft view events -f --json print NDJSON, one
object per line, because a stream has no end on which to close an array.
kraft view events --json without -f prints one JSON array.
Shell completion
kraft completes verbs with argcomplete,
in any shell argcomplete supports. Register it by adding
eval "$(register-python-argcomplete kraft)" to your shell's rc file.
In this section
- Item verbs: file, approve, reject, pause, unblock, resume, retry, skip, escalate, and set policy on a work item.
- View verbs: read the board, follow a running item, and review its diff and documents.
- Repo verbs: connect repositories and reach their worktrees.
- Admin verbs: run, check, update, and configure this machine's server.