istok run

istok run works with runs: individual attempts at a task. Agents do all of this through MCP; the CLI is for inspection, troubleshooting, and direct control. For the concepts, see Tasks and runs and Validation.

Commands

Run IDs are canonical UUIDv7 values.

List runs

istok run list
istok run list --task 12
istok run list --status active --limit 20

Status values are active, succeeded, failed, blocked, cancelled, and abandoned; --status can be repeated.

run list covers the current project. To see runs across all projects, with running and stale runs told apart, use the runs feed in the web UI.

Show a run

istok run show RUN_ID

Shows the run’s state, lease, revision, context snapshot, executions, validations, and artifacts. Use it to get the current lease or revision before another operation. The web UI shows the same run, with the snapshot laid out as What the agent saw.

Leases

Commands that execute or change work inside an active run need its current lease:

istok run heartbeat RUN_ID --lease LEASE

The lease comes from the claim or from recovery. If it changes, use the new one.

Heartbeat

istok run heartbeat RUN_ID --lease LEASE

Extends the lease so the run is not considered stale while long work continues.

Execute a command

istok run exec RUN_ID --lease LEASE -- pnpm lint
istok run exec RUN_ID --lease LEASE -- \
  go test ./internal/orders -run TestGetOrder

Everything after -- is the command and its arguments. The command and its output are stored with the run.

Validate a run

istok run validate RUN_ID --lease LEASE -- go test ./...
istok run validate RUN_ID --lease LEASE -- pnpm test

The result becomes validation evidence that finish and istok task done can refer to. --summary sets the validation summary; without it, the summary is derived from the result.

Options for exec and validate

istok run exec RUN_ID \
  --lease LEASE \
  --cwd packages/api \
  -- pnpm test

Managed commands receive an allowlisted environment from the parent process, not the whole environment, plus ISTOK_RUN_ID, ISTOK_EXECUTION_ID, and ISTOK_PROJECT_ROOT. See Configuration.

Use --allow-dangerous only when the operation genuinely requires it; the reason is recorded:

istok run exec RUN_ID \
  --lease LEASE \
  --allow-dangerous \
  --override-reason "Required for the requested migration" \
  -- COMMAND

Artifacts

istok run artifact list RUN_ID
istok run artifact verify ARTIFACT_ID --run RUN_ID

Artifacts keep files produced by a run associated with it. Their contents live in Istok’s artifact store, outside the database.

Finish a run

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision REVISION \
  --status succeeded \
  --summary "Implemented and validated."

finish requires the current lease, the expected revision, a terminal status (succeeded, failed, blocked, or cancelled), and a summary. Finishing as succeeded requires a passed validation and no managed execution still running.

When no check applies, finish without validation explicitly:

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision REVISION \
  --status succeeded \
  --summary "Documentation-only change." \
  --allow-unvalidated \
  --override-reason "No automated checks apply to this change"

Recover a run

istok run recover RUN_ID --reason "Continuing interrupted work"

Recovery gives the same run a new lease. It only works for the actor that owns the run; use the returned lease afterwards.

--force replaces the current actor’s own lease before it expires, for example after losing the token:

istok run recover RUN_ID \
  --force \
  --reason "Replacing stale local session"

Abandon a run

istok run abandon RUN_ID \
  --expected-revision REVISION \
  --reason "Implementation approach needs to be restarted"

Abandoning ends the attempt, keeps it in the history as abandoned, and leaves the task open for another claim. It does not need the lease, so it works for a run whose agent is gone.

The CLI command works on any active run, so check with istok run show that nobody is still working on it. The web UI abandons only stale runs, and the MCP tool run_abandon is available only with the supervisor or admin profile.

Recording work done outside Istok

exec and validate run commands themselves. When a command runs elsewhere, record it instead:

istok run execution start RUN_ID --lease LEASE -- COMMAND
istok run execution finish EXECUTION_ID --run RUN_ID --expected-revision REVISION --status succeeded --exit-code 0
istok run validation record EXECUTION_ID --run RUN_ID --source attested --status passed --command "COMMAND" --summary "Checked manually"

These commands do not start a process. execution finish also accepts --duration-ms, --signal, and --timed-out; validation record accepts --exit-code and --duration-ms. A validation recorded this way has the source attested, which keeps it distinguishable from validations Istok derived from a command it ran itself.

Revisions

finish, abandon, and execution finish take --expected-revision. If the run or execution changed since you read it, the command fails instead of overwriting newer state; run istok run show and retry with the current revision.

JSON output

Run JSON results, in the CLI and in MCP, use "schema_version": "2". See JSON output.

Help

istok run exec --help
istok run validate --help
istok run finish --help
istok run recover --help
istok run abandon --help