Item verbs
kraft item acts on a work item. Wherever a command takes an ID, you can omit it inside that item's worktree. See the CLI overview for output format and --json.
Approve, reject, pause, resume, retry, raise a budget
kraft item approve
kraft item reject --note "the plan skips migrations"
kraft item pause
kraft item resume --steer "try the other adapter"
kraft item retry
kraft item raise-budget --usd 25
| Command | Effect |
|---|---|
item approve | Approves the pending gate. --gate names a gate when more than one could apply. --digest pins the approval to a chain revision, as kraft view artifact printed it. |
item reject | Rejects the pending gate. --note records why. --gate names the gate when more than one is pending. --node N re-enters the chain at node N instead of the gate's default. |
item pause, item resume | Pause stops the whole work item. resume --steer gives the paused agent a message. |
item retry | Re-runs the node a stopped item stopped on. It is the only way back onto a stopped item. --steer carries a message into the retry's prompt. |
item raise-budget | Raises the item's own dollar cap to --usd N and retries it, like the board's Raise budget button. --usd none lifts the cap. It works only on an item that cap stopped: a stop on the policy's budget_usd or token_budget, which set-policy sets, or on budget.daily_usd, is refused; see Raising a cap. |
Filing a work item
kraft item create "fix the flaky test" --description "..."
kraft item create "fix it now" --autostart
kraft item create "ship the thing" --spec .engineering/specs/x.md
kraft item create "backport the fix" --base-branch release/1.2
kraft item create "fix the parser" --repo ~/code/app --chain quick-task --no-auto-gate
kraft item create "small fix" --skip-nodes spec,plan --budget 5
kraft item create "tuned fix" --node-override implementation.attempts=2
| Flag | Effect |
|---|---|
| (none) | Files the item paused. A person starts it. |
--autostart | Starts the item at once. A Kraft worker session is refused. |
--spec, --plan | Attaches a document and skips the node that would write it. |
--base-branch | Starts from, and merges into, that branch. |
--repo, --chain | Targets another connected repo or chain. Without --chain, the item gets the repo's default_chain_template. A relative --repo is read from where you stand. |
--implements ID | Closes the named issue in your optional beads issue tracker when the item completes. |
--auto-gate (default), --no-auto-gate | An agent reviews each gate that declares auto_review before a human is asked. --no-auto-gate turns that off for this item. Items filed by a cron trigger, POST /api/triggers or auto-intake have it off. |
--skip-nodes | Skips the named nodes. |
--budget USD | Sets the item's dollar cap. --budget none lifts it. |
--node-override N.FIELD=VALUE | Overrides one field on node N. |
--policy KEY=VALUE | Gives the item its own policy override. Repeatable. |
--repo must name a repo you have already connected with kraft repo connect.
Kraft refuses any other path and names that command.
Addressing work by path
Retry, skip and resume address chain work by its path: node, node.step or
node.step.task. A tasks: node's one step is main, so the path to its
implement task is implementation.main.implement. kraft view show --json
lists every path.
kraft item retry --path verification.review
kraft item retry --path verification.review.code_review
kraft item retry --path spec
kraft item retry --restart
kraft item resume --steer "keep the old API" --steer-task verification.review.code_review="check the auth module first"
kraft item skip --path verification.review.code_review
| Command | Effect |
|---|---|
retry --path node.step | Re-runs that step and everything after it. |
retry --path node.step.task | Re-runs that task. Its finished siblings stand. |
retry --path node | Re-runs a node that already completed, and everything after it. |
retry --restart | Re-runs the whole chain from its first node. |
resume --steer | Sends a message to every paused agent task. |
resume --steer-task PATH=TEXT | Sends a message to one paused agent task. |
skip --path | Skips only that task. Its siblings keep running. |
A retry keeps everything the earlier run did and runs on a new run fork. It reopens every gate it has to rerun. A gate before the retried work keeps its decision.
A paused agent task resumes its own session when its harness supports it, and is told the steer. Otherwise it restarts with its brief and the steer. You see a refusal when you:
- steer an item that is still running (pause it first);
- steer an item whose pause stopped no agent task, such as a test run or a CI wait;
- name a
--steer-taskthat is not a paused agent task.
Reviewing a change
kraft item comment --body "this leaks the connection" --file src/db.py --lines 40-46 --label must-fix
kraft item comment --body "why not a set here?" --file src/db.py --lines 12 --label question
kraft item comment --body "small fix" --file src/db.py --lines 40 --suggest "conn.close()"
kraft item comment --reply <thread-id> --body "looks right now"
kraft item resolve <thread-id>
kraft item reopen <thread-id>
kraft item review comment --summary "a few notes, nothing blocking"
kraft item review approve
kraft item review request-changes --summary "please address the must-fix"
| Command | Effect |
|---|---|
item comment | A draft review comment: a new thread, or --reply THREAD to answer one. --file/--lines A[-B]/--side (default new) anchor it to a line range; without them it is about the whole change. --label is must-fix, question or nit. --suggest needs --lines, and gives a suggested replacement for that range. |
item resolve, item reopen | Mark a thread resolved, or reopen it. |
item review | Send your drafted comments with an outcome: comment (queues them for the next agent; never interrupts), approve (needs a pending gate), or request-changes (redoes the work now, at a pending gate or not). --summary adds a note above the threads. --node overrides where request-changes re-runs; left out, it is derived from the threads. |
Drafts are invisible to every agent until a review sends them. must-fix
blocks every gate approval until resolved. See Reviewing a
change for the full picture, and kraft view threads/kraft view compare in the view verbs to read
before you comment.
Less common item verbs
kraft item skip --note "already fixed upstream"
kraft item escalate --message "the fix loop keeps missing the same edge case"
kraft item escalate --message "..." --new-thread
kraft item set-chain --template quick-task
kraft item set-attachments --spec specs/x.md
kraft item set-attachments --drop spec
kraft item set-overrides --model opus --effort high
kraft item set-overrides --clear
kraft item mr-label --id <id> release::patch
kraft item abandon --yes
kraft item complete --reason "shipped by hand"
kraft item cancel --reason "superseded by #412"
| Command | Effect |
|---|---|
skip | Advances past the current node or gate without running it. |
progress N | kraft item progress N is called by a worker session to report it started plan task N. You do not run it by hand. |
reply THREAD | kraft item reply THREAD --body "..." [--claim fixed|answered|should_fix] is called by a worker session to answer a review thread. You do not run it by hand. |
escalate | The manual counterpart of the board's auto-escalation. Asks an agent to help resolve a needs_human stop. --new-thread starts a fresh agent session instead of continuing the latest thread. |
set-chain | Switches a not-yet-started item's chain. |
set-attachments | Revises a not-yet-started item's spec or plan. --drop KIND removes it and restores its gate. |
set-overrides | Sets the item-wide --model and --effort (low, medium, high, xhigh or max), and --escalate-model for a fix loop's escalation model. --clear returns to the template's own binding. |
mr-label | Relabels the merge request with one or more labels given as arguments. --id picks the item. This re-creates its pipeline. |
abandon | Drops the item and reclaims its worktree. It destroys uncommitted work, so --yes is required. |
complete | Ends the item as completed. Requires --reason. Add --close-beads to close its linked beads issues. |
cancel | Ends the item as cancelled. Requires --reason. The worktree stays. |
complete and cancel stop whatever is running and record the reason on the
item's timeline.
One node's agent tasks
kraft item set-node-override --node N changes one node of one item until
that node starts. After that, Kraft refuses the change.
kraft item set-node-override --node verify --auto-escalate-stuck
kraft item set-node-override --node implementation --model opus --effort high
kraft item set-node-override --node implementation --extra-prompt "Keep the migration backwards compatible."
It accepts these flags:
--auto-escalate,--no-auto-escalate: arms or disarms agent review of this node's auto-escalate gates.--auto-escalate-stuck,--no-auto-escalate-stuck: arms or disarms auto-escalation when this node stops stuck.--auto-escalate-delay-s SECONDS: the delay before this node's auto-escalation fires.--clear: resets the node to the template's own binding.--model,--effort: what every agent task in the node launches with. From highest precedence to lowest: this node override, the item-wideset-overrides, the task's ownmodel:andeffort:in the library, the repo'smodels:(model only), then the harness profile'sdefaults:. A value the node's harness does not accept is refused when you set it, not at launch. A gate'sauto_reviewuses the item-wide values only.--extra-prompt TEXT: appended to the instruction of every agent task the node runs, after the task's own prompt and brief. It never replaces them. It does not reach a gate'sauto_reviewor the interactive escalation turn. At intake,N.extra_prompt=...is taken as written, not read as YAML.
The override is stored on the item. It does not edit the chain. attempts and
wall_clock_s have no flag here. Set them at filing with
kraft item create --node-override N.attempts=2.
A work item's own policy
kraft item create --policy KEY=VALUE (repeatable) and kraft item set-policy give one work item its own policy override, without touching its
chain or any other item. FIELD=VALUE applies item-wide. PATH.FIELD=VALUE
applies to one node, step or task and everything under it. Values are read as
YAML, so deny_tools=[WebFetch] is a list.
kraft item create "quick fix" --policy time_cap_minutes=45 --policy merge_request_feedback.ci.await_ci.total_time_cap_minutes=60 --policy verification.max_attempts=4
kraft item set-policy --policy merge_request_feedback.ci.await_ci.total_time_cap_minutes=60
kraft item set-policy <id> --policy max_attempts=2
kraft item set-policy --clear
set-policy replaces the whole override. The fields are those described in
Configuration:
| Fields | Behavior |
|---|---|
timeout_minutes, max_attempts, allowed_harnesses | Move within the administrator maxima and win over what the chain set. max_attempts applies to execution nodes only. |
allowed_tools, deny_tools, sandbox | Only tighten. A list intersects with what each task already allows. |
time_cap_minutes, total_time_cap_minutes, token_budget, budget_usd | Item-wide caps. Raise one above the chain's, up to maxima.work_item, to unstick a capped item before a retry. budget_usd=none clears the dollar cap, the one way past a stop on unknown spend; see Raising a cap. |
On a path, you can pass that level's default up to its level's maximum. Kraft refuses a value above what the chain or the item already gives that scope, naming both. A wait task's total cap is its timeout.
Kraft refuses a value past its maximum, a path the chain does not have, and a key that is not a policy field, naming the field.
set-policy works on any item that has not ended. On a running or waiting
item it takes effect from the next node the item enters and from the next
check of a wait it is parked on. The new timeout counts from when the wait
started.