The Respan CLI lets you authenticate, integrate coding agents, query traces and logs, manage prompts and datasets, run evaluators, and more.
Install
Setup
The fastest way to get started with Respan. Sets up your API key, installs the Respan skill for your coding agent, and opens the agent to instrument your project.
The wizard walks through:
- API key — saved to
.env, verified with a demo trace
- Agent selection — auto-detects Claude Code, Cursor, Codex, Gemini CLI, or OpenCode
- Skill install — the agent learns how to set up Respan tracing
- Launch — opens the agent with the setup skill pre-loaded
| Command |
Description |
respan setup |
Interactive setup wizard |
respan setup doctor |
Diagnose agent setup (installed skills, API key, configs) |
| Flag |
Description |
--agent <name> |
Skip detection (claude-code, cursor, codex-cli, gemini-cli, opencode) |
--no-instrument |
Skip opening the agent after setup |
Authentication
| Command |
Description |
respan auth login |
Authenticate interactively or with --api-key |
respan auth status |
Check auth status and available profiles |
respan whoami |
Show current authenticated user |
Profiles allow you to manage multiple environments (e.g. staging vs production):
| Flag |
Description |
--profile <name> |
Use or create a named profile |
Any command accepts --profile to target a specific environment.
Integrate
Set up tracing for CLI coding agents with a single command. Each writes a hook to ~/.respan/hooks/ and registers it with the agent. See the CLI agents cookbook for details.
| Command |
Description |
respan integrate claude-code |
Set up tracing for Claude Code |
respan integrate codex-cli |
Set up tracing for Codex CLI |
respan integrate gemini-cli |
Set up tracing for Gemini CLI |
respan integrate opencode |
Set up tracing for OpenCode |
| Flag |
Description |
--customer-id <id> |
Customer identifier attached to traces |
--workflow-name <name> |
Workflow name for grouping traces |
--span-name <name> |
Root span name (defaults to agent name) |
--project-id <id> |
Respan project ID |
--attrs <json> |
Custom attributes as JSON string |
--global |
Apply to all projects |
--local |
Apply to current project only |
--dry-run |
Preview changes without writing files |
Logs
Query and inspect individual LLM request spans.
| Command |
Description |
respan logs list |
List recent logs |
respan logs get <id> |
Get a specific log by ID |
respan logs summary |
Get aggregated stats |
respan logs create |
Create a log span manually |
| Flag |
Description |
--filter <expr> |
Filter results (e.g. model::gpt-4o, cost:gt:0.01) |
--start-time <iso> |
Start of time range |
--end-time <iso> |
End of time range |
--model <name> |
Model for create |
--prompt <text> |
Input for create |
--completion <text> |
Output for create |
Traces
Query and inspect traces (hierarchical groups of spans).
| Command |
Description |
respan traces list |
List recent traces |
respan traces get <id> |
Get a trace with its full span tree |
respan traces summary |
Get trace summary stats |
| Flag |
Description |
--filter <expr> |
Filter results (e.g. total_cost:gt:0.10, customer_identifier::user_123) |
--start-time <iso> |
Start of time range |
--end-time <iso> |
End of time range |
Users
Manage customer and user records.
| Command |
Description |
respan users list |
List users |
respan users get <id> |
Get user details |
respan users create |
Create a user |
respan users update <id> |
Update a user |
| Flag |
Description |
--sort-by <field> |
Sort results (prefix with - for descending) |
--customer-identifier <id> |
Customer identifier for create |
--name <name> |
User display name |
Prompts
Manage prompt templates and versions.
| Command |
Description |
respan prompts list |
List all prompts |
respan prompts get <id> |
Get a prompt with its current version |
respan prompts versions <id> |
List all versions of a prompt |
respan prompts create |
Create a new prompt |
respan prompts create-version <id> |
Create a new version of a prompt |
respan prompts update <id> |
Update prompt metadata |
| Flag |
Description |
--name <name> |
Prompt name |
--model <model> |
Default model |
--messages <json> |
Messages array as JSON |
Datasets
Manage evaluation datasets and their spans.
| Command |
Description |
respan datasets list |
List datasets |
respan datasets get <id> |
Get dataset details |
respan datasets create |
Create a dataset |
respan datasets update <id> |
Update a dataset |
respan datasets spans <id> |
List spans in a dataset |
respan datasets add-spans <id> |
Add existing spans to a dataset |
respan datasets create-span <id> |
Create a new span in a dataset |
| Flag |
Description |
--name <name> |
Dataset name |
--span-ids <ids> |
Comma-separated span IDs for add-spans |
--input <text> |
Span input for create-span |
--output <text> |
Span output for create-span |
Evaluators
Manage and run evaluators on datasets.
| Command |
Description |
respan evaluators list |
List evaluators |
respan evaluators get <id> |
Get evaluator details |
respan evaluators create |
Create an evaluator |
respan evaluators run <id> |
Run an evaluator on a dataset |
respan evaluators update <id> |
Update an evaluator |
| Flag |
Description |
--name <name> |
Evaluator name |
--type <type> |
Evaluator type (llm, human, code) |
--dataset-id <id> |
Target dataset for run |
Experiments
Manage experiments for comparing prompt and model configurations.
| Command |
Description |
respan experiments list |
List experiments |
respan experiments get <id> |
Get experiment details |
respan experiments create |
Create an experiment |
| Flag |
Description |
--name <name> |
Experiment name |
--dataset-id <id> |
Dataset to run against |
Global options
These options work with any command.
| Flag |
Description |
--json |
Output as JSON |
--csv |
Output as CSV |
--limit <n> |
Limit number of results |
--page <n> |
Page number for pagination |
--profile <name> |
Use a named profile |
Filter syntax
All list commands support --filter field:operator:value:
| Operator |
Description |
Example |
| (empty) |
Exact match |
model::gpt-4o |
gt / gte |
Greater than (or equal) |
cost:gt:0.01 |
lt / lte |
Less than (or equal) |
latency:lt:500 |
not |
Not equal |
status_code:not:200 |
icontains |
Case-insensitive contains |
customer_identifier:icontains:alice |
startswith |
Starts with |
model:startswith:gpt |
in |
Value in list |
model:in:gpt-4o,claude-3 |