Get started

CLI

Manage your Respan observability from the command line.

The Respan CLI lets you authenticate, integrate coding agents, query traces and logs, manage prompts and datasets, run evaluators, and more.

Setup

Install

$npm install -g @respan/cli

Authenticate

$respan auth login --api-key YOUR_API_KEY

Or interactively (opens a prompt to choose API key or browser login):

$respan auth login

Check your auth status:

$respan whoami
$respan auth status

Profiles

Use named profiles to manage multiple environments:

$# Login with a named profile
$respan auth login --api-key KEY --profile staging
$
$# Use a profile for any command
$respan logs list --profile staging
$
$# Check which profiles exist
$respan auth status

Configuration

$respan config list
$respan config get activeProfile
$respan config set activeProfile staging

Integrate

Set up tracing for CLI coding agents with a single command. This installs hooks that capture every agent turn and send it to Respan.

$respan integrate claude-code
$respan integrate codex-cli
$respan integrate gemini-cli
$respan integrate opencode

Each command writes a hook script to ~/.respan/hooks/ and registers it with the agent’s config. See the CLI agents cookbook for details.

Flags

$respan integrate claude-code \
>  --customer-id "dev-alice" \
>  --workflow-name "feature-work" \
>  --project-id "proj_123" \
>  --attrs '{"team": "backend", "sprint": "2025-Q3"}'
FlagDescription
--customer-idCustomer identifier for traces
--workflow-nameWorkflow name for grouping
--span-nameRoot span name (defaults to agent name)
--project-idRespan project ID
--attrsCustom attributes as JSON
--globalApply to all projects
--localApply to current project only
--dry-runPreview changes without writing

Features

Logs

Query and inspect LLM request logs (spans).

$# List recent logs
$respan logs list
$
$# Filter by model and cost
$respan logs list --filter model::gpt-4o --filter cost:gt:0.01
$
$# Filter by time range
$respan logs list --start-time 2025-01-01T00:00:00Z --end-time 2025-01-02T00:00:00Z
$
$# Get a specific log
$respan logs get LOG_UNIQUE_ID
$
$# Get aggregated stats
$respan logs summary --start-time 2025-03-01T00:00:00Z
$
$# Create a log span manually
$respan logs create --model gpt-4o --prompt "Hello" --completion "Hi there"

Traces

Query and inspect traces (groups of related spans).

$# List recent traces
$respan traces list
$
$# Filter by cost
$respan traces list --filter total_cost:gt:0.10
$
$# Filter by customer
$respan traces list --filter customer_identifier::user_123
$
$# Get a trace with its full span tree
$respan traces get TRACE_UNIQUE_ID
$
$# Get trace summary stats
$respan traces summary --start-time 2025-03-01T00:00:00Z

Users

Manage customer/user records.

$# List users sorted by cost
$respan users list --sort-by -total_cost
$
$# Get user details
$respan users get USER_ID
$
$# Create a user
$respan users create --customer-identifier "user_alice" --name "Alice"
$
$# Update a user
$respan users update USER_ID --name "Alice Smith"

Prompts

Manage prompt templates and versions.

$# List all prompts
$respan prompts list
$
$# Get a prompt with current version
$respan prompts get PROMPT_ID
$
$# List all versions
$respan prompts versions PROMPT_ID
$
$# Create a new prompt
$respan prompts create --name "customer-support" --model gpt-4o \
>  --messages '[{"role": "system", "content": "You are a helpful support agent."}]'
$
$# Create a new version
$respan prompts create-version PROMPT_ID \
>  --messages '[{"role": "system", "content": "Updated system prompt."}]'
$
$# Update prompt metadata
$respan prompts update PROMPT_ID --name "new-name"

Datasets

Manage evaluation datasets and their spans.

$# List datasets
$respan datasets list
$
$# Create a dataset
$respan datasets create --name "qa-test-set"
$
$# Get dataset details
$respan datasets get DATASET_ID
$
$# List spans in a dataset
$respan datasets spans DATASET_ID
$
$# Add existing spans to a dataset
$respan datasets add-spans DATASET_ID --span-ids "id1,id2,id3"
$
$# Create a new span in a dataset
$respan datasets create-span DATASET_ID --input "What is 2+2?" --output "4"
$
$# Update dataset
$respan datasets update DATASET_ID --name "renamed-set"

Evaluators

Manage and run evaluators on datasets.

$# List evaluators
$respan evaluators list
$
$# Get evaluator details
$respan evaluators get EVALUATOR_ID
$
$# Create an evaluator
$respan evaluators create --name "accuracy-check" --type llm
$
$# Run an evaluator on a dataset
$respan evaluators run EVALUATOR_ID --dataset-id DATASET_ID
$
$# Update an evaluator
$respan evaluators update EVALUATOR_ID --name "updated-name"

Experiments

Manage experiments for comparing prompt/model configurations.

$# List experiments
$respan experiments list
$
$# Get experiment details
$respan experiments get EXPERIMENT_ID
$
$# Create an experiment
$respan experiments create --name "model-comparison" --dataset-id DATASET_ID

Query options

These options work across all list commands.

Output formats

$respan logs list              # table (default)
$respan logs list --json       # JSON
$respan logs list --csv        # CSV

Pagination

$respan logs list --limit 50 --page 2
$respan traces list --limit 20 --page 3

Filtering

All list commands support --filter with the format field:operator:value:

$respan logs list --filter model::gpt-4o          # exact match
$respan logs list --filter cost:gt:0.01           # greater than
$respan traces list --filter total_cost:gt:0.10   # works on traces too
$respan users list --filter customer_identifier:icontains:alice
OperatorDescription
(empty)Exact match
gt, gteGreater than (or equal)
lt, lteLess than (or equal)
notNot equal
icontainsCase-insensitive contains
startswithStarts with
inValue in list