> ## Documentation Index
> Fetch the complete documentation index at: https://refinehq.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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

<CodeGroup>
  ```bash Default table output theme={null}
  agentdbg list
  ```

  ```bash Last 5 runs theme={null}
  agentdbg list --limit 5
  ```

  ```bash JSON output theme={null}
  agentdbg list --json
  ```
</CodeGroup>

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.

```json theme={null}
{
  "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.

```bash theme={null}
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

<CodeGroup>
  ```bash Open latest run in browser theme={null}
  agentdbg view
  ```

  ```bash Open a specific run by prefix theme={null}
  agentdbg view a1b2c3d4
  ```

  ```bash Start server only, no browser theme={null}
  agentdbg view --no-browser
  ```

  ```bash Custom port theme={null}
  agentdbg view --port 9000
  ```

  ```bash Custom port without browser theme={null}
  agentdbg view --port 9000 --no-browser
  ```

  ```bash JSON output (for scripting) theme={null}
  agentdbg view --json
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

When you use `--json`, the command prints a JSON object before starting the server:

```json theme={null}
{
  "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"
}
```

<Note>
  The viewer server waits until it is ready before opening the browser, so you will not see a "connection refused" error on startup.
</Note>

***

## `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.

```bash theme={null}
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

<CodeGroup>
  ```bash Export using full run ID theme={null}
  agentdbg export a1b2c3d4-1234-5678-90ab-cdef12345678 --out run.json
  ```

  ```bash Export using short prefix theme={null}
  agentdbg export a1b2c3d4 -o ./exports/run.json
  ```
</CodeGroup>

The output file contains three top-level keys:

```json theme={null}
{
  "spec_version": "0.1",
  "run": { "...run metadata..." },
  "events": [ "...array of event objects..." ]
}
```

<Note>
  Parent directories in the `--out` path are created automatically if they do not exist.
</Note>

***

## `agentdbg --version`

Prints the installed AgentDbg version and exits.

```bash theme={null}
agentdbg --version
agentdbg -v
```

Example output:

```
AgentDbg 0.1.0
```