agentdbg CLI is your primary interface for managing runs from the terminal. It reads traces written to ~/.agentdbg/runs/ by default (override with AGENTDBG_DATA_DIR) and lets you list recent runs, open the timeline viewer in your browser, or export a full run to a single JSON file. All commands are available immediately after pip install agentdbg.
agentdbg list
Lists your most recent runs, sorted by start time (newest first). By default it shows the last 20 runs as a formatted table. Use --json when you need to pipe the output to another tool or script.
Exit codes:
0 success · 10 internal error
run_id (first 8 characters), run_name, started_at, duration_ms, llm_calls, tool_calls, and status.
When you pass --json, the output is a JSON object with spec_version and a runs array containing the same fields as the table, plus the full run_id UUID.
agentdbg view
Starts the local timeline viewer server and, by default, opens your browser. The server keeps running until you press Ctrl+C, so you can leave it open while running more agents — new runs appear in the sidebar automatically.
Exit codes:
0 success · 2 run not found · 10 internal error
--json, the command prints a JSON object before starting the server:
The viewer server waits until it is ready before opening the browser, so you will not see a “connection refused” error on startup.
agentdbg export
Exports a single run to a self-contained JSON file. The output contains the run metadata and a complete events array — everything you need to replay or analyze the run offline or share it with a teammate.
Exit codes:
0 success · 2 run not found · 10 internal error
Parent directories in the
--out path are created automatically if they do not exist.