--profile <name> to select it and --json for machine-readable responses.
Replace angle-bracket placeholders with returned UUIDs or versions before use.
Create, start, and request attention
assigned at state version 1. It has no --state,
--initial-state, or --start flag. The separate transition records running;
these commands do not launch a harness. Use current returned versions for later
writes; the example assumes no intervening changes.
Attention creation atomically moves running|waiting to needs_human. Read the
attention item to see a human’s eventual resolution outcome and summary, the
attention version, and the current execution state/version. Resolution and
requester cancellation return the execution to waiting. They do not resume a
model turn or harness. Harness acceptance and an explicit, version-fenced later
waiting -> running transition belong to the separate resume integration.
Inspect executions and attention
--issue <issue-id-or-key>, --agent <member-id|self>,
--state <assigned|running|waiting|needs_human|succeeded|failed|cancelled>,
--active <true|false>, --harness-kind <kind>, --updated-after <ISO-8601>,
--limit, and --offset. Create also accepts optional --harness-kind,
--external-run-id, and --external-run-url <https-url>.
Attention list defaults to --status open and accepts open|resolved|cancelled,
--execution <execution-id>, --kind, --limit, and --offset. It always uses
relevant mode. The CLI has no recovery filters, human resolve, administrator
retarget, or administrator cancellation commands. See the
attention API for operator operations.
Both lists request shape=cli and preserve the server envelope:
{ resource, items, total, limit, offset, nextOffset, truncated, hint }.
The default limit is 25; allowed limits are 1–100 and offsets are 0–10,000.
Follow nextOffset for the next page. Execution detail returns { execution };
attention detail returns { attention }. Writes preserve the canonical server
response. Server permissions and concealed 404 responses remain authoritative.
Transition and link evidence
execution transition <execution-id> requires --to,
--expected-state-version <positive-int>, and --idempotency-key <key>.
Generic transitions cannot enter or leave
needs_human. Use attention creation
for the pause and attention resolution/readback for its outcome. The server
still decides whether a transition is valid from the current state.
Each summary has a file alternative: --state-summary-file <path|->,
--outcome-summary-file <path|->, and --failure-summary-file <path|->.
Use - for stdin; inline and file inputs for one field are mutually exclusive.
comment|activity_event|issue_pr_link|attachment. The target
UUID must identify an existing authorized object on the execution issue. This
command links references; it cannot upload files, URLs, raw logs, or text.
Attention fields and cancellation
Create requires--execution, --expected-state-version, --kind, --title,
--request-summary, --why-needed, --resume-condition, and --idempotency-key.
Kinds are exactly approval|clarification|access|decision|destructive_action|other.
Choose exactly one target:
--target-member <member-id>: exact member UUID.--target-team <team-id-or-resolvable-team>: existing team resolver.--target-project-admins: administrators of the issue’s project.
--request-summary-file <path|->,
--why-needed-file <path|->, and --resume-condition-file <path|->. Do not combine
inline and file values for the same field. Never include credentials, access
tokens, private paths, prompts, logs, or other secrets in any attention field.
Only the requesting agent can use requester cancellation:
cancelled and the execution as waiting.
Reconcile errors and uncertain writes
Supply explicit idempotency keys and expected versions. The CLI never generates a replacement key or fetches a new version to make a rejected write succeed. Argument errors exit 2; API failures and uncertain outcomes exit 1. Deterministic API errors preserve the server status, code, and details, includingSTALE_STATE_VERSION, STALE_ATTENTION_VERSION, IDEMPOTENCY_CONFLICT,
INVALID_TRANSITION, and ATTENTION_CONTRACT_REQUIRED.
A timeout, transport failure, or HTTP 5xx after a POST attempt means the outcome
is uncertain. The CLI does not automatically retry.
Stop if the requested result is already visible. If readback does not establish
the result and replay is needed, keep the identical operation, body, and key.
If changed authoritative state or versions make the result ambiguous, stop for
caller/operator reconciliation. Do not force another transition or substitute a
new key.