Command Reference
Spans
Search spans, inspect span payloads, and debug trace steps from the CLI.
Use inf span when you already know you need span-level detail instead of a whole trace tree. It lets you search spans across traces, focus on root or entrypoint spans, inspect captured input/output, and print OpenTelemetry attributes for a single step.
Alias: inf spans
inf span list
Display spans in the active project.
inf span listAlias: inf span ls
Options
| Flag | Required | Description | Default |
|---|---|---|---|
-l, --limit <n> | No | Maximum number of spans | 25 |
--cursor <cursor> | No | Pagination cursor from a previous response | - |
--sort <key> | No | Sort by start_time, duration_ns, cost_total, or total_tokens | Server default |
--order <asc|desc> | No | Sort order | Server default |
--trace-id <id> | No | Limit results to one trace | - |
--text <query> | No | Search captured span input/output text | - |
--scope <all|root|entrypoint> | No | Span scope filter | all |
--range <preset> | No | Relative time range: 1h, 6h, 12h, 1d, 3d, 7d, 14d, 30d, 90d, all | 1d |
--from <iso> | No | Start time. Must be used with --to | - |
--to <iso> | No | End time. Must be used with --from | - |
--kind <kind> | No | Observation kind. Repeat or comma-separate values like LLM,TOOL,AGENT | All kinds |
--provider <name> | No | LLM provider filter | All providers |
--model <name> | No | LLM model filter | All models |
--service <name> | No | OpenTelemetry service.name filter | All services |
--environment <name> | No | Deployment environment filter | All environments |
--user <id> | No | User ID filter | All users |
--session <id> | No | Session ID filter | All sessions |
--agent <name> | No | Agent name filter | All agents |
--status <ok|error> | No | Span status filter | All statuses |
--filter <expr> | No | Advanced typed field filter. Repeatable | - |
--metadata <expr> | No | Span attribute filter. Repeatable | - |
--resource <expr> | No | Resource attribute filter. Repeatable | - |
Use --json to preserve full trace IDs and span IDs for scripting.
Spans are retained for 60 days. 90d and all still return at most the last 60 days of history. Older span history is not available. See Data Retention.
Examples
# Recent spans
inf span list
# Root spans for failed traces in the last day
inf span list --scope root --status error --range 1d
# Spans inside a specific trace
inf span list --trace-id 2f0d2b...
# Search captured IO text for a string
inf span list --text "rate limit"
# Find expensive model spans
inf span list --kind LLM --filter "cost_total>0.05" --sort cost_total --order descinf span get
Open a single span by trace ID and span ID.
inf span get <trace-id> <span-id>Alias: inf span show
Arguments
| Argument | Required | Description |
|---|---|---|
trace-id | Yes | Trace ID containing the span |
span-id | Yes | Span ID |
Options
| Flag | Required | Description | Default |
|---|---|---|---|
--view <view> | No | summary, io, attributes, events, links, or raw | summary |
-o, --output <path> | No | Write raw JSON to a file | - |
Views
| View | Use it for |
|---|---|
summary | Span identity, timing, status, model/provider, token counts, cost, task/session metadata, and domain-specific summary fields |
io | Captured input, output, input messages, output messages, and retrieval documents |
attributes | Span and resource attributes across string, integer, and floating-point maps |
events | Raw OpenTelemetry events JSON |
links | Raw OpenTelemetry links JSON |
raw | Full span JSON exactly as returned by the API |
Examples
# Human-readable summary
inf span get 2f0d2b... 91f8c4...
# Inspect captured prompt/response payloads
inf span get 2f0d2b... 91f8c4... --view io
# Inspect OpenTelemetry attributes
inf span get 2f0d2b... 91f8c4... --view attributes
# Save raw span JSON
inf span get 2f0d2b... 91f8c4... --view raw -o span.jsoninf span facets
Inspect available span filter values and counts.
inf span facetsinf span facets accepts the same filters as inf span list, plus:
| Flag | Required | Description | Default |
|---|---|---|---|
--facet <id> | No | Facet ID. Repeat or comma-separate values | All supported facets |
--search <facet=query> | No | Search within a facet's values. Repeatable | - |
--attribute-key <scope:key> | No | Fetch values for one span: or resource: attribute key | - |
-l, --limit <n> | No | Maximum options per facet | 50 |
Examples
# Discover span facets for recent traffic
inf span facets --range 1d
# Search model facet values
inf span facets --facet llm_model_name --search llm_model_name=claude
# List values for a span attribute
inf span facets --attribute-key span:gen_ai.operation.nameAdvanced filter syntax
The span filter language matches inf trace except trace aggregate fields such as span_count and llm_span_count are not valid for span queries.
| Expression | Meaning |
|---|---|
duration_ms>500 | Numeric comparison. duration and duration_ms are converted to nanoseconds for the API |
total_tokens between:100,500 | Numeric range |
span_name~retrieval | String contains |
llm_provider=anthropic | String equality |
service_name in:api,worker | String set membership |
agent_name not-empty | Non-empty string field |
--metadata gen_ai.operation.name=chat | Span attribute equality |
--resource service.version~2026 | Resource attribute contains |
Common workflows
# Pick a trace, then inspect its LLM spans
TRACE_ID=$(inf trace list --json | jq -r '.traces[0].traceId')
inf span list --trace-id "$TRACE_ID" --kind LLM --json
# Open the first span from that trace
SPAN_ID=$(inf span list --trace-id "$TRACE_ID" --json | jq -r '.spans[0].spanId')
inf span get "$TRACE_ID" "$SPAN_ID" --view ioRelated commands
inf traceopens whole traces, trees, timelines, and trace exports.inf inferenceinspects gateway request/response records.inf dashboardlaunches the interactive terminal dashboard.