CLI

High-level AgentInspect CLI command groups for local inspect, check, redact, and export workflows.

This document describes the stable CLI surface of AgentInspect.

AgentInspect is local-first and read-only by default where possible:

• No upload (exports write local strings/files only)
• No vendor sinks
• No external services required
• No replay/fork execution

1. Overview

The CLI command is:

agent-inspect <command> [options]

Core commands:

• list — list local runs
• view — render a single run
• clean — safely delete old runs (verified traces only)
• logs — parse structured logs into local execution trees
• tail — live-tail logs into updating local trees
• export — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
• open — read supported local trace files, directories, or stdin through the canonical reader pipeline
• migrate — convert one local AgentInspect JSONL file to schema 1.0 with dry-run or explicit output
• init — scaffold local AgentInspect config and demo files (v3.1+)
• doctor — diagnose local setup without network or installs (v3.1+)
• workspace — manage a project-local trace workspace (.agent-inspect/workspace.json) (v4.0+)
• index sqlite — optional SQLite-backed trace index for faster queries (requires @agent-inspect/index-sqlite) (v4.1+)
• check — run deterministic local trace checks with stable JSON and exit codes
• eval — run deterministic local evals over existing traces
• redact — redact a local JSON/JSONL file or trace copy
• scan — best-effort local safety scan for trace capture risks
• verify-safe — best-effort local trace safety verification
• artifacts — create safe local CI trace artifact bundles and optional step summaries
• bundle — create share-safe offline trace bundles (redacted copies + verify-safe)
• ci-summary — summarize local reporter artifact manifests for CI
• diff — compare two manual traces (local, read-only)
• timeline — chronological view of one run (local JSONL)
• stats — local aggregate stats over a trace directory
• search — deterministic local search over traces
• sessions — list workflow sessions; v4.2+ subcommands: latest, activity, show, handoffs, errors
• session — inspect one session (handoffs, retries, optional timeline)
• what — concise summary of a single run (local JSONL)
• report — markdown or HTML inspection report for a single run
• explain — deterministic local facts/inferences for a trace, with dry-run payloads

2. Environment variables

• AGENT_INSPECT_TRACE_DIR: default directory for manual trace files (.jsonl) when not passed via --dir (or API options).
• AGENT_INSPECT_SILENT: when true, suppresses live terminal tree output during manual tracing (inspectRun / step). Trace files are still written.
• AGENT_INSPECT: enables manual tracing for maybeInspectRun when set to 1, true, yes, on, or enabled (case-insensitive). Unset or any other value disables tracing. Does not change default inspectRun behavior (which always traces unless enabled: false is passed in code). No network upload — local JSONL only.

3. Exit code policy

• 0: command succeeded (even if a diff reports “differences”)
• 1: command error (invalid args, missing files, missing runs, parse failures, validation failures, etc.)

Exception: check uses CI-oriented semantic exit codes:

• 0: all selected checks passed
• 1: checks ran and at least one error-severity rule failed
• 2: invalid arguments or invalid config
• 3: trace input could not be read
• 4: unsupported or ambiguous trace format

Exception: eval uses local eval semantic exit codes:

• 0: all selected eval rules passed
• 1: eval ran and at least one error-severity rule failed
• 2: invalid arguments, invalid config, unreadable input, unsupported input, ambiguous input, or run-selection errors

Exception: scan and verify-safe use local safety status exit codes:

• 0: status is SAFE or SAFE WITH WARNINGS
• 1: status is UNSAFE
• 2: status is UNKNOWN, including unreadable, unsupported, ambiguous, or invalid inputs

AgentInspect favors human-readable errors without stack traces for expected user mistakes.

4. JSON output policy

Many commands support --json for scripting. JSON output is intended to be:

• machine-parseable
• deterministic for the same input files
• local-only (no network)

5. Safety and redaction notes

• Log-derived output includes confidence labels and avoids inventing parent-child relationships.
• Redaction defaults are conservative (e.g. authorization, cookie, token, apiKey, password, secret, email).
• Exported payloads are redacted by default unless explicitly configured otherwise.
• eval is deterministic and local-only. It does not replay agents, call model providers, upload traces, or create hosted datasets.
• redact writes or prints a redacted copy. It does not mutate source trace files.
• scan and verify-safe are best-effort local checks, not compliance, privacy, security, or regulatory certifications.
• artifacts renders structural summaries and check evidence only; it does not include raw prompt/output bodies, request/response bodies, headers, API keys, secrets, or full tool payloads.

6. Command reference

6.1 list

List recent local runs (trace files).

agent-inspect list [options]

Options:

• --dir <path>: trace directory
• --limit <number>: max runs to show (default 20, max 100)
• --status <running|success|error|unknown>: filter by status
• --name <query>: substring match on run id/name
• --since <duration>: only include recent runs (e.g. 30s, 5m, 2h, 7d)
• --json: print list as JSON

6.2 view

Render a single manual trace by run id.

agent-inspect view <run-id> [options]

Options:

