Traces

Use inf trace to inspect multi-step LLM workflows captured by Catalyst 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 Catalyst	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 list

Alias: 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-5

`inf 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.json

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 facets

Options

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.name

Advanced 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.jsonl

`inf trace export list`

inf trace export list

`inf trace export status`

inf trace export status <job-id>

`inf trace export download`

inf trace export download <job-id> -o traces.jsonl

inf span lists and opens individual spans.
inf inference inspects gateway request/response records.
inf dashboard launches the interactive terminal dashboard.

Get Started

Command Reference

`inf trace upload`

Arguments

Options

`inf trace list`

Options

Examples

`inf trace get`

Arguments

Options

Examples

`inf trace facets`

Options

Examples

Advanced filter syntax

`inf trace export`

`inf trace export create`

`inf trace export list`

`inf trace export status`

`inf trace export download`

​inf trace upload

​Arguments

​Options

​inf trace list

​Options

​Examples

​inf trace get

​Arguments

​Options

​Examples

​inf trace facets

​Options

​Examples

​Advanced filter syntax

​inf trace export

​inf trace export create

​inf trace export list

​inf trace export status

​inf trace export download

​Related commands

`inf trace upload`

Arguments

Options

`inf trace list`

Options

Examples

`inf trace get`

Arguments

Options

Examples

`inf trace facets`

Options

Examples

Advanced filter syntax

`inf trace export`

`inf trace export create`

`inf trace export list`

`inf trace export status`

`inf trace export download`

Related commands