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

# Inspect and debug runs

> Inspect Archal runs, clone sessions, traces, and account state from the CLI to debug scored agent results without re-running scenarios.

These commands inspect existing runs, sessions, and account state. They do not
run agents.

## `archal traces`

List and inspect scenario traces you own without opening the dashboard.
Requires `archal login` or `ARCHAL_TOKEN`. The default output stays compact; use
`--json` when another coding agent or script needs the full response.

```bash theme={null}
archal traces [name-or-root-id]          # list recent traces, or inspect one by name/id
archal traces list                       # list recent traces
archal traces detail <name-or-root-id>   # show one trace in detail
```

| Flag                       | Description                           | Default          |
| -------------------------- | ------------------------------------- | ---------------- |
| `-n, --limit <count>`      | Number of traces to list              | `20`             |
| `--workspace <name-or-id>` | Read traces from a specific workspace | active workspace |
| `--json`                   | Print machine-readable JSON           | `false`          |

```bash theme={null}
archal traces --workspace acme-prod --limit 5
archal traces detail trace-1746910996
archal traces detail root_01hxyz --json
```

`archal trace` remains available as a compatibility alias.

## `archal inspect session <id>`

Print a hosted session as JSON: services, seeds, TTL, clone URLs, and health.

```bash theme={null}
archal inspect session ses-01hxyz...
```

## `archal inspect run <id>`

Print a managed run bundle as JSON.

```bash theme={null}
archal traces --limit 5         # find the recent run or trace name first
archal inspect run run-01hxyz...
```

## `archal export run <id>`

Export a run as a single JSON document. Pipe it to a file to share a failing run.

```bash theme={null}
archal inspect run run-01hxyz... # confirm the id before exporting
archal export run run-01hxyz... > run.json
archal export run run-01hxyz... --anonymize > run.json
```

| Flag          | Description                                             |
| ------------- | ------------------------------------------------------- |
| `--anonymize` | Redact sensitive evidence payload fields before writing |

## `archal usage`

Print current plan and usage.

```bash theme={null}
archal usage
```

## `archal doctor`

Probe the active clone session: reachability, auth, URL resolution, and tool
surface per clone.

```bash theme={null}
archal doctor
archal doctor --clone github      # probe a single clone
archal doctor --json              # machine-readable output for scripts
```

| Flag             | Description                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `--clone <name>` | Probe a single clone by id (defaults to all clones in the active session) |
| `--json`         | Emit diagnosis as JSON                                                    |