• --dir <path>: trace directory
• --summary: run summary (counts, max depth, longest step)
• --metadata: file path/size + timestamps
• --errors-only: only error events/failed steps
• --verbose: include extra detail (types, metadata, stacks)
• --json: print raw trace events as JSON
• --tui: open optional interactive TUI viewer (requires @agent-inspect/tui)

6.3 clean

Safely delete old local trace files. This is safety-critical: the CLI verifies trace files before deletion.

agent-inspect clean --older-than <duration> [--dry-run] [--yes]
agent-inspect clean --keep <count> [--dry-run] [--yes]

Options:

• --dir <path>: trace directory
• --older-than <duration>: delete runs older than a duration
• --keep <count>: keep N most recent runs
• --dry-run: show what would be deleted
• --yes: skip confirmation prompt

Recommendation: run with --dry-run first.

6.4 logs

Advanced ingestion: use this when your app already emits structured logs. Parse those logs into local execution trees.

agent-inspect logs <file> [options]

Options:

• --format <auto|json|log4js>
• --config <path>: ingest config JSON (see docs/SCHEMA.md for config types)
• --run-id-key <keys>: override runId keys (comma-separated)
• --event-key <key>: override event key
• --timestamp-key <key>: override timestamp key
• --message-key <key>: override message key
• --level-key <key>: override level key
• --parent-id-key <key>: override parent id key
• --duration-key <key>: override duration key
• --status-key <key>: override status key
• --json: emit JSON payload (events/trees/warnings/summary)
• --summary: include summary section in human output
• --warnings <none|summary|all>: warning output mode

Example (fixtures):

agent-inspect logs fixtures/logs/proactive-json.log --format json --config fixtures/configs/proactive-agent-inspect.logs.json

6.5 tail

Live-tail logs into updating execution trees in the terminal.

agent-inspect tail [options]

Options:

• --file <path>: tail a file (otherwise reads stdin)
• --format <auto|json|log4js>
• --config <path>
• --once: read once and exit (useful for CI/scripting with --file)
• --warnings <none|summary|all>
• --refresh <ms>: minimum time between renders
• --json: newline-delimited JSON updates

Important: tail is a local developer tool, not a production monitor.

6.6 export

Export a manual trace run to local formats. No upload. Export redaction operates on a copy of the run tree — original JSONL files are not modified. Review every export before sharing, even with --redaction-profile strict.

agent-inspect export <run-id> --format <markdown|html|openinference|otlp-json> [options]

Options:

• --dir <path>
• --format <format>
• -o, --output <path>: write file (canonical; --out is a legacy alias)
• --json: JSON wrapper output (includes content if not writing to file)
• --validate: validate exported payload shape
• --include-attributes: include bounded attributes (review before sharing)
• --no-metadata: omit summary/metadata sections
• --no-errors: omit error sections
• --redaction-profile <profile>: redaction profile for exported copies — local (default), share, or strict. Key-based safety only; review exports before sharing. (--profile is a legacy alias.)

Examples:

npx agent-inspect export <run-id> --format markdown --redaction-profile share
npx agent-inspect export <run-id> --format html --redaction-profile strict

6.7 open

Open any local trace format supported by the canonical reader pipeline. This command is read-only: it does not mutate input files, upload traces, or run agents.

agent-inspect open [input] [options]

input may be a file, directory, - for stdin, or omitted to read stdin.

Options:

• --format <agent-inspect-jsonl|openinference-json|otlp-json>: explicit reader format override
• --run <run-id>: select a run when input contains multiple runs
• --json: print structured JSON output
• --diagnostics: print reader warnings and unsupported fields in human output

Examples:

npx agent-inspect open fixtures/traces/minimal-success.jsonl --format agent-inspect-jsonl
npx agent-inspect open fixtures/traces-v0.2/manual-basic.jsonl --format agent-inspect-jsonl
npx agent-inspect open packages/core/test/fixtures/openinference-basic.json --format openinference-json
npx agent-inspect open packages/core/test/fixtures/otlp-basic.json --format otlp-json
cat packages/core/test/fixtures/openinference-basic.json | npx agent-inspect open - --format openinference-json --json

When a directory or payload contains multiple runs, open lists the run ids and exits until you pass --run <run-id>.

6.8 migrate

Convert one local AgentInspect JSONL trace file to the stable schema 1.0 persisted contract. This command is local and non-destructive by default: it does not upload traces, run agents, mutate the input file, or overwrite originals.

agent-inspect migrate <input.jsonl> --to 1.0 --dry-run
agent-inspect migrate <input.jsonl> --to 1.0 --output <output.jsonl>

Options:

• --to 1.0: required target schema version
• --dry-run: print deterministic counts and warnings without writing output
• -o, --output <path>: write migrated schema 1.0 JSONL to a separate file
• --force: accepted only for explicit output validation; input overwrite is still refused

Input support:

• v0.1 manual trace rows are converted to schema 1.0 persisted rows.
• v0.2 and v1.0 persisted rows are preserved/upgraded through the shared persisted contract.
• malformed JSON and unsupported schema rows are reported as line warnings.

