phoenix-cli

# Phoenix CLI

## Invocation

```bash
px <resource> <action>                          # if installed globally
npx @arizeai/phoenix-cli <resource> <action>    # no install required
```

The CLI uses singular resource commands with subcommands like `list` and `get`:

```bash
px trace list
px trace get <trace-id>
px trace annotate <trace-id>
px trace add-note <trace-id>
px trace delete <trace-identifier>
px trace-annotations delete
px span list
px span annotate <span-id>
px span add-note <span-id>
px span delete <span-identifier>
px span-annotations delete
px session list
px session get <session-id>
px session annotate <session-id>
px session add-note <session-id>
px session delete <session-id>
px session-annotations delete
px dataset list
px dataset get <name>
px dataset delete <dataset-identifier>
px experiment list
px experiment get <id>
px experiment delete <experiment-id>
px prompt list
px prompt get <prompt-identifier>
px prompt delete <prompt-identifier>
px project list
px project get <name>
px project delete <project-identifier>
px annotation-config list
px annotation-config get <identifier>
px annotation-config create
px annotation-config update <identifier>
px annotation-config delete <id>
px auth login
px auth logout
px auth status
px profile list
px profile show [name]
px profile create <name>
px profile use <name>
px profile edit <name>
px profile delete <name>
px api graphql <query>
px docs fetch
px setup
px self update
```

Every `delete` above is gated: it requires
`PHOENIX_CLI_DANGEROUSLY_ENABLE_DELETES=true` in the environment and prompts for
confirmation unless `-y`/`--yes` is passed (`px profile delete` is local-only and
takes `--yes` without the env gate). Without the env var the command exits
without deleting anything.

## Setup

```bash
export PHOENIX_ENDPOINT=http://localhost:6006
export PHOENIX_PROJECT=my-project
export PHOENIX_API_KEY=your-api-key  # if auth is enabled
```

`PHOENIX_ENDPOINT` is the base URL for API access. It usually holds the same URL as `PHOENIX_COLLECTOR_ENDPOINT`; when only the collector variable is set, the CLI uses it for API access too.

For interactive local use, `px auth login` stores an OAuth session in the selected profile; the session acts with the permissions of the user who logged in. API keys take precedence over OAuth tokens when both are configured.
OAuth access tokens are refreshed automatically for REST, GraphQL, and PXI
requests, and rotated tokens are persisted to the selected profile.

Always use `--format raw --no-progress` when piping to `jq`.

### `px setup` — onboarding

`px setup` connects the app in the current directory to a Phoenix deployment
and writes `.env.phoenix` (mode 0600, gitignored). The interactive flow is for
humans — it prompts, launches coding agents, and polls for traces. **From an
agent, always pass `--no-input`:**

```bash
# Register only: connection + .env.phoenix, no source changes.
px setup --no-input --endpoint http://localhost:6006 --project my-app --format raw
```

Headless requires a clean git repo and, by default, stops after writing the
files — it will not touch source unless you ask. If auth is enabled, also set
`PHOENIX_API_KEY`. The project doesn't need to exist — Phoenix creates it on
first trace. Missing inputs exit `3` with exact remediation; cancel exits `2`.

To also instrument the app, name the lane — headless has no prompt to pick one
from, so `--instrument` requires `--agent`:

```bash
px setup --no-input --instrument --agent claude --yolo --format raw
```

`--yolo` matters: a background agent has no terminal to approve its edits on,
so without it the run stalls until trace verification times out. `--language
python` skips the agent's language detection. `--docs-mcp` connects the
Phoenix docs MCP server to the hand-off agent (`claude mcp add` for claude,
config-file merge for cursor/opencode; codex unsupported) and skips the
`.px/docs` download — the agent searches docs on demand instead; any failure
falls back to the download. `--no-docs-mcp` suppresses the interactive offer.
`--format raw` prints
`{"endpoint","project","files","instrumentation","tracesVerified","tracesUrl"}`
— check `tracesVerified`, which is set only when the API confirmed a trace
arriving, not when the agent claims it finished.

A run whose wait ran out with no trace exits `6`, not `0`: the configuration and
edits are real, but tracing is not confirmed working. Treat that as a failure to
report, not a success — and do not substitute the hand-off agent's own exit code
or summary for the verdict. Registering without `--instrument`, and a human
answering "verify later" at the timeout prompt, both exit `0`.

`tracesVerified` is `false` for a registration-only run too, so it alone can't
tell "nothing to verify" from "no trace arrived". Read `verification`
(`verified` / `notVerified` / `deferred`, absent when there was nothing to
verify) when you need the difference.

Re-runnable slices, so an already-registered repo skips the questions:

```bash
px setup instrument --agent claude   # instrument + verify only
px setup skills                      # install the Phoenix coding-agent skills
```

### `px setup mcp` — register the remote MCP server

Wire the Phoenix remote MCP server (`<endpoint>/mcp`) into a coding agent so it
can query Phoenix data. The endpoint is inferred from `--endpoint`, the active
profile, or `PHOENIX_ENDPOINT`. Bare command prompts for scope (global default) then
agent; `--agent` skips both prompts.

```bash
px setup mcp --agent codex --no-input --format raw
px setup mcp --agent claude --local            # write this repo's .mcp.json
```

Agents: `claude`, `codex`, `gemini`, `cursor`, `opencode`, `vscode`. Scope is
`--global` (default) or `--local` (repo; Codex is global-only). Auth is OAuth by
default (URL-only config, browser login on first use); pass `--header "Name:
value"` (repeatable) for an API-key bearer fallback — for Codex a
`Authorization: Bearer ${VAR}` header becomes `bearer_token_env