CLI Reference¶

Complete documentation for all Assay commands.

Planning note: see CLI Command Grouping RFC for the selective noun-verb grouping direction and migration contract.

Installation¶

# Rust
cargo install assay-cli
# Or via installer scripts (see Home)

Verify installation:

assay --version
# assay 0.9.0

Commands Overview¶

Command	Description
`assay run`	Run tests against traces
`assay policy`	Author, validate, format, and migrate policies
`assay explain`	Explain why trace steps were allowed/blocked
`assay bundle`	Create/verify replay bundles
`assay replay`	Replay from a replay bundle
`assay evidence`	Manage evidence bundles, external evidence imports, and receipt schemas
`assay trust-basis`	Generate, compare, and assert canonical Trust Basis artifacts
`assay trust-card`	Generate Trust Card JSON, Markdown, and static HTML projections
`assay import`	Import sessions from MCP Inspector, etc.
`assay migrate`	Upgrade config from v0 to v1
`assay doctor`	Diagnose setup and optionally auto-fix known issues
`assay watch`	Re-run on config/policy/trace changes
`assay monitor`	Runtime Security (Linux Kernel Enforcement)
`assay mcp`	MCP runtime commands: wrap, discover, kill, config-path, and tool signing
CLI Command Grouping RFC	Selective command grouping direction and compatibility contract

Global Options¶

Common top-level options:

Option	Description
`--help`, `-h`	Show help message
`--version`, `-V`	Show version

Quick Examples¶

Run Tests¶

# Basic run
assay run --config eval.yaml

# Strict mode (fail on any violation)
assay run --config eval.yaml --strict

# Specific trace file
assay run --config eval.yaml --trace-file traces/golden.jsonl

# Machine-readable run report on stdout
assay run --config eval.yaml --trace-file traces/golden.jsonl --format json > results.json

# CI reports
assay ci --config eval.yaml --trace-file traces/golden.jsonl --sarif sarif.json --junit junit.xml

Generate Policy (With Diff Preview)¶

# Generate policy from trace
assay policy generate --input traces/session.jsonl --output policy.yaml

# Preview changes against existing policy file
assay policy generate --input traces/session.jsonl --output policy.yaml --diff --dry-run

Replay Bundles¶

# Create bundle from latest run artifacts
assay bundle create

# Verify bundle safety/integrity
assay bundle verify --bundle .assay/bundles/12345.tar.gz

# Replay from bundle (offline default)
assay replay --bundle .assay/bundles/12345.tar.gz

# Replay live with seed override
assay replay --bundle .assay/bundles/12345.tar.gz --live --seed 42

Migrate Config¶

# Upgrade to v1 format
assay migrate --config old-eval.yaml

# Preview changes without writing
assay migrate --config old-eval.yaml --dry-run

Validate Config And Trace¶

# Positional config path
assay validate eval.yaml --trace-file traces/golden.jsonl

# Equivalent explicit config flag
assay validate --config eval.yaml --trace-file traces/golden.jsonl

MCP Runtime¶

# Enforcing mode
assay mcp wrap --policy assay.yaml -- <real-mcp-command> [args...]

# Dry-run mode
assay mcp wrap --policy assay.yaml --dry-run -- <real-mcp-command> [args...]

# Discover local MCP servers
assay mcp discover --format json

# Sign or verify MCP tool definitions
assay mcp tool sign tool.json --key private.pem --out signed.json

Diagnose and Watch¶

# Diagnose and auto-fix known issues
assay doctor --config eval.yaml --trace-file traces/dev.jsonl --fix --yes

# Live re-run loop on local edits
assay watch --config eval.yaml --trace-file traces/dev.jsonl --strict

Exit Codes¶

Code	Meaning
0	Success (all tests passed)
1	Test failure (one or more tests failed)
2	Configuration error
3	Infrastructure/judge error
4	Would block (sandbox/policy)

Environment Variables¶

Variable	Description	Default
`ASSAY_EXIT_CODES`	Exit code compatibility mode (`v1` or `v2`)	`v2`
`MCP_CONFIG_LEGACY`	Enable legacy config mode when set to `1`	disabled
`ASSAY_STRICT_DEPRECATIONS`	Fail on deprecated policy/config usage when set to `1`	disabled
`OPENAI_API_KEY`	API key for OpenAI-backed judge/embedder paths	unset
`NO_COLOR`	Disable colored output	unset

Configuration File¶

Most run/ci commands read from eval.yaml by default:

version: 1
suite: my-agent
model: gpt-4o-mini
tests:
  - id: args_valid
    input:
      prompt: "Summarize this task."
    expected:
      type: args_valid
      policy: policies/default.yaml

See Configuration for full reference.

Command Details¶

assay run

Run tests against traces. The main command for CI/CD.

Full reference
assay explain

Explain blocked/allowed trace steps and evaluated rules.

Full reference
assay policy

Author, validate, format, and migrate policies.

Full reference
assay import

Import sessions from MCP Inspector and other formats.

Full reference
assay migrate

Upgrade configuration from v0 to v1 format.

Full reference
assay doctor

Diagnose environment/config issues and apply known fixes.

Full reference
assay watch

Watch files and rerun Assay on changes.

Full reference
assay replay

Replay runs from a replay bundle (--bundle), offline by default.

Full reference
assay bundle

Create and verify replay bundles.

Full reference
assay evidence

Manage evidence bundles and import external evidence receipts.

Full reference
assay trust-basis

Generate and compare canonical Trust Basis artifacts.

Full reference
assay trust-card

Generate Trust Card JSON, Markdown, and static HTML projections.

Full reference
assay mcp wrap

Wrap a real MCP process with policy enforcement for agent self-correction.

Full reference
assay monitor

Real-time kernel enforcement (SOTA). Blocks attacks before they happen.

Runtime Reference