Examples:

npx agent-inspect migrate fixtures/traces/minimal-success.jsonl --to 1.0 --dry-run
npx agent-inspect migrate fixtures/traces/minimal-success.jsonl --to 1.0 --output fixtures/traces/minimal-success.v1.jsonl

6.9 check

Run deterministic checks against a local trace. This command is local and read-only: it does not rerun agents, call models, upload traces, or mutate input files.

agent-inspect check <trace-path-or-run-id> [options]

<trace-path-or-run-id> may be a trace file, directory, - for stdin, or a run id resolved with --dir.

Options:

• --dir <path>: trace directory for run-id lookup
• --format <agent-inspect-jsonl|openinference-json|otlp-json>: explicit reader format override
• --run <run-id>: select a run when input contains multiple runs
• --config <path>: check config (.json, .js, .mjs, or .cjs)
• --json: print deterministic TraceCheckResult JSON
• --rule <id>: select a rule id; repeatable
• --max-duration-ms <number>: add run.duration
• --required-tool <name> / --forbidden-tool <name>: add tool.usage
• --allowed-model <model> / --max-total-tokens <number>: add llm.usage
• --session <id>: check all runs in a workflow session (uses --dir; target may be .)
• --group <id>: check all runs sharing a groupId metadata value
• --correlate-group: when using --session, also match synthetic group: session keys
• --guardrails <rule>: optional deterministic guardrail rules (banned-phrase, pii-leak, prompt-injection, …); repeatable
• --circuit <rule>: optional circuit analyzers (same-tool-repetition, max-retries, …); repeatable
• --fail-on-observation <status>: add outcome.status rule; repeatable (failed, passed, unknown, skipped; default when flag present without value: failed)
• --preset <trajectory|safety|comprehensive>: additive check preset (does not change the default when omitted)
  • trajectory: completion/structure/relationship focus; excludes share-safety findings
  • safety: raw-content / secret / redaction focus
  • comprehensive: union of trajectory and safety
  • Presets are a base select set. CLI shorthands on the same invocation (--fail-on-observation, --required-tool, --forbidden-tool, --allowed-model, --max-total-tokens, --max-duration-ms, --max-step-duration, --detect-stalls) extend that set; they are not dropped because the preset already selected rules. Config checks.select is not silently expanded with unrelated configured rules.
• --evidence-on <fail|always|never>: write local Evidence v2 (no upload); omitted = never
• --evidence-dir <path>: Evidence output directory or base path
• --evidence-profile <local|share|strict>: redaction profile for Evidence (default share)
• --evidence-format <directory|html|zip>: Evidence layout (default directory)

By default, check runs run.status. Additional built-in rules can be selected with --rule or config when their options are available. Prefer --preset trajectory in CI, then verify-safe before sharing.

Config files use this shape:

{
  "checks": {
    "select": ["run.status", "run.duration"],
    "run": { "maxDurationMs": 30000 },
    "tool": { "required": ["search_docs"] },
    "llm": { "allowedModels": ["gpt-4.1-mini"], "maxTotalTokens": 12000 }
  }
}

YAML is not supported. TypeScript config files (.ts, .mts, .cts) fail clearly unless a future explicit loader strategy is added; use precompiled JavaScript config instead.

Examples:

npx agent-inspect check fixtures/traces-v0.2/manual-basic.jsonl --json
npx agent-inspect check minimal-success --dir fixtures/traces --rule run.status
npx agent-inspect check trace.jsonl --preset trajectory --evidence-on fail
npx agent-inspect check trace.jsonl --max-duration-ms 30000 --required-tool search_docs --json
npx agent-inspect check trace.jsonl --guardrails pii-leak --guardrails prompt-injection --json
npx agent-inspect check trace.jsonl --circuit same-tool-repetition --circuit max-retries --json

Recipe: examples/recipes/deterministic-ci-checks

6.10 serve

Start the optional localhost read-only trace viewer (@agent-inspect/viewer). Reads traces from disk only; no upload or mutation.

agent-inspect serve [options]

Options:

• --dir <path>: trace directory to serve (default from AGENT_INSPECT_TRACE_DIR or .agent-inspect-runs)
• --host <host>: bind host (default 127.0.0.1)
• --port <number>: bind port (default 7337)
• --open: open a browser when host is localhost

Binding to 0.0.0.0 logs a warning — traces may be exposed on the network. Prefer 127.0.0.1 unless you accept that risk.

6.11 eval

Run deterministic local evals against an existing trace. This command reads through the same local reader pipeline as open and check; it does not rerun agents, call models, upload traces, mutate inputs, or create a hosted dataset.

agent-inspect eval <trace-path-or-run-id> [options]

Options:

