CLI

Query logs and traces, and manage Respan from your terminal.

Use respan to inspect your application’s requests and traces or call Respan tools from scripts.

Install

Requires Node.js 18 or later.


npm install -g @respan/cli

To run without installing, use npx @respan/cli <command>.

Sign in


respan auth login

Choose Respan Platform or Enterprise, then API key (recommended) or Browser login. Get an API key from Gateway › API keys in the platform .

If you already export RESPAN_API_KEY or have it in your project’s .env, you can skip login.

Find a request or trace


respan logs list --limit 5
respan traces list --limit 5
respan traces get <trace_unique_id>

Copy a trace_unique_id from the list to inspect its spans. logs list shows the last hour by default; use --start-time and --end-time to change the range.

Filter requests

Repeat --filter field:operator:value to combine conditions. Leave the operator empty for an exact match.


respan logs list --filter model::gpt-5.5 --filter cost:gt:0.01 --sort-by -cost
respan logs list --filter metadata__env::production --json

Run respan logs list --help for supported fields and operators.

Use the same tools as MCP

List tools and their arguments, then call one with JSON input:


respan tools list --categories
respan tools list --category logs --json
respan tools call log_list --input '{"page_size":5,"environment":"prod"}'
respan tools call trace_get --input '{"trace_id":"your-trace-id"}'

These call the same server as MCP. Use respan tools list --json for all tool schemas. Write tools apply changes immediately.

For larger inputs, save the arguments in a JSON file:


respan tools call log_list --input-file arguments.json

Profiles and output

Save separate credentials with respan auth login --profile-name <name> and select them with --profile <name>.

Option	Use it to
`--json`, `--csv`	Export data-command results. `tools call` always returns JSON.
`--api-key <key>`	Use a key for this command.
`--profile <name>`	Select saved credentials. An exported `RESPAN_API_KEY` still takes precedence.
`--base-url <url>`	Override the API URL for this command.

Run respan --help to list commands, or respan <command> --help for flags. Use respan auth logout to remove saved credentials.

Set up your application

Paste this into your coding agent:


Set up Respan for me: fetch and follow https://respan.ai/docs/agent-setup.md

The Agent setup guide covers tracing and gateway integration. Use respan setup doctor to check existing coding-agent configuration.