CLI Commands

SDK

Command-line interface reference for the Traccia SDK.

The Traccia CLI provides utilities for managing configuration, validating setups, and diagnosing connectivity issues. All commands are accessed through the traccia command.

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 platform|upstream]

Options

--source platform

Fetch from the Traccia platform only. Returns HTTP 304 (Not Modified) and exits immediately if the cached ETag matches — no unnecessary download.

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

Examples

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


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


# Force platform only
traccia pricing refresh --source platform

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.

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)

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

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.