• --dir <path>: trace directory for run-id lookup
• --format <agent-inspect-jsonl|openinference-json|otlp-json>: explicit trace input format
• --run <run-id>: select a run when input contains multiple runs
• --config <path>: eval config (.json, .js, .mjs, or .cjs); TypeScript configs are rejected until an explicit loader is approved
• --json: print deterministic JSON eval result
• --markdown: print deterministic Markdown eval summary
• --require-success: require the selected run to complete successfully
• --required-tool <name>: require a tool name (repeatable)
• --forbid-tool <name> / --forbidden-tool <name>: forbid a tool name (repeatable)
• --max-duration-ms <number>, --max-depth <number>, --max-retries <number>, --max-total-tokens <number>
• --require-retrieval-before-generation
• --required-decision-metadata <key>: require decision metadata (repeatable)
• --context-overlap, --min-context-overlap <number>, --min-shared-terms <number>
• --quote-overlap
• --citation-presence
• --required-source-id <id>: require a source id in context or citations (repeatable)
• --min-answer-characters <number>, --max-answer-characters <number>, --min-answer-words <number>, --max-answer-words <number>
• --banned-phrase <text>: ban unsupported-answer phrasing (repeatable)

Example config:

{
  "eval": {
    "requireSuccess": true,
    "requiredTools": ["searchDocs"],
    "forbiddenTools": ["deleteAccount"],
    "citationPresence": true,
    "contextOverlap": { "minOverlap": 0.2 },
    "requiredSourceIds": ["policy-30-day"]
  }
}

Examples:

npx agent-inspect eval fixtures/traces-v0.2/manual-basic.jsonl --require-success --json
npx agent-inspect eval trace.jsonl --forbid-tool deleteAccount --markdown
npx agent-inspect eval trace.jsonl --config agent-inspect.eval.json --json

Recipes: eval-local-checks and eval-ci-artifacts.

6.11 redact

Redact a local JSON or JSONL trace/file. The command prints or writes a redacted copy and reports bounded findings; it does not mutate the source file or upload content.

agent-inspect redact <trace-or-file> [options]

Options:

• --dir <path>: trace directory for run-id lookup
• --profile <local|share|strict>: redaction profile (default share)
• -o, --output <path>: write redacted content to a file
• --json: print deterministic JSON wrapper with findings

Examples:

npx agent-inspect redact trace.jsonl --profile share --json
npx agent-inspect redact trace.jsonl --profile strict -o trace.share.jsonl

Recipe: redact-share-safe-file.

6.12 scan and verify-safe

Run best-effort local safety verification for supported trace inputs. These commands are local and read-only: they do not rerun agents, call models, upload traces, mutate input files, or certify compliance.

agent-inspect scan <trace-path-or-run-id> [options]
agent-inspect verify-safe <trace-path-or-run-id> [options]

<trace-path-or-run-id> may be a trace file, directory, - for stdin, or a run id resolved with --dir.

Statuses:

• SAFE: no safety findings and no reader warnings.
• SAFE WITH WARNINGS: no blocking safety findings, but warnings (reader or findings) remain.
• UNSAFE: blocking safety findings were detected.
• UNKNOWN: the input could not be read, normalized, or selected conservatively.

verify-safe assesses the source trace and a share-redacted artifact. The printed/exit status follows the artifact assessment when a single-file (or stdin) artifact can be derived. scan remains source-oriented.

Options:

• --dir <path>: trace directory for run-id lookup
• --format <agent-inspect-jsonl|openinference-json|otlp-json>: explicit reader format override
• --run <run-id>: select a run when input contains multiple runs
• --json: print deterministic JSON safety result
• --explain: explain each finding (detector/path/category/confidence/redaction/override/bundle gate) without printing matched secret values
• --max-string-length <number>: unsafe threshold for string values
• --max-array-length <number>: unsafe threshold for array values
• --max-object-keys <number>: unsafe threshold for object key counts
• --max-serialized-bytes <number>: unsafe threshold for serialized values

The scan looks for raw prompt/output-like capture paths, unredacted sensitive-looking keys, secret-like string patterns, and oversized values. It reports evidence paths rather than raw prompt, output, request/response, header, API key, secret, or full tool payload values. Secret detection is best-effort and should not be treated as exhaustive.

Policy and overrides: SAFETY-POLICY.md.

Examples:

npx agent-inspect scan fixtures/traces-v0.2/manual-basic.jsonl --json
npx agent-inspect scan trace.jsonl --explain
npx agent-inspect verify-safe minimal-success --dir fixtures/traces
npx agent-inspect verify-safe trace.jsonl --explain --json
npx agent-inspect verify-safe trace.jsonl --max-string-length 8192 --json

6.13 artifacts

Create deterministic local CI artifacts for supported trace inputs. This command is local and read-only for trace inputs: it does not rerun agents, call models, upload files, use GitHub APIs, or mutate repository state. It writes only to --output-dir and, when requested, a local step-summary file.

agent-inspect artifacts <trace-path-or-run-id> --output-dir <path> [options]

Generated files:

• trace.json: structural trace summary only
• check.json: safety check result
• diff.json: baseline diff result, or not_requested
• summary.md: safe Markdown CI summary
• report.html: safe HTML CI summary
• manifest.json: deterministic file/status manifest

