CLI Commands

Complete reference for the spooled command-line tool.

CI/CD commands

spooled ci run

Full CI orchestration: run tests → capture traces → compare → report. Works locally on the free tier. The --push flag (sync report to backend) requires Pro.

spooled ci run \
    --suite tests/agents/ \
    --baseline baselines/ \
    --policy spooled-policy.yml \
    --out ci-report/ \
    --retries 2

Flag	Default	Description
--suite, -s	(required)	Path to test suite (Python module or directory)
--baseline, -b	None	Path to baseline directory or JSON file
--policy, -p	None	Path to policy YAML file
--out, -o	ci-report	Output directory for reports
--agent-id, -a	None	Agent identifier (auto-detected from traces)
--enable-blocking / --no-blocking	true	Exit code 1 on policy violations
--retries, -r	1	Rerun count for flaky metric signals (2 = 2-pass)
--push	false	Upload CI report to backend
--backend-url, -u	None	Backend API URL override

spooled ci compare

Compare one or more traces against a baseline. Available on the free tier.

spooled ci compare trace.jsonl \
    --baseline baselines/agent.json \
    --agent-id my_agent \
    --policy spooled-policy.yml

Flag	Default	Description
current (positional)	(required)	Path(s) to trace JSONL file(s). Accepts shell globs.
--baseline, -b	(required)	Path to baseline JSON or trace file
--agent-id, -a	"unknown"	Agent identifier
--policy, -p	None	Path to policy YAML
--out, -o	None	Write JSON result to file
--enable-blocking / --no-blocking	true	Exit code 1 on violations
--attest	false	Submit attestation after comparison (requires backend)

spooled ci update-baseline

Generate compact baselines from traces.

spooled ci update-baseline \
    --from .spooled/traces/ \
    --out baselines/ \
    --min-runs 3

Flag	Default	Description
--from	.spooled/traces/	Directory containing traces
--out, -o	baselines	Output directory
--agent-id, -a	None	Filter to specific agent (default: all)
--min-runs	0	Minimum runs per intent (0 = no gate)
--max-error-rate	1.0	Max error rate 0–1 (1.0 = no gate)
--max-cv	inf	Max latency coefficient of variation

spooled ci accept-variant

Accept a fingerprint variant as an approved behavioral pattern.

spooled ci accept-variant \
    --intent a1b2c3d4 \
    --fingerprint e5f6g7h8 \
    --baseline baselines/agent.json \
    --reason "prompt update"

spooled ci batch-compare

Compare all traces in a directory against baselines. Works locally on the free tier. The --push flag (sync results to backend) requires Pro.

spooled ci fetch-traces

Download recent traces from the backend for CI comparison — the command behind Pattern 4. Pro feature.

spooled ci fetch-traces \
    --agent-id deal_agent \
    --since 24h \
    --out-dir .spooled/fetched

Flag	Default	Description
--agent-id, -a	(required)	Agent identifier to fetch traces for
--since, -s	"24h"	Time window — duration (24h, 7d) or ISO timestamp
--commit-sha, -c	None	Filter by git commit SHA prefix
--out-dir, -o	.spooled/fetched	Directory to write fetched JSONL files
--limit, -n	20	Maximum traces to fetch (max 50)
--backend-url, -u	None	Backend API URL override

spooled ci history

Show recent CI comparison history from .spooled/ci-history/. Use --push / --pull to sync with the backend.

spooled ci history --agent-id my_agent --limit 50

spooled ci badge

Generate a Spooled Score badge (shields.io) for README or CI.

spooled ci badge --baseline baselines/my_agent.json --format markdown

spooled ci report

Generate a comprehensive behavioral diff report.

spooled ci approve

Accept variants + regenerate baseline + optional git commit.

Behavioral analysis

spooled analyze

Analyze agent behavioral stability across recent runs — which tools are called consistently, which are flaky, and how many unique fingerprints exist. Run your agent a few times first to generate traces.

spooled analyze --agent-id my_agent --runs 10

Flag	Default	Description
--agent-id, -a	(required)	Agent ID to analyze
--from	.spooled/traces/	Trace directory
--runs, -n	0	Number of runs to analyze (0 = all available, capped at 20)
--output, -o	table	Output format: table, json, or csv
--wide, -w	false	Wide output — full tool names, no truncation

Tracing commands

spooled init project

Initialize a project for Spooled. Creates .spooled/ directory and policy file.

spooled init project --with-demo

spooled view trace

View and pretty-print a trace with interaction details.

spooled verify trace

Verify hash chain integrity of a trace.

spooled verify trace .spooled/traces/agent-runid.jsonl --verbose

spooled diff traces

Compare two traces with structural analysis — tool sequence changes, new/removed tools, error pattern differences.

spooled diff traces trace1.jsonl trace2.jsonl

Baseline management

spooled baseline add    # Add baseline from trace
spooled baseline show   # Display baseline stats

Fingerprinting

spooled fingerprint generate  # Generate fingerprint from trace
spooled fingerprint compare  # Compare two fingerprints

Policy

spooled policy init      # Create default policy file
spooled policy validate  # Validate policy YAML
spooled policy show      # Show current policy config

Fleet management

spooled fleet status  # Show fleet health overview
spooled fleet report  # Generate fleet report

Attestation (Pro/Team)

spooled attest create  # Create KMS-signed attestation
spooled attest verify  # Verify attestation signature

Workflow commands

spooled new-agent           # Scaffold a new agent for Spooled
spooled traces              # Manage local traces
spooled session             # View multi-agent trace sessions
spooled watch               # Watch traces in real time
spooled ingest              # Import traces from external systems
spooled keys                # Manage API keys (admin)

Utility commands

spooled doctor   # Health check setup
spooled status   # Backend connection status
spooled whoami   # Show org context for API key
spooled version  # Show version number
spooled demo run # Run demo agent (zero setup)

Exit codes

Code	Meaning
0	Success — all agents passed
1	Blocked — policy violation detected
2	Runtime error — configuration or execution failure

Global flags

--help     Show help for any command
--version  Show version
--quiet    Suppress non-essential output
--debug    Enable debug logging