# CLI Reference

Complete documentation for all Assay commands.

Planning note: see [CLI Command Grouping RFC](command-grouping-rfc.md) for the
selective noun-verb grouping direction and migration contract.

---

## Installation

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

Verify installation:

```bash
assay --version
# assay 0.9.0
```

---

## Commands Overview

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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```yaml
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](../config/index.md) for full reference.

---

## Command Details

<div class="grid cards" markdown>

-   :material-play:{ .lg .middle } __assay run__

    ---

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

    [:octicons-arrow-right-24: Full reference](run.md)

-   :material-file-search-outline:{ .lg .middle } __assay explain__

    ---

    Explain blocked/allowed trace steps and evaluated rules.

    [:octicons-arrow-right-24: Full reference](explain.md)

-   :material-source-branch:{ .lg .middle } __assay policy__

    ---

    Author, validate, format, and migrate policies.

    [:octicons-arrow-right-24: Full reference](policy.md)

-   :material-import:{ .lg .middle } __assay import__

    ---

    Import sessions from MCP Inspector and other formats.

    [:octicons-arrow-right-24: Full reference](import.md)

-   :material-update:{ .lg .middle } __assay migrate__

    ---

    Upgrade configuration from v0 to v1 format.

    [:octicons-arrow-right-24: Full reference](migrate.md)

-   :material-stethoscope:{ .lg .middle } __assay doctor__

    ---

    Diagnose environment/config issues and apply known fixes.

    [:octicons-arrow-right-24: Full reference](doctor.md)

-   :material-eye-refresh:{ .lg .middle } __assay watch__

    ---

    Watch files and rerun Assay on changes.

    [:octicons-arrow-right-24: Full reference](watch.md)

-   :material-step-forward:{ .lg .middle } __assay replay__

    ---

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

    [:octicons-arrow-right-24: Full reference](replay.md)

-   :material-package-variant:{ .lg .middle } __assay bundle__

    ---

    Create and verify replay bundles.

    [:octicons-arrow-right-24: Full reference](bundle.md)

-   :material-shield-check:{ .lg .middle } __assay evidence__

    ---

    Manage evidence bundles and import external evidence receipts.

    [:octicons-arrow-right-24: Full reference](evidence.md)

-   :material-shield-search:{ .lg .middle } __assay trust-basis__

    ---

    Generate and compare canonical Trust Basis artifacts.

    [:octicons-arrow-right-24: Full reference](trust-basis.md)

-   :material-card-account-details-outline:{ .lg .middle } __assay trust-card__

    ---

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

    [:octicons-arrow-right-24: Full reference](trust-card.md)

-   :material-server:{ .lg .middle } __assay mcp wrap__

    ---

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

    [:octicons-arrow-right-24: Full reference](mcp-server.md)

-   :material-shield-lock:{ .lg .middle } __assay monitor__

    ---

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

    [:octicons-arrow-right-24: Runtime Reference](../../guides/runtime-monitor.md)

</div>
