# Tracing CLI

Use the Provon CLI to query API-backed trace summaries, inspect spans, export evidence, and diagnose
trace sources. API-backed trace commands require a project API key. Source-based diagnosis does
not.

## Authenticate

Store the API project context once:

```bash
provon auth token set \
  --api-key "$PROVON_API_KEY" \
  --project "$PROVON_PROJECT_ID"
```

Set `PROVON_BASE_URL` when the target is not the default hosted API:

```bash
export PROVON_BASE_URL="http://127.0.0.1:3000"
```

The API key needs `telemetry:read` for all `provon traces` commands.

## List Traces

```bash
provon traces list --range 6h --limit 20
```

Available filters:

| Option                  | Meaning                                            |
| ----------------------- | -------------------------------------------------- |
| `--range <range>`       | Relative range such as `30m`, `6h`, `24h`, or `7d` |
| `--limit <n>`           | Maximum trace summaries, default `20`              |
| `--cursor <cursor>`     | Opaque cursor from the previous response           |
| `--query <text>`        | Search value                                       |
| `--search-type <types>` | Comma-separated search fields                      |
| `--level <levels>`      | Comma-separated `ok`, `error`, or `unknown`        |

The CLI defaults to a one-hour range. The HTTP API defaults to 24 hours when `range` is omitted.

## Search Traces

Search retained input, output, or other content:

```bash
provon traces search "permission denied" \
  --search-type content,input,output \
  --level error \
  --range 24h
```

Search types are:

```text
trace-id
span-id
user-id
conversation-id
span-name
operation-name
content
input
output
```

Use exact identity search when you already have a trace or conversation ID:

```bash
provon traces search "$TRACE_ID" --search-type trace-id --range 7d
provon traces search "repair-42" --search-type conversation-id --range 7d
```

## Inspect A Trace

Fetch all normalized spans:

```bash
provon traces get <trace-id>
```

Fetch the compact overview and paged span summaries:

```bash
provon traces overview <trace-id> --limit 100
```

Pass `--cursor` with `nextSpanCursor` to continue a large overview:

```bash
provon traces overview <trace-id> \
  --limit 100 \
  --cursor "<nextSpanCursor>"
```

`traces get` returns complete normalized spans and is not paginated. Use `overview` first for large
traces when you only need identity, timing, status, usage, cost, and previews.

## Summarize Telemetry

```bash
provon traces summarize <trace-id> --top 5
```

This command returns a compact telemetry summary from the API containing:

- duration and span counts;
- failed span count;
- token and cost totals when available;
- provider and model dimensions;
- the slowest spans;
- failed span details.

`traces summarize` does not run diagnostic Rules and does not generate Findings. Use
`provon diagnose` for diagnosis.

## Export Evidence

Export an API-backed trace for source-based investigation or a coding agent:

```bash
provon traces export <trace-id> --out ./trace-evidence
```

The bundle contains:

```text
manifest.json
trace.jsonl
spans.jsonl
overview.json
git_context.json
```

`git_context.json` records the current repository, branch, commit, remote, and dirty paths when the
command runs inside a Git repository. It does not copy repository content.

Useful options:

| Option                     | Meaning                               |
| -------------------------- | ------------------------------------- |
| `--out <dir>`              | Output directory                      |
| `--force`                  | Overwrite files that already exist    |
| `--overview-page-size <n>` | Span-summary page size, default `500` |
| `--no-git-context`         | Do not include current Git context    |

## Diagnose A Trace Source

Run the built-in Rules against a bundle, transcript, OTLP file, normalized span file, or stdin:

```bash
provon diagnose ./trace-evidence
provon diagnose ~/.claude/projects/example/session.jsonl
provon diagnose ./spans.jsonl --deterministic-only
cat ./spans.jsonl | provon diagnose - --input-format provon-spans
```

Source-based diagnosis:

- uses the same diagnostic Rule definitions as the server;
- needs no API key;
- does not upload telemetry;
- does not persist Findings;
- does not create GitHub issues;
- can request hash-bound adjudication from the calling Agent.

See [Trace diagnosis with CLI](./trace-diagnosis.md) for input formats, Rule selection, thresholds, and
the adjudication response contract.

## Common Workflows

### Investigate An Error

```bash
provon traces search "run-tests" \
  --search-type span-name,content \
  --level error \
  --range 24h

provon traces overview <trace-id>
provon traces get <trace-id>
```

### Hand Evidence To A Coding Agent

```bash
provon traces export <trace-id> --out ./trace-evidence
provon diagnose ./trace-evidence
```

The calling Agent can inspect the exported spans alongside repository context and adjudicate only
the candidates supplied by Provon.

### CI Screening

```bash
provon diagnose ./artifacts/agent-trace.jsonl \
  --deterministic-only \
  --min-score 0.5 \
  --min-confidence 0.7
```

Deterministic-only mode makes no model call and intentionally has lower recall for semantic
failures.

## Related Docs

- [Explore traces](./trace-explorer.md)
- [Trace read API](./trace-api.md)
- [Trace diagnosis with CLI](./trace-diagnosis.md)
- [Agent transcript sync](./agent-transcripts.md)
- [Tracing troubleshooting](./troubleshooting.md)