---
title: CLI
subtitle: 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.

<Steps>
<Step title="Install">

Requires Node.js 18 or later.

```bash
npm install -g @respan/cli
```

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

</Step>
<Step title="Sign in">

```bash
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](https://platform.respan.ai/platform/gateway/api-keys).

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

</Step>
<Step title="Find a request or trace">

```bash
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.

</Step>
</Steps>

## Filter requests

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

```bash
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:

```bash
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](/docs/documentation/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:

```bash
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:

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

The [Agent setup guide](/docs/documentation/agent-setup) covers tracing and gateway integration. Use `respan setup doctor` to check existing coding-agent configuration.