> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Inspect & logs
description: Reference for inspecting execution runs, distributed traces, and logs from the CLI.
category: CLI
last_verified: 2026-07-24
hideRightSidebar: true
---

**`agnt5 inspect`** looks at what already happened: execution runs, distributed traces, and their logs. **`agnt5 logs`** tails deployment-level logs. **`agnt5 deployments`** is registered but not yet implemented.


**Commands**: `agnt5 inspect runs ls`, `agnt5 inspect runs describe <runId>`, `agnt5 inspect trace --run-id <id>`, `agnt5 inspect logs --run-id <id>`, `agnt5 logs [deployment-id]`
**Key flags**: `--status`, `--component`, `--since`, `--watch`/`-w` (runs); `--run-id`/`-r` (trace, logs); `--follow`/`-f`, `--tail` (logs)
**Not implemented**: `agnt5 deployments` (aliases `list`, `ls`) always returns "list functionality not yet implemented" — use `agnt5 inspect runs ls` or `agnt5 projects` instead


## Command summary

| Command | Purpose |
| --- | --- |
| `inspect runs ls` | List execution runs for the current project. |
| `inspect runs describe <runId>` | Show detailed status, timing, and LLM usage for one run. |
| `inspect trace` | Show the distributed trace (span tree) for a run. |
| `inspect logs` | Show logs scoped to one run. |
| `logs [deployment-id]` | Show deployment-level logs from the control plane. |
| `deployments` | Not yet implemented — reserved. |

## `agnt5 inspect runs ls`

```bash
agnt5 inspect runs ls [options]
```

Lists execution runs for the current project.

| Flag | Description |
| --- | --- |
| `--status <status>` | Filter by status: `completed`, `failed`, `running`, `pending`. |
| `--component <name>` | Filter by component name. |
| `--component-type <type>` | Filter by type: `function`, `workflow`, `agent`. |
| `--since <window>` | Time window, e.g. `1h`, `24h`, `7d`. |
| `--limit <n>` | Maximum runs to show. Default: `20`. |
| `--watch`, `-w` | Auto-refresh every 2 seconds. |

```bash
agnt5 inspect runs ls
agnt5 inspect runs ls --status failed --since 24h
agnt5 inspect runs ls --component my-workflow --watch
```

## `agnt5 inspect runs describe`

```bash
agnt5 inspect runs describe <runId>
```

Shows detailed information about one run: status, timing, LLM usage, and error info if it failed. No flags — use the global `--output json` for machine-readable output.

```bash
agnt5 inspect runs describe run_9f2a1c
```

## `agnt5 inspect trace`

```bash
agnt5 inspect trace --run-id <id> [options]
```

Shows the distributed trace for a run as a span tree with durations.

| Flag | Description |
| --- | --- |
| `--run-id <id>`, `-r` | Run ID to trace. **Required.** |
| `--flat` | Show a flat list instead of a tree. |
| `--verbose` | Print span attributes for spans that have them. |

```bash
agnt5 inspect trace --run-id run_9f2a1c
agnt5 inspect trace -r run_9f2a1c --flat --verbose
```

## `agnt5 inspect logs`

```bash
agnt5 inspect logs --run-id <id> [options]
```

Shows logs for a specific execution run — narrower than `agnt5 logs`, which is scoped to a deployment.

| Flag | Description |
| --- | --- |
| `--run-id <id>`, `-r` | Run ID to fetch logs for. **Required.** |
| `--severity <level>` | Filter by severity: `DEBUG`, `INFO`, `WARN`, `ERROR`. |
| `--follow`, `-f` | Stream logs in real time. |
| `--tail <n>` | Show the last N lines. `0` (default) shows all. |

```bash
agnt5 inspect logs --run-id run_9f2a1c --severity ERROR
agnt5 inspect logs -r run_9f2a1c --follow
```

## `agnt5 logs`

```bash
agnt5 logs [deployment-id] [options]
```

Shows deployment-level logs from the control plane. If no ID is given, resolves the latest deployment for the current project.

| Flag | Description |
| --- | --- |
| `--follow`, `-f` | Follow log output via server-sent events. |
| `--tail <n>` | Number of lines to show from the end. Default: `100`. |
| `--since <window>` | Show logs since a timestamp, e.g. `2h`, `30m`, `2026-01-01T00:00:00Z`. |
| `--timestamps` | Show timestamps in log output. |

```bash
agnt5 logs
agnt5 logs <deployment-id> --follow
agnt5 logs --since 2h --timestamps
```

## `agnt5 deployments`

```bash
agnt5 deployments [options]
```

Aliases: **`agnt5 list`**, **`agnt5 ls`**. Registered but **not yet implemented** — every invocation currently returns `list functionality not yet implemented`, regardless of flags. Use `agnt5 inspect runs ls` for run history or `agnt5 projects` for project listing until this ships.

## Next steps

- [Deploy commands](/docs/cli/deploy.md): `agnt5 deployment status`/`errors` for the current project's latest deployment, and `agnt5 deploy status <id>` for a specific one.
- [Run commands](/docs/cli/run.md): produce a run to inspect.
- [Automation & agents](/docs/cli/automation.md): `agnt5 schema` for machine-readable command introspection.
- [Troubleshooting](/docs/cli/troubleshooting.md): diagnosing a failed run or deployment.