CLI Commands

Command-line interface reference for the Traccia SDK.

The Traccia CLI manages configuration, checks connectivity, and runs eval gates. Python commands use traccia. TypeScript commands use traccia-ts. Pricing commands differ. Python uses traccia pricing status, traccia pricing refresh, and traccia pricing clear. TypeScript uses traccia-ts pricing:status, traccia-ts pricing:refresh, and traccia-ts pricing:clear.

Global Options

These options can be used with any command:

--config PATH

Path to config file (default: ./traccia.toml or ~/.traccia/config.toml)

traccia config init

Initialize a new traccia.toml configuration file in the current directory with default values and helpful comments.

Usage

bash
traccia config init [OPTIONS]

Options

--force

Overwrite existing config file if present

Example

bash
# Create traccia.toml in current directory
traccia config init


# Overwrite existing config
traccia config init --force

Next steps after init

After creating your config file:
  1. Edit the file to add your API key and endpoint
  2. Run traccia doctor to validate
  3. Run traccia check to test connectivity

traccia doctor

Validate your Traccia configuration and diagnose common issues. This command checks for config files, environment variables, validates configuration structure, and reports potential problems.

Usage

bash
traccia doctor [OPTIONS]

What it checks

Config file existence

Looks for traccia.toml in standard locations

Environment variables

Lists all set Traccia env vars

Configuration validity

Validates config structure and values

Exporter configuration

Ensures at least one exporter is enabled

Endpoint setup

Checks if OTLP endpoint is configured when needed

Rate limiting

Reports rate limiting settings if enabled

Example Output

text
🩺 Running Traccia configuration diagnostics...


✅ Found config file: ./traccia.toml


📋 Environment variables:
   ✅ TRACCIA_API_KEY is set


🔍 Validating configuration...
✅ Configuration is valid


📊 Configuration summary:
   • API Key: ✅ Set
   • Endpoint: http://localhost:4318/v1/traces
   • Sample Rate: 1.0
   • OTLP Exporter: ✅ Enabled
   • Console Exporter: ❌ Disabled
   • File Exporter: ❌ Disabled
   • Auto-patching: ✅ Enabled


============================================================
✅ No issues found! Your configuration looks good.


💡 Tip: Run `traccia check` to test connectivity to your endpoint

Example

bash
# Validate default config
traccia doctor


# Validate specific config file
traccia doctor --config /path/to/traccia.toml

traccia check

Test connectivity to your configured exporter endpoint. This command attempts to reach the endpoint and reports whether it's accessible.

Usage

bash
traccia check [OPTIONS]

Options

--endpoint URL

Override endpoint URL for this check (useful for testing different backends)

--api-key KEY

API key for authentication (overrides config)

Examples

bash
# Check configured endpoint
traccia check


# Check specific endpoint
traccia check --endpoint http://localhost:4318/v1/traces


# Check with custom API key
traccia check --api-key your-api-key-here


# Check production endpoint
traccia check --endpoint https://api.traccia.ai/v2/traces --api-key prod-key

Expected responses

