Skip to main content
The 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. 
agentdbg list [--limit N] [--json]
Options
OptionShortDefaultDescription
--limit-n20Maximum number of runs to return
--json—offPrint machine-readable JSON instead of a table
Exit codes: 0 success · 10 internal error 
agentdbg list
The plain-text table contains these columns: 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. 
{
  "spec_version": "0.1",
  "runs": [
    {
      "run_id": "a1b2c3d4-1234-5678-90ab-cdef12345678",
      "run_name": "customer-support-agent",
      "started_at": "2026-04-12T10:30:00.000Z",
      "duration_ms": 4210,
      "status": "ok",
      "counts": {
        "llm_calls": 3,
        "tool_calls": 5,
        "errors": 0,
        "loop_warnings": 0
      }
    }
  ]
}

​
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. 
agentdbg view [RUN_ID] [--host HOST] [--port PORT] [--no-browser] [--json]
Arguments and options
Argument / OptionShortDefaultDescription
RUN_ID—latest runRun to open on start. Accepts a full UUID or a short prefix (e.g. first 8 chars).
--host-H127.0.0.1Host address for the server to bind on
--port-p8712Port for the server to listen on
--no-browser—offStart the server without opening your browser
--json—offPrint run_id, url, and status as JSON before starting the server
Exit codes: 0 success · 2 run not found · 10 internal error 
agentdbg view
Use --no-browser in CI or SSH sessions where a browser cannot open. The URL is printed to stdout so you can copy it manually.
When you use --json, the command prints a JSON object before starting the server: 
{
  "spec_version": "0.1",
  "run_id": "a1b2c3d4-1234-5678-90ab-cdef12345678",
  "url": "http://127.0.0.1:8712/?run_id=a1b2c3d4-1234-5678-90ab-cdef12345678",
  "status": "serving"
}
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. 
agentdbg export RUN_ID --out FILE
Arguments and options
Argument / OptionShortRequiredDescription
RUN_ID—YesRun to export. Accepts a full UUID or a short prefix.
--out-oYesOutput file path (JSON)
Exit codes: 0 success · 2 run not found · 10 internal error 
agentdbg export a1b2c3d4-1234-5678-90ab-cdef12345678 --out run.json
The output file contains three top-level keys: 
{
  "spec_version": "0.1",
  "run": { "...run metadata..." },
  "events": [ "...array of event objects..." ]
}
Parent directories in the --out path are created automatically if they do not exist.

​
agentdbg --version

Prints the installed AgentDbg version and exits. 
agentdbg --version
agentdbg -v
Example output: 
AgentDbg 0.1.0