Skip to content
Documentation CLI overview

CLI

Command-line interface

The CLI wraps explicit argv, persists evidence under the project root, and exposes deterministic output suitable for both people and automation.
agentdiff <command> --help

Transaction workflow

runExecute an argv inside an observed transaction. inspectRead one durable run capsule. rollbackConflict-check and recover eligible changes. verifyValidate the capsule checksum manifest. runsList durable capsules under a root. doctorReport implemented runtime capabilities.

Policy workflow

agentdiff policy init
agentdiff policy validate --policy agentdiff.yaml
agentdiff policy explain .env --policy agentdiff.yaml

See policy commands for the exact subcommand surface.

Cortex workflow

agentdiff cortex memory search "authentication regression"
agentdiff cortex agent ask --provider codex-cli --task "Plan the smallest safe fix"

See Cortex, memory, and provider commands for Claude, Codex/OpenAI, Ollama, and optional local semantic indexing.

Shared conventions

Project root

Transaction commands default to the current directory. Use --root when the command and evidence store belong elsewhere:

agentdiff runs --root /workspace/project
agentdiff inspect <run-id> --root /workspace/project

Capsules are stored at <root>/.agentdiff/runs/<run-id>/.

Output formats

Current transaction and operational commands support:

  • --format summary — compact, human-readable output;
  • --format json — complete machine-readable output.

Exit behavior

agentdiff run preserves a non-zero subprocess exit code. For a successful subprocess, the default --fail-on deny policy maps observed safety outcomes as follows:

Outcome Default exit
allow 0
review 0
deny 3
command blocked before launch 126
AgentDiff execution error 1

Use --fail-on never to report policy only, or --fail-on review to make both review and deny outcomes non-zero.

Full implemented command map

agentdiff
├── init / bootstrap            # zero-touch trust configuration
├── wrap                        # run one agent through the full pipeline
├── serve / status / stop / hook# local sidecar daemon + adapters
├── run
├── inspect / runs / verify
├── prove / promote / repair    # trust pipeline automation
├── rollback / cleanup / doctor
├── trust
│   └── graph / status
├── impact                      # minimum strong proof for changed paths
├── proof
│   └── cache-status
├── workspace
│   └── status / warm / prune
├── policy
│   └── init / validate / explain
├── api                         # self-maintaining external API scanner
│   └── scan / check
└── cortex                    # experimental, secondary surface
    ├── memory
    │   └── stats / search / index
    ├── agent
    │   └── ask
    ├── skill
    │   └── list / generate
    ├── context
    │   └── pack
    └── advise

Zero-touch automation is documented in Zero-touch commands.

Trust the installed help

The command surface is beta and may evolve. agentdiff <command> --help is generated directly from the installed implementation.