Command Reference
Traces
Browse trace trees, inspect trace facets, and manage trace exports from the CLI.
Use inf trace to inspect multi-step LLM workflows captured by Inference Tracing. It mirrors the dashboard trace viewer for headless debugging: list trace summaries, open a trace tree, render a timeline, inspect captured conversation messages, discover filter facets, and queue/download trace exports.
Alias: inf traces
inf trace upload
Upload a JSONL trace file into the active project. The CLI validates the format locally (OTLP or Langfuse export), uploads it in parts, waits for processing to finish, and prints the upload ID plus line counts. Same flow as the dashboard Upload button and inf dataset upload.
inf trace upload <file>Arguments
| Argument | Required | Description |
|---|---|---|
file | Yes | Path to a .jsonl trace file |
Options
| Flag | Required | Description | Default |
|---|---|---|---|
-n, --name <name> | No | Upload name shown in the Inference platform | Filename without extension |
--no-wait | No | Return after the transfer completes without polling processing | Off |
Uploaded traces appear under the Traces tab once processing completes. Filter them with all-time range and the upload ID (trace_import_id in filters):
# Upload and wait for processing (default)
inf trace upload ./exports/langfuse-traces.jsonl
# Custom upload name
inf trace upload ./traces.jsonl --name prod-replay-2026-04-01
# Queue processing but do not wait
inf trace upload ./traces.jsonl --no-wait
# List traces from a completed upload
inf trace list --range all --filter "trace_import_id=<upload-id>"inf trace list
Display trace summaries in the active project.
inf trace listAlias: inf trace ls
Options
| Flag | Required | Description | Default |
|---|---|---|---|
-l, --limit <n> | No | Maximum number of traces | 25 |
--cursor <cursor> | No | Pagination cursor from a previous response | - |
--sort <key> | No | Sort by start_time, duration, total_cost, total_tokens, span_count, or llm_span_count | Server default |
--order <asc|desc> | No | Sort order | Server default |
--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 | Trace 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 for the raw API payload with full trace IDs, pagination cursors, and aggregate counts.
Examples
# Recent traces
inf trace list
# Failed LLM traces from the last hour
inf trace list --range 1h --kind LLM --status error
# Slow traces by duration, sorted longest first
inf trace list --filter "duration_ms>5000" --sort duration --order desc
# Filter by service and model
inf trace list --service api --model claude-sonnet-4-5inf trace get
Open a single trace and its spans.
inf trace get <trace-id>Alias: inf trace show
Arguments
| Argument | Required | Description |
|---|---|---|
trace-id | Yes | Trace ID |
Options
| Flag | Required | Description | Default |
|---|---|---|---|
--view <view> | No | summary, tree, timeline, thread, spans, or raw | summary |
--span <span-id> | No | Highlight a selected span in the tree view | - |
--limit <n> | No | Maximum spans to fetch for this trace | 1000 |
--cursor <cursor> | No | Span pagination cursor | - |
-o, --output <path> | No | Write raw JSON to a file | - |
The default summary view prints trace metadata and an ASCII span tree. Use --view raw or global --json when piping trace data into scripts.
Examples
# Summary plus span tree
inf trace get 2f0d2b...
# Text waterfall ordered by span start time
inf trace get 2f0d2b... --view timeline
# Conversation-style view from captured input/output messages
inf trace get 2f0d2b... --view thread
# Persist raw trace + spans JSON for local analysis
inf trace get 2f0d2b... --view raw -o trace.jsoninf trace facets
Inspect available trace filter values and counts. This is useful when building a repeatable query and you do not know the exact model, service, environment, or attribute values in a project.
inf trace facetsOptions
inf trace facets accepts the same filter flags as inf trace 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
# Show all default trace facets
inf trace facets --range 7d
# Find model facet values containing "claude"
inf trace facets --facet llm_model_name --search llm_model_name=claude
# Explore values for an OpenTelemetry span attribute
inf trace facets --attribute-key span:gen_ai.operation.nameAdvanced filter syntax
--filter, --metadata, and --resource are repeatable. Quote expressions so your shell does not interpret operators.
| 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_count>=3 | Trace aggregate filter |
llm_model_name~claude | String contains |
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 |
inf trace export
Trace exports create downloadable JSONL files for offline analysis, support escalations, or long-running review workflows.
inf trace export create
Queue an export job.
inf trace export create --range 7d --kind LLM| Flag | Required | Description | Default |
|---|---|---|---|
--from <iso> / --to <iso> | No | Explicit export window | - |
--range <preset> | No | Relative export window | 1d |
--kind <kind> | No | Observation kind filter | All kinds |
--trace-id <id> | No | Trace ID. Repeat or comma-separate values | - |
--session <id> | No | Session ID filter | - |
--user <id> | No | User ID filter | - |
--agent <name> | No | Agent name filter | - |
--model <name> | No | LLM model filter | - |
--status-code <OK|ERROR|UNSET> | No | Span status code filter | - |
--attribute <key=value> | No | Attribute equality match. Repeatable | - |
--wait | No | Poll until the export finishes | Off |
--download | No | Download after the export is ready | Off |
-o, --output <path> | No | Download path | Generated from job ID |
# Queue and print a job ID
inf trace export create --range 30d --kind LLM
# Queue, wait, and download in one command
inf trace export create --range 7d --status-code ERROR --wait --download -o failed-traces.jsonlinf trace export list
inf trace export listinf trace export status
inf trace export status <job-id>inf trace export download
inf trace export download <job-id> -o traces.jsonlRelated commands
inf spanlists and opens individual spans.inf inferenceinspects gateway request/response records.inf dashboardlaunches the interactive terminal dashboard.