The check command may return HTTP 400, 401, or 405 responses from OTLP endpoints, which are expected and indicate the endpoint is reachable (it just doesn't accept HEAD requests). These are reported as successful connectivity tests.

Exit Codes

0Success - endpoint is reachable
1Failure - endpoint unreachable or configuration error

traccia pricing

Manage the local LLM pricing snapshot that the SDK uses to estimate costs at span-end time. The snapshot is stored in ~/.cache/traccia/pricing.json and resolves with higher priority than the bundled snapshot shipped inside the SDK wheel.

traccia pricing status

Show the current pricing source, its age in days, and the number of models in the active snapshot.

bash
traccia pricing status
text
Pricing snapshot status
  Source  : local_cache
  File    : /Users/you/.cache/traccia/pricing.json
  Age     : 1 day(s)
  Models  : 2547
  Warning : None

The SDK emits a logger.info reminder when the snapshot is older than 7 days, and a logger.warning when older than 30 days.

traccia pricing refresh

Download the latest pricing and write it to the local cache. By default, the command tries the Traccia platform first (which maintains an up-to-date snapshot in sync with your org overrides), then falls back to the upstream open-source pricing database if the platform is unreachable.

Usage

bash
traccia pricing refresh [--source upstream]

Options

--source upstream

Skip the platform and fetch directly from the upstream LiteLLM pricing database. Useful when you do not have a Traccia account or want to bypass any org-level overrides. With no flag, the command tries the platform first, then the upstream source. --source platform is a parse error. TypeScript has no --source flag. Use traccia-ts pricing:refresh.

Examples

bash
# Default: platform first, upstream fallback
traccia pricing refresh


# Force upstream (skips platform, no account needed)
traccia pricing refresh --source upstream

Example output

text
# First run — new snapshot downloaded
Pricing updated from platform (2547 models)


# Subsequent run — cached, no download
Pricing is already up to date (304 Not Modified)


# Platform unreachable — fallback used
Platform unreachable, falling back to upstream...
Pricing updated from upstream (2547 models)

ETag caching

The command stores the platform's ETag after each successful download and sends it as If-None-Match on the next run. If pricing has not changed, the platform responds with HTTP 304 and no data is transferred.

traccia pricing clear

Remove the local cache file. The SDK reverts to the bundled snapshot that ships inside the SDK wheel until you run traccia pricing refresh again.

bash
traccia pricing clear
text
Local pricing cache cleared. SDK will use bundled snapshot.

Pricing and the Traccia platform

The platform maintains its own authoritative pricing snapshot independently of your SDK's local cache. Running traccia pricing refresh syncs the platform's current snapshot to your SDK so that llm.cost.usd (SDK-emitted) and platform_cost_usd (platform-recomputed) converge, but the platform will always recompute costs server-side regardless. See Platform Costs for the full picture.

traccia eval

Run a task script against a saved dataset, store an experiment, and exit non-zero when a gate misses. TypeScript is traccia-ts eval. The walkthrough, exit codes, and GitHub Action are in Run Evals In CI.

Usage

bash
traccia eval SCRIPT --output summary.json --dataset DATASET [--scorer NAME]...
traccia-ts eval SCRIPT --output summary.json --dataset DATASET [--scorer NAME]...

Required

SCRIPT

Python file that defines task, or a TypeScript module that exports it. Local scorers live on scorers and are passed as local:name.

--output PATH

Summary JSON. This file is the contract. The process exit code is the gate.

--dataset NAME

Dataset name or id in the workspace for TRACCIA_API_KEY.

Gates

--scorer NAME

Repeatable platform scorer, or local:name.

--informational NAME

Selected scorer that skips the pass-rate bar. An error still fails the check.

--min-pass-rate RATE

Absolute bar from 0 to 1. With no bar, exit 0 is Execution Only.

--max-drop POINTS

Allowed drop in percentage points. 0.05 means five points, not five percent. Needs one baseline. A local scorer cannot pass this bar.

--baseline-prompt NAME / --baseline-experiment ID

Pass one. Add --baseline-panel when the baseline has more than one panel.

--max-task-cost-increase RATIO, --max-judge-cost-increase RATIO, --max-latency-increase RATIO

Relative caps. 0.2 is 20 percent above the baseline. Incomplete cost or latency fails before the ratio is applied.

--allow-dataset-change, --allow-concurrency-mismatch

The dataset flag does not waive a change that happens during the run. The concurrency flag does not waive the latency cap.

--name TITLE

Replaces the whole title. The default is the script name, or the dataset name when the file is task, eval, main, index, or run, followed by eval. When TRACCIA_GIT_HEAD_REF is set, the title adds · and the branch. Otherwise a pull request number adds · PR and that number.

--prompt NAME

Stores that prompt on the experiment so promotion can attach the run. Requires --prompt-version or --prompt-label.

Exit codes

0 pass, 1 quality miss, 2 a bad command, a baseline that cannot be used, a script that will not load, or invalid TRACCIA_PROVIDER_KEYS, 3 untrustworthy evidence, including a task error and a task script that exits early, 4 the experiment did not save, 5 the summary file was not written, 130 the run was interrupted. Evidence is decided before a low score.

Prompt evidence is explicit

evaluate() in Python SDK 0.1.33 and TypeScript SDK 0.1.19 can still attach production when you pass a prompt name with no version or label, and it prints a deprecation warning. traccia eval requires --prompt-version or --prompt-label with --prompt.

Environment Variables

Common environment variables recognized by the CLI and SDK:

TRACCIA_API_KEY or AGENT_DASHBOARD_API_KEY

API key for authentication

TRACCIA_ENDPOINT or AGENT_DASHBOARD_ENDPOINT

Endpoint URL for trace ingestion

TRACCIA_SAMPLE_RATE

Sampling rate (0.0 to 1.0)

TRACCIA_ENABLE_METRICS

Enable OpenTelemetry metrics emission (true/false)

TRACCIA_METRICS_ENDPOINT

OTLP/HTTP endpoint for metrics (overrides config)

TRACCIA_DEBUG

Enable debug logging (true/false)

TRACCIA_PROMPT_API_BASE

Override the prompt and eval API base. traccia eval uses this with TRACCIA_API_KEY.

TRACCIA_PROVIDER_KEYS

JSON object of provider names to API keys for LLM-judge and Jev scorers. It overrides OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, GROQ_API_KEY, and TYPESAFE_API_KEY. Invalid JSON is exit 2. The keys are not written into the summary.

Set these from the job's own variables in any CI. The GitHub Action sets the same variables for you. The names are TRACCIA_GIT_CHECKOUT_SHA, TRACCIA_GIT_GITHUB_SHA, TRACCIA_GIT_HEAD_SHA, TRACCIA_GIT_HEAD_REF, TRACCIA_GIT_BASE_REF, TRACCIA_PR_NUMBER, TRACCIA_GIT_REPOSITORY, and TRACCIA_GIT_ACTOR.

For a complete list of environment variables, see the Configuration Reference.

Common Workflows

Setting up a new project

bash
# 1. Install Traccia
pip install traccia


# 2. Create config file
traccia config init


# 3. Edit traccia.toml to add your settings
# (set endpoint, api_key, etc.)


# 4. Validate configuration
traccia doctor


# 5. Test connectivity
traccia check

Debugging connectivity issues

bash
# Check your configuration
traccia doctor


# Test specific endpoints
traccia check --endpoint http://localhost:4318/v1/traces
traccia check --endpoint https://api.traccia.ai/v2/traces


# Enable debug logging in your app
export TRACCIA_DEBUG=true
python your_app.py

Switching environments

bash
# Development (local OTLP)
export TRACCIA_ENDPOINT=http://localhost:4318/v1/traces
export TRACCIA_DEBUG=true
traccia check


# Production (Traccia platform)
export TRACCIA_ENDPOINT=https://api.traccia.ai/v2/traces
export TRACCIA_API_KEY=your-production-key
traccia check

Next Steps

Run Evals In CI

Exit codes, baselines, and the GitHub Action around traccia eval.

Configuration Reference

Complete configuration file and environment variable documentation

SDK Quickstart

Get started with Traccia in under 5 minutes

Error Reference

Common error codes and solutions

© 2026 Traccia.