AgentDbg CLI Reference: list, view, and export

Complete reference for the agentdbg command-line tool. Covers list, view, and export commands with all flags: —limit, —json, —no-browser, and —port.

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

Option	Short	Default	Description
--limit	-n	20	Maximum number of runs to return
--json	—	off	Print machine-readable JSON instead of a table

Exit codes: 0 success · 10 internal error

Default table output

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 / Option	Short	Default	Description
RUN_ID	—	latest run	Run to open on start. Accepts a full UUID or a short prefix (e.g. first 8 chars).
--host	-H	127.0.0.1	Host address for the server to bind on
--port	-p	8712	Port for the server to listen on
--no-browser	—	off	Start the server without opening your browser
--json	—	off	Print run_id, url, and status as JSON before starting the server

Exit codes: 0 success · 2 run not found · 10 internal error

Open latest run in browser

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 / Option	Short	Required	Description
RUN_ID	—	Yes	Run to export. Accepts a full UUID or a short prefix.
--out	-o	Yes	Output file path (JSON)

Exit codes: 0 success · 2 run not found · 10 internal error

Export using full run ID

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