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-base

View as Markdown Open the plain-text version of this page.

On this page Browse sections

Authenticate#

Store the API project context once:

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:

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

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

List Traces#

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:

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

Search types are:

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:

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:

provon traces get <trace-id>

Fetch the compact overview and paged span summaries:

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

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

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#

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:

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

The bundle contains:

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:

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 for input formats, Rule selection, thresholds, and the adjudication response contract.

Common Workflows#

Investigate An Error#

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#

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#

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.