For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordPlatform
DocumentationIntegrationsAPI referenceSDKsChangelog
DocumentationIntegrationsAPI referenceSDKsChangelog
    • Overview
    • Live demo
      • MCP
      • CLI
      • Agent
  • Get started
    • Start tracing
    • Setup evals
    • Use gateway
  • Observability & evals
    • Users
  • Gateway
    • Limits
  • Admin
    • API keys
    • Provider keys
    • Workspaces & projects
    • Collaborate
  • Resources
  • Security & Support
    • Support
    • Status
LogoLogo
DiscordPlatform
On this page
  • Install
  • Setup
  • Authentication
  • Integrate
  • Logs
  • Traces
  • Users
  • Prompts
  • Datasets
  • Evaluators
  • Experiments
  • Global options
  • Filter syntax
Use AI

CLI

Manage your Respan observability from the command line.
Was this page helpful?
Previous

Agent

Ask questions about your traces, logs, and metrics directly in the platform.
Next
Built with

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

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.

$npx @respan/cli setup

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
CommandDescription
respan setupInteractive setup wizard
respan setup doctorDiagnose agent setup (installed skills, API key, configs)
FlagDescription
--agent <name>Skip detection (claude-code, cursor, codex-cli, gemini-cli, opencode)
--no-instrumentSkip opening the agent after setup

Authentication

$respan auth login --api-key YOUR_API_KEY
CommandDescription
respan auth loginAuthenticate interactively or with --api-key
respan auth statusCheck auth status and available profiles
respan whoamiShow current authenticated user

Profiles allow you to manage multiple environments (e.g. staging vs production):

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

CommandDescription
respan integrate claude-codeSet up tracing for Claude Code
respan integrate codex-cliSet up tracing for Codex CLI
respan integrate gemini-cliSet up tracing for Gemini CLI
respan integrate opencodeSet up tracing for OpenCode
FlagDescription
--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
--globalApply to all projects
--localApply to current project only
--dry-runPreview changes without writing files

Logs

Query and inspect individual LLM request spans.

CommandDescription
respan logs listList recent logs
respan logs get <id>Get a specific log by ID
respan logs summaryGet aggregated stats
respan logs createCreate a log span manually
FlagDescription
--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).

CommandDescription
respan traces listList recent traces
respan traces get <id>Get a trace with its full span tree
respan traces summaryGet trace summary stats
FlagDescription
--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.

CommandDescription
respan users listList users
respan users get <id>Get user details
respan users createCreate a user
respan users update <id>Update a user
FlagDescription
--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.

CommandDescription
respan prompts listList 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 createCreate a new prompt
respan prompts create-version <id>Create a new version of a prompt
respan prompts update <id>Update prompt metadata
FlagDescription
--name <name>Prompt name
--model <model>Default model
--messages <json>Messages array as JSON

Datasets

Manage evaluation datasets and their spans.

CommandDescription
respan datasets listList datasets
respan datasets get <id>Get dataset details
respan datasets createCreate 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
FlagDescription
--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.

CommandDescription
respan evaluators listList evaluators
respan evaluators get <id>Get evaluator details
respan evaluators createCreate an evaluator
respan evaluators run <id>Run an evaluator on a dataset
respan evaluators update <id>Update an evaluator
FlagDescription
--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.

CommandDescription
respan experiments listList experiments
respan experiments get <id>Get experiment details
respan experiments createCreate an experiment
FlagDescription
--name <name>Experiment name
--dataset-id <id>Dataset to run against

Global options

These options work with any command.

FlagDescription
--jsonOutput as JSON
--csvOutput 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:

OperatorDescriptionExample
(empty)Exact matchmodel::gpt-4o
gt / gteGreater than (or equal)cost:gt:0.01
lt / lteLess than (or equal)latency:lt:500
notNot equalstatus_code:not:200
icontainsCase-insensitive containscustomer_identifier:icontains:alice
startswithStarts withmodel:startswith:gpt
inValue in listmodel:in:gpt-4o,claude-3