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:

1. **API key** — saved to `.env`, verified with a demo trace
2. **Agent selection** — auto-detects Claude Code, Cursor, Codex, Gemini CLI, or OpenCode
3. **Skill install** — the agent learns how to set up Respan tracing
4. **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](/content/docs/documentation/resources/cookbooks/trace-cli-coding-agents/index.html) 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`       |