Skip to content
Documentation Run a transaction

CLI · Transactions

Run a transaction

agentdiff run captures baseline state, executes an explicit argv, evaluates the resulting evidence, and persists the complete capsule.

agentdiff run [options] -- <command> [arguments...]

Minimal example

agentdiff run --task "Fix authentication" -- codex

Everything after -- is treated as the subprocess argv. AgentDiff does not invoke a shell unless the argv explicitly launches one.

The summary starts with expected (allow), unexpected (review), and protected (deny) mutation counts, the blast-radius category, and whether safe collateral recovery has an eligible target. JSON output preserves the complete machine-readable evidence.

Options

Option Meaning
--root PATH Project root and .agentdiff evidence location. Defaults to ..
--policy PATH YAML or JSON policy. Defaults to <root>/agentdiff.yaml when present.
--task TEXT Human-readable intended task stored in the capsule.
--timeout SECONDS Maximum runtime before AgentDiff terminates the observed command.
--runtime local\|srt Local observation or Anthropic Sandbox Runtime.
--srt-executable PATH Sandbox Runtime executable used with --runtime srt.
--srt-settings PATH Sandbox Runtime settings JSON.
--format summary\|json Human or machine-readable result.
--fail-on never\|review\|deny Policy outcome that produces a non-zero CLI status. Defaults to deny.

Local observation

agentdiff run \
  --root /workspace/project \
  --policy /workspace/project/agentdiff.yaml \
  --runtime local \
  --format json \
  -- python3 /workspace/project/task.py

The local backend observes the subprocess and state around it. It does not block network traffic or provide a kernel containment boundary.

Sandbox Runtime

agentdiff run \
  --runtime srt \
  --srt-executable srt \
  --srt-settings sandbox-settings.json \
  -- python3 agent_task.py

AgentDiff still owns the evidence and policy result; the selected external runtime owns enforcement. See Anthropic Sandbox Runtime.

Automation

Use JSON and select the policy threshold explicitly:

agentdiff run \
  --format json \
  --fail-on review \
  -- python3 agent_task.py > agentdiff-result.json

A local deny is an observed outcome

In local observation mode, a denied filesystem mutation may already exist when the transaction ends. Use safe rollback or an enforcement-capable runtime as appropriate.