sdtk-agent — Command Reference

Durable DAG orchestration CLI. Guide: SDTK-AGENT.

npm install -g sdtk-agent-kit   # included in sdtk-kit
sdtk-agent --help

All run-scoped commands accept --project-path <path> (defaults to the CWD) and most support --json for machine-readable output. Run sdtk-agent <command> --help for command-specific options.

Setup & validation

sdtk-agent init

Initialize the runtime ledger root (.sdtk/agent-runtime/).

sdtk-agent init --project-path ./my-project

sdtk-agent workflow validate

Validate a workflow JSON DAG — cycle detection, unsafe paths, schema.

sdtk-agent workflow validate --file ./workflow.json

Runs

sdtk-agent run start

Create a new run. Ledger-only — nothing executes until run continue.

sdtk-agent run start \
  --project-path ./my-project \
  --workflow ./workflow.json \
  --runtime-map ./runtime-map.json \
  --feature-key MY_FEATURE \
  --goal "Describe the goal" \
  --json

sdtk-agent run continue

Execute the driver loop until the run blocks (gate/manual evidence), waits, or completes.

sdtk-agent run continue --project-path ./my-project --run-id <run_id>

sdtk-agent run status

Current run state as JSON.

sdtk-agent run status --project-path ./my-project --run-id <run_id> --json

sdtk-agent run report

Generate and print the run report — every task, gate decision, and evidence file.

sdtk-agent run report --project-path ./my-project --run-id <run_id>

Gates

sdtk-agent gate approve

Approve a human gate, unblocking downstream stages. Attribution is required.

sdtk-agent gate approve --project-path ./my-project --run-id <run_id> \
  --gate <gate_id> --approved-by <name>

sdtk-agent gate reject

Reject (or request changes on) a human gate.

sdtk-agent gate reject --project-path ./my-project --run-id <run_id> \
  --gate <gate_id> --approved-by <name>

Adapters

sdtk-agent adapter hermes-kanban plan Preview

Compile a workflow into a Hermes Kanban card create/link plan. Dry-run only — no live gateway; the currently published npm adapter refuses mode:"live" fail-closed. Live dispatch remains gated/unpublished. See Hermes Adapter.

sdtk-agent adapter hermes-kanban plan --workflow ./workflow.json

Recovery verbs Shipped

sdtk-agent run cancel and sdtk-agent task retry are published in sdtk-agent-kit@0.4.0 and part of the installable surface. run cancel sets the run and its non-terminal tasks to cancelled (preserving completed/failed) and best-effort cancels any in-flight external task; task retry re-readies a failed or timed-out task for another attempt. Both require --run-id.