Phoenix CLI (@arizeai/phoenix-cli)#

@arizeai/phoenix-cli is a TypeScript CLI for Arize Phoenix, published to npm and invoked as px (or pxi for the AI chat interface). It lives in js/packages/phoenix-cli within the main Phoenix repository and is released independently on npm.

• Binary entry points: px and phoenix-cli → build/index.js; pxi → build/pxi/index.js 1
• Node requirement: ≥22 1
• Current version: 1.13.0 1
• npm: https://www.npmjs.com/package/@arizeai/phoenix-cli

Key capabilities 2:

• Query and pipe Phoenix data (traces, spans, sessions, datasets, experiments, prompts) as JSON
• Agent-assisted onboarding via px setup — auto-instruments an app and verifies a real trace lands
• OAuth login (px auth login) with automatic token refresh
• Interactive terminal AI chat (pxi) backed by the Phoenix PXI server-agent 3

Installation and Configuration#

npm install -g @arizeai/phoenix-cli
px --help

For self-updates: px self update checks the npm registry and upgrades the global install in place, supporting npm, pnpm, bun, and deno. 2

Configuration precedence (highest wins): CLI flags → process environment → active profile → .env.phoenix file → built-in defaults. 2

Key environment variables 2:

The CLI auto-discovers the nearest .env.phoenix dotenv file by walking up from the current working directory. 4 This is the intended destination for credentials written by px setup.

px setup — Onboarding Wizard#

Added in v1.9.0 (July 14, 2026) 5. Source: src/commands/setup.ts.

px setup runs an end-to-end onboarding flow from the app root 2:

1. Git safety check (prevents accidental credential commits)
2. Phoenix connection setup (endpoint, project, optional auth) → writes .env.phoenix
3. Optional: hands a coding agent (Claude Code, Codex, Cursor, OpenCode) an instrumentation task
4. API-verified trace check — polls the Phoenix API until a real trace lands in the project
5. Optional: installs Phoenix skills so the agent can query captured traces

The agent receives a structured prompt from src/setup/prompts/instrumentationPrompt.ts. The comment in that file states: "Every rule is load-bearing — do not trim a rule without replacing the protection it provides." 6

For CI/headless use, flags replace interactive prompts: --endpoint, --project, --agent, --no-input, --language, --instrument/--no-instrument, --skills/--no-skills. 4

Subcommands:

• px setup instrument — re-run just the instrumentation + verification lane
• px setup skills — install Phoenix skills only
• px setup mcp — register the Phoenix remote MCP server with a coding agent (v1.10.0+, supports claude, codex, gemini, cursor, opencode, vscode) 7

Known Issue: Silent Trace Loss Causes False Verification Success#

Root Cause#

PHOENIX_COLLECTOR_ENDPOINT is documented as a base URL. Standard Phoenix SDKs (register() in Python and TypeScript) append the OTLP path (/v1/traces) themselves. However, @mastra/arize's ArizeExporter — and any other full-URL exporter — POSTs to the endpoint exactly as given, with no path appended. 8

Result: spans go to the wrong HTTP path. Mastra's batching exporter swallows the 404, the run looks clean, and px setup's verification step can report success even though no trace landed in Phoenix. 9 8

What NOT to Do#

Do not set PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces as a workaround. That breaks phoenix.client.Client (which appends its own path segments) and px setup's own endpoint probing. 10 The path must be appended at the exporter call site:

// Correct pattern for full-URL exporters (e.g. ArizeExporter)
new ArizeExporter({
  endpoint: `${process.env.PHOENIX_COLLECTOR_ENDPOINT}/v1/traces`,
})

Fix Status#

PR #14891 (open as of 2026-07-29) addresses this by: 11

1. Adding a new rule to the agent instrumentation prompt explicitly calling out that full-URL exporters require <endpoint>/v1/traces and must not rewrite the environment variable.
2. Updating setup/copy.ts verification messaging to name the wrong OTLP path as the most likely cause when traces don't verify — the one failure mode that produces no error anywhere.

Known Issue: Unknown Command Error Gives No Upgrade Hint#

If @arizeai/phoenix-cli is installed below v1.9.0, running px setup fails with error: unknown command 'setup' and no indication that upgrading is the answer. The package releases every few days, making stale global installs a recurring issue. 12

Tracked in Issue #14878. Until the unknown-command handler is patched to suggest npm i -g @arizeai/phoenix-cli@latest, run px self update to upgrade in place.

Source Map#