Options:

• --output-dir <path>: required local artifact directory
• --dir <path>: trace directory for run-id lookup
• --format <agent-inspect-jsonl|openinference-json|otlp-json>: explicit reader format override
• --run <run-id>: select a run when input contains multiple runs
• --baseline <trace-path-or-run-id>: optional baseline trace for diff artifacts
• --baseline-run <run-id>: select a run from the baseline trace
• --github-summary <path>: append the safe Markdown summary to this file, such as $GITHUB_STEP_SUMMARY
• --json: print deterministic manifest.json content

The artifact command runs safety checks before rendering and only includes structural counts, statuses, bounded check findings, diagnostics, and evidence paths. Baseline diff artifacts use normalized baseline checks and also avoid raw prompt/output/tool payload values. --github-summary is plain local file output; AgentInspect does not call GitHub APIs or upload artifacts.

Examples:

npx agent-inspect artifacts fixtures/traces-v0.2/manual-basic.jsonl --output-dir ./artifacts --json
npx agent-inspect artifacts minimal-success --dir fixtures/traces --output-dir ./artifacts --github-summary "$GITHUB_STEP_SUMMARY"
npx agent-inspect artifacts candidate.jsonl --baseline baseline.jsonl --output-dir ./artifacts

Recipe and sample workflow: examples/recipes/deterministic-ci-checks

6.14 ci-summary

Summarize local Vitest/Jest reporter artifact manifests into deterministic Markdown or JSON. This command reads shared schemaVersion: "0.1" manifest JSON files only, including the reporter package wrapper emitted by the workspace reporters. It does not read trace contents, rerun tests, upload artifacts, call GitHub APIs, or mutate repository state. --output and --github-summary write local files.

agent-inspect ci-summary <manifest...> [options]

Options:

• -o, --output <path>: write the Markdown summary to a local file
• --github-summary <path>: append the Markdown summary to a local file, such as $GITHUB_STEP_SUMMARY
• --json: print deterministic JSON summary

Example:

npx agent-inspect ci-summary .agent-inspect/jest-artifacts/tests/**/report.json \
  --output ./artifacts/reporter-summary.md \
  --github-summary "$GITHUB_STEP_SUMMARY"

Reporter artifact paths in the summary are kept relative and validated conservatively. The summary includes bounded package/framework metadata, test identity, status counts, trace filenames, artifact paths, redaction profiles, and diagnostic counts only.

Recipe and sample workflow: examples/recipes/github-actions-artifact

6.15 diff

Compare two manual trace runs. Diff is local and read-only (does not rerun agents).

agent-inspect diff <left-run-id> <right-run-id> [options]

Options:

• --dir <path>
• --json
• --ignore-duration
• --duration-threshold <duration>
• --focus <all|errors|structure|outputs>
• --check <all|structure|outputs|errors|timing>

Fixture examples:

agent-inspect diff minimal-success minimal-error --dir fixtures/traces
agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration

Simplified example output (actual CLI formatting may differ slightly):

Run diff
Left:  minimal-success
Right: minimal-error

Summary:
  Differences: 4
  Errors: 0
  Warnings: 3
  Info: 1

First divergence:
  run-status at (run)
    left: success
    right: error

Differences:
  [warning] run-status
    Run completion status differs
    left: success
    right: error
  [info] duration
    Run duration differs
    left: 120
    right: 70
  [warning] step-removed plan
    Step only in left run: plan
    left: step_root
    right: (undefined)
  [warning] step-added failing-step
    Step only in right run: failing-step
    left: (undefined)
    right: step_fail

More examples, including timing-only and structure-only diffs, are in docs/DIFF.md.

6.16 timeline

Chronological step list for one manual trace. Read-only; does not mutate JSONL files.

agent-inspect timeline <run-id> [options]

Options:

• --dir <path>
• --json — structured RunTimeline JSON
• --focus slow — show only the slowest steps by duration (top N)

6.17 stats

Local aggregate statistics over trace files in a directory. Read-only.

agent-inspect stats [options]

Options:

• --dir <path>
• --since <duration> — e.g. 7d, 24h
• --correlation-id <id> — filter by run_started.metadata.correlationId
• --group-id <id> — filter by run_started.metadata.groupId
• --json

Use --correlation-id or --group-id to filter runs by run_started metadata (see API.md).

6.18 search

Deterministic search over local traces (substring / exact filters). No semantic search.

agent-inspect search [options]

Options:

• --dir <path>
• --since <duration>
• --status <success|error|running|unknown>
• --kind <kind> / --type <type> — manual step type (llm, tool, logic, …)
• --name <query> — substring on run or step name
• --tool <query> — substring on tool step name or metadata.toolName
• --duration <expr> — e.g. >5s, >=500ms
• --limit <number> — default 50
• --session <id> — limit to runs in one workflow session
• --correlate-group — when using --session, also match synthetic group: keys
• --observation <status> — filter runs with observed outcomes matching status (passed, failed, unknown, skipped)
• --json

