CLI | Respan Docs

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

Install

$ npm install -g @respan/cli

Authentication

$ respan auth login --api-key YOUR_API_KEY

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`