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.
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 |
trace_import_id in filters):
inf trace list
Display trace summaries in the active project.
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 | - |
--json for the raw API payload with full trace IDs, pagination cursors, and aggregate counts.
Examples
inf trace get
Open a single trace and its spans.
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 | - |
--view raw or global --json when piping trace data into scripts.
Examples
inf 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.
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
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.
| 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 |
inf trace export list
inf trace export status
inf trace export download
Related commands
inf spanlists and opens individual spans.inf inferenceinspects gateway request/response records.inf dashboardlaunches the interactive terminal dashboard.