Examples:

npx agent-inspect search --status error --dir ./.agent-inspect
npx agent-inspect search --kind tool --name search
npx agent-inspect search --duration ">100ms" --json
npx agent-inspect search --session sess-retry-001 --dir ./.agent-inspect

6.19 sessions

Workflow sessions and activity from local trace metadata. v4.2 adds session status, activity summaries, and optional SQLite index acceleration (falls back to directory scan). Read-only; no network.

agent-inspect sessions [options]                    # list sessions (default)
agent-inspect sessions latest [--json]
agent-inspect sessions activity [--since 7d] [--json]
agent-inspect sessions show <session-id> [--timeline] [--json]
agent-inspect sessions handoffs [--session <id>] [--json]
agent-inspect sessions errors [--since 7d] [--json]

Shared options:

• --dir <path>
• --correlate-group — treat shared groupId as a synthetic session when sessionId is absent
• --stale-after <duration> — mark sessions stale after inactivity (e.g. 24h, 7d)
• --json — deterministic JSON output

activity and errors accept --since <duration> (e.g. 7d, 24h). Session summaries include derived status, lastActivity, lastError, and retryCount without changing trace files.

Example:

npx agent-inspect sessions --dir ./.agent-inspect
npx agent-inspect sessions latest --json
npx agent-inspect sessions activity --since 7d
npx agent-inspect sessions handoffs --session sess-handoff-001
npx agent-inspect sessions errors --since 30d --json

6.20 session

Inspect one workflow session: runs, handoffs, retries, and optional per-run timelines. Uses the same session index as sessions.

agent-inspect session <session-id> [options]

Options:

• --dir <path>
• --timeline — include per-run timelines (human or JSON timelines)
• --critical-path — include critical path section
• --diagnostics — include ambiguity warnings for the session
• --json — structured session view

Example:

npx agent-inspect session sess-handoff-001 --timeline
npx agent-inspect session sess-retry-001 --critical-path --json

6.21 what

Concise human-readable summary of one local trace run. Read-only; accepts v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path. Vocabulary: TRACE-VOCABULARY-V1.5.md.

agent-inspect what <run-id> [options]

Options:

• --dir <path>
• --json — structured RunWhatSummary JSON
• --no-correlation — omit correlation ids from human output

Example:

npx agent-inspect what minimal-success --dir fixtures/traces

Sample output:

What: minimal-success
Status: success · Duration: 120ms · Steps: 1 (1 logic)
Outcome: Completed successfully.
Slowest: plan (100ms, logic)

6.20 report

Generate a local inspection report combining what happened, timeline, and execution tree sections. The command reads local v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path without mutating them. Distinct from export (which targets shareable tree snapshots and standards formats).

agent-inspect report <run-id> [options]

Options:

• --dir <path>
• --format <markdown|html> — default markdown
• -o, --output <path> — write to file
• --json — JSON wrapper (includes content when writing to stdout)
• --include-attributes — bounded attributes in the execution tree section
• --section <name> — include report sections; repeatable (what, timeline, tree, observations; default: all except when narrowed)
• --no-errors — omit error details from the execution tree section
• --no-correlation — omit correlation ids from what section
• --redaction-profile <local|share|strict> — key-based redaction profile applied to the complete report (default local); review output before sharing

Example:

npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html

6.21 explain

Explain a local trace using deterministic facts and local inference labels. This command reads through the same local reader pipeline as open / check; it does not call a model provider, upload traces, replay agents, or mutate input files.

agent-inspect explain <trace-path-or-run-id> [options]

Options:

• --dir <path> — trace directory for run-id lookup
• --format <agent-inspect-jsonl|openinference-json|otlp-json> — explicit input format
• --run <run-id> — select a run when the trace contains multiple runs
• --dry-run — emit only the redacted facts payload, with no local inference labels
• --provider <provider> — reserved for an explicit future provider mode; currently rejected without network calls
• --json — print deterministic JSON output
• --redaction-profile <local|share|strict> — key-based redaction profile for the explanation payload (default local)

Examples:

npx agent-inspect explain minimal-success --dir fixtures/traces
npx agent-inspect explain fixtures/traces/minimal-success.jsonl --dry-run --json --redaction-profile strict

Provider design gate:

• Current behavior is local only. --provider <provider> exits with a user-facing PROVIDER_NOT_IMPLEMENTED error and performs no provider call.
• --dry-run --json is the payload review surface. The provider payload contract is the returned explanation object: mode, runId, optional name / status, redactionProfile, facts, inferences, and notes.
• Provider chunks must require explicit provider selection, document required environment variables, and keep credentials out of trace data and dry-run output.
• Provider prompts must ask for concise explanations from redacted facts only. They must not request, expose, or preserve raw chain-of-thought.
• Cloud provider behavior is never selected by default and must be reviewed before implementation. Local provider support must still be explicit and opt-in.

6.22 workspace

