CLI Reference¶

agentguard includes a backend-aware CLI for trace inspection, migration, reporting, generated tests, and the local dashboard.

Install¶

pip install awesome-agentguard
agentguard --help

Initialise a SQLite trace store:

agentguard traces init ./traces
agentguard traces init --db-path ./traces/agentguard_traces.db

List recorded sessions:

agentguard traces list ./traces
agentguard traces list ./traces --json

Inspect one session:

agentguard traces show agent_run_001 ./traces
agentguard traces show ./traces --session-id agent_run_001 --tool search_web --status failure --json

Aggregate statistics:

agentguard traces stats ./traces
agentguard traces stats ./traces --session agent_run_001 --json

Generate a JSON report:

agentguard traces report ./traces --output report.json
agentguard traces report ./traces --entries --session agent_run_001

Import legacy JSONL traces into SQLite:

agentguard traces import ./legacy_traces ./traces

Export traces to JSONL:

agentguard traces export ./traces --output-dir ./trace-export
agentguard traces export ./traces --session agent_run_001 --output-dir ./trace-export

Launch the local SQLite dashboard:

agentguard traces serve ./traces
agentguard traces serve --db-path ./traces/agentguard_traces.db --port 9000

Most trace commands accept:

If omitted, the CLI infers the backend from the storage path. SQLite is the default for newly initialised stores.

Generate pytest cases from traces:

agentguard generate ./traces --output tests/test_generated.py
agentguard generate ./traces --backend sqlite --session agent_run_001

agentguard registry
agentguard benchmark --model gpt-4o-mini
agentguard policy validate agentguard.toml
agentguard policy apply agentguard.toml