Manage a project-local trace workspace (.agent-inspect/workspace.json). Added in v4.0. Local-only; trace files are never deleted. See WORKSPACE.md for the full model.

agent-inspect workspace init [--project <name>] [--redaction-profile <local|share|strict>] [--dry-run] [--json]
agent-inspect workspace status [--json]
agent-inspect workspace doctor [--json]
agent-inspect workspace clean [--yes] [--json]
agent-inspect workspace path [--json]

• init — create or adopt a workspace and its standard folders (runs/, reports/, artifacts/, bundles/, notes/, index/). An existing workspace.json is adopted without rewrite; existing traces are preserved.
• status — read-only counts of traces, reports, artifacts, bundles, notes, plus index status.
• doctor — validate the manifest, folder permissions, trace readability, and index freshness. Exits non-zero when a check fails.
• clean — remove generated content (reports/artifacts/bundles/index). Dry-run by default; --yes deletes. Trace directories are never targeted.
• path — print resolved workspace paths.

All subcommands accept --json for deterministic output.

6.23 index sqlite

Optional SQLite-backed index that accelerates local queries over large trace directories. Added in v4.1. Requires the optional @agent-inspect/index-sqlite package; the core CLI does not depend on SQLite. The index is derived from JSONL and always safe to delete — JSONL remains the source of truth and trace files are never mutated. Local-only; no network. See INDEX.md for the full model.

agent-inspect index sqlite build [--dir <path>] [--max-runs <n>] [--json]
agent-inspect index sqlite rebuild [--dir <path>] [--max-runs <n>] [--json]
agent-inspect index sqlite status [--dir <path>] [--json]
agent-inspect index sqlite query [--dir <path>] [--status <s>] [--session <id>] [--name <q>] [--kind <k>] [--tool <q>] [--limit <n>] [--json]
agent-inspect index sqlite clean [--dir <path>] [--json]

• build / rebuild — build or fully rebuild trace-index.sqlite from the trace directory. Rebuilds are idempotent; a corrupt prior index is discarded and rebuilt cleanly.
• status — report index health, run/step counts, build time, and staleness (stale when any trace is newer than the index).
• query — filter indexed runs by status, session, name, step kind, or tool. Exits non-zero with an install/build hint when no usable index is present.
• clean — delete the index database (and its WAL/SHM sidecars). Traces are never touched.

If @agent-inspect/index-sqlite is not installed, these subcommands print a short install hint and exit non-zero.

6.24 bundle

Create a share-safe offline trace bundle (v4.3+ / Evidence v2). Bundles are derived copies: original traces are read-only and never mutated. Automatic safety assessment runs on the redacted artifact before write; the command fails when the artifact is UNSAFE/UNKNOWN unless --allow-unsafe. Source-only findings that redaction removes do not refuse the bundle. See BUNDLES.md, EVIDENCE-FORMAT.md, and SAFETY-POLICY.md.

agent-inspect bundle <run-id> [options]
agent-inspect bundle --session <session-id> [options]
agent-inspect bundle --since <duration> [options]

Options:

• --dir <path> — trace directory
• --session <session-id> — bundle all runs in a session
• --since <duration> — bundle runs with activity since a window (e.g. 24h, 7d)
• --profile <profile> — local, share (default), or strict redaction for exported copies (--redaction-profile is the canonical alias)
• --format <format> — directory (default), html (evidence.html + evidence.json sidecar), or zip (local archive)
• --out <path> — output directory, .html path, or .zip path; directory mode still strips a bare .zip suffix to a folder (--output is the canonical alias)
• --allow-unsafe — write bundle even when verify-safe reports UNSAFE
• --json — print deterministic JSON manifest

Verify an Evidence v2 directory:

agent-inspect bundle verify <path> [--unexpected fail|warn|ignore] [--json]

Checks manifest schema, listed-file presence, SHA-256 hashes, unexpected files (default fail), assessment, and generator provenance. Unpack ZIP archives before verify.

Open a verified local Evidence HTML file in the platform browser (no network):

agent-inspect bundle open <path> [--skip-verify] [--json]

<path> may be an Evidence directory or an evidence.html file. Verify runs first unless --skip-verify is set. If the OS cannot open a browser, the command prints the local file path as a fallback and does not upload anything.

Output includes trace.html, trace.jsonl, summary.md, metadata.json, check-results.json, redaction-report.json, and assets/runs/ mirrors for multi-run bundles.

Examples:

npx agent-inspect bundle minimal-success --dir fixtures/traces --out ./bundle-out
npx agent-inspect bundle --session sess-handoff-001 --dir ./.agent-inspect --profile strict
npx agent-inspect bundle --since 24h --dir ./.agent-inspect --json

Recipe: shareable-bundle-basic.

6.25 suite

Define and run local trace suites for CI trajectory checks (v5.0+). Suites read existing traces only — no agent replay, no model calls, no upload.

agent-inspect suite init [--template <name>]
agent-inspect suite validate [--config path]
agent-inspect suite list [--config path]
agent-inspect suite run [--config path] [--json] [--markdown] [-o dir]
agent-inspect suite report --input <suite-run.json> [--format markdown|json]

Default config file: agent-inspect.suite.json in the current directory.

Options (shared):

• --config <path> — suite config (.json, .js, .mjs, .cjs)

init also supports:

• --template <name> — PM/QA template (v5.4+): customer-support-agent, refund-agent, sales-assistant, browser-task-agent, mcp-tool-agent, workflow-agent, rag-answer-agent, human-approval-agent

run also supports:

• -o, --output <dir> — write JSON run artifact (default: .agent-inspect/suite-runs)
• --json / --markdown — structured or readable output

Case fields include requireTools, forbidTools, maxDurationMs, and expectedObservations (outcome names that must be passed).

Example:

npx agent-inspect suite init
npx agent-inspect suite run --config fixtures/configs/outcome-suite.suite.json --json

Recipe: trace-suite-basic.

6.26 cohort

Compare baseline vs candidate trace cohorts for regressions (v5.1+). Reads local traces only — no agent replay, no model calls, no upload.

agent-inspect cohort --dir <path> --baseline <label> --candidate <label> [options]

Options:

• --dir <path> — trace directory (default: .agent-inspect/traces)
• --baseline <label> / --candidate <label> — cohort labels from run_started.metadata
• --cohort-key <key> — metadata key for labels (default: cohort)
• --group-by <spec> — model, session, group, or metadata.<key> (default: model)
• --metric <list> — comma-separated metrics (errorRate, duration, toolChoice, observationFailure, …)
• --format <format> — markdown, json, or html (default: markdown)
• -o, --output <dir> — write cohort-results.json, cohort-summary.md, cohort-report.html
• --json — print deterministic JSON result

Exit code 1 when any comparison flags a regression.

Example:

npx agent-inspect cohort \
  --dir fixtures/cohorts/before-after \
  --baseline before \
  --candidate after \
  --group-by model

Recipe: cohort-baseline-candidate.

6.27 gate

Run deterministic CI quality gates over local traces or suite configs (v5.2+). No agent replay, no model calls, no upload.

agent-inspect gate --suite <path> [options]
agent-inspect gate --dir <path> --max-error-rate <percent> [options]

Options:

• --dir <path> — trace directory for threshold checks
• --suite <path> — suite config (.json, .js, .mjs, .cjs)
• --max-error-rate <percent> — maximum allowed error rate
• --max-p95-duration <ms> — maximum allowed p95 run duration
• --forbid-tool <name> — forbidden tool (repeatable or comma-separated)
• --require-observation <name> — required passed observation (repeatable or comma-separated)
• --format <format> — markdown, json, html, junit, or github (default: markdown)
• -o, --output <dir> — write gate-results.json, gate-summary.md, gate-report.html, junit.xml, github-step-summary.md
• --json — print deterministic JSON result
• --evidence-on <fail|always|never> — write local Evidence v2 (no upload); omitted = never
• --evidence-dir <path> — Evidence output directory or base path
• --evidence-profile <local|share|strict> — redaction profile (default share)
• --evidence-format <directory|html|zip> — Evidence layout (default directory)

Exit codes: 0 pass, 1 gate failed, 2 invalid config, 3 trace read failure, 4 unsupported format. Evidence emission never suppresses the original gate exit code.

Example:

npx agent-inspect gate --suite fixtures/configs/outcome-suite.suite.json --output ./gate-artifacts
npx agent-inspect gate --dir fixtures/cohorts/before-after --max-error-rate 5 --forbid-tool deleteAccount
npx agent-inspect gate --suite agent-inspect.suite.ts --evidence-on fail --evidence-profile share

Recipe: github-actions-gate.

6.28 viewer

Start the localhost read-only viewer for traces, suite evidence, or workspace status (v5.3+).

agent-inspect viewer [--suite | --workspace] [options]

Options:

• --suite — suite evidence mode (runs suite config and shows case status, failures, observations)
• --workspace — workspace mode (project status, runs, artifacts)
• --config <path> — suite config for --suite mode
• --dir <path> — trace directory (trace mode default)
• --host, --port, --open — same as serve

Example:

npx agent-inspect viewer --suite --config fixtures/configs/outcome-suite.suite.json
npx agent-inspect viewer --workspace

7. Optional TUI behavior

view --tui delegates to @agent-inspect/tui and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.

8. Warnings behavior

Log parsing emits warnings for malformed lines or missing required keys. --warnings controls whether warnings are hidden, summarized, or printed line-by-line.

9. Limitations (reminder)

See:

• docs/KNOWN-ISSUES.md
• docs/LIMITATIONS.md

MCP configure (v6.11+)

agent-inspect mcp configure --client cursor
agent-inspect mcp configure --client claude-code --project-local
agent-inspect mcp configure --client cursor --project-local --write --yes

Dry-run by default. Writes project-local files only with --project-local --write --yes. No network; share redaction by default. See CODING-AGENT-LOOP.md and coding-agent-instructions/.