phoenix-cli-development

# Phoenix CLI Design Specification

The Phoenix CLI (`px`) is a command-line interface for the Phoenix AI observability platform. It serves two distinct audiences simultaneously: **humans** typing commands in a terminal and **coding agents** (Claude Code, Cursor, Codex, Gemini CLI) executing commands programmatically.

This specification uses RFC 2119 keywords (MUST, SHOULD, MAY, etc.) to indicate requirement strength.

## Command Structure: Noun-Verb

All commands MUST follow a **noun-verb** pattern, modeled after the GitHub CLI (`gh`):

```
px <resource> <action> [arguments] [options]
```

Resource names MUST be **singular** — they name the type of thing you're acting on, not how many:

```bash
px project list              # not "px projects"
px project create            # not "px create-project"
px trace get <trace-id>
px dataset get <name-or-id>
px auth status
```

### Standard verbs

Commands SHOULD use these verbs consistently across all resources:

| Verb     | Purpose                       | Takes argument? | Example                             |
| -------- | ----------------------------- | --------------- | ----------------------------------- |
| `list`   | List/query multiple resources | No (uses flags) | `px project list --limit 10`        |
| `get`    | Fetch a single resource by ID | Yes (required)  | `px trace get <trace-id>`           |
| `create` | Create a new resource         | Varies          | `px project create --name foo`      |
| `update` | Modify an existing resource   | Yes (required)  | `px project update <id> --name bar` |
| `delete` | Remove a resource             | Yes (required)  | `px project delete <id>`            |

Not every resource supports every verb — datasets MAY omit `create` via CLI if the primary flow is through the SDK. Commands SHALL only add verbs that make sense for the resource.

Additional verbs for specialized actions are RECOMMENDED when the standard set doesn't cover it:

- `px auth login`, `px auth status`
- `px self update`
- `px docs fetch`
- `px api graphql <query>`

### Backward compatibility during migration

The CLI is evolving from a flat structure (`px projects`, `px traces`) toward full noun-verb. During the transition, both forms MAY coexist. When migrating an existing command:

1. The new noun-verb form MUST be created as the primary command
2. The old form SHOULD be kept as a hidden alias (Commander's `.alias()` or a hidden command) so existing scripts don't break
3. Only the noun-verb form SHALL be documented going forward

## Dual-Audience Design

The CLI MUST be equally usable by a person at a terminal and by a coding agent. Every command that outputs data MUST support `--format`:

- **`pretty`** (default) — Human-readable tables and formatting
- **`json`** — Indented JSON for human inspection of structured data
- **`raw`** — Compact single-line JSON for piping into `jq` or agent consumption

Commands MAY support additional formats (e.g., `--format text` for prompts). The default MUST always be `pretty`.

Progress indicators MUST write to stderr. Agents SHOULD pass `--no-progress` to suppress them.

```bash
# Agent-friendly invocation
px trace list --format raw --no-progress | jq '...'
```

### Semantic exit codes

Defined in `src/exitCodes.ts`. Commands MUST use the named constants and MUST NOT use bare numeric literals.

| Code | Constant           | Meaning                                             |
| ---- | ------------------ | --------------------------------------------------- |
| 0    | `SUCCESS`          | Command completed successfully                      |
| 1    | `FAILURE`          | Unspecified or unexpected error                     |
| 2    | `CANCELLED`        | User cancelled (e.g., declined a confirmation)      |
| 3    | `INVALID_ARGUMENT` | Bad CLI flags, missing required args, invalid input |
| 4    | `AUTH_REQUIRED`    | Not authenticated or insufficient permissions       |
| 5    | `NETWORK_ERROR`    | Failed to connect to server or network request      |

### Interactive default with non-interactive mode

Commands MAY prompt interactively when a required value is missing or a confirmation is needed — this is the human-friendly default. The `--no-input` flag MUST suppress all prompts: both missing-value prompts and destructive-action confirmations. Non-interactive mode is also activated automatically when no TTY is attached (piped stdin).

In non-interactive mode, if a required value is missing, the command MUST exit immediately with `ExitCode.INVALID_ARGUMENT` and print the correct invocation. If a confirmation would have been shown, the command MUST proceed as if confirmed:

```bash
# Human: missing --name triggers interactive prompt
px project create

# Agent: all inputs as flags, no prompts
px project create --name my-project --format raw --no-input

# Human: gets "Are you sure?" prompt
px dataset delete my-dataset

# Agent: skips confirmation
px dataset delete my-dataset --no-input --format raw
```

```
Error: Missing required flag --name.
  px project create --name <project-name>
```

### Idempotent commands

Commands SHOULD be idempotent where possible. Running the same command twice MUST NOT produce duplicate resources or unexpected errors:

- `create` commands SHOULD support `--if-not-exists` to return the existing resource instead of failing
- `delete` commands on a missing resource SHOULD exit with `ExitCode.SUCCESS` (not an error)

### Return structured data on success

Mutating commands (`create`, `update`, `delete`) MUST return the affected resource in the selected `--format` on stdout. Commands MUST NOT print bare success messages like "Project created." — output the resource so agents can extract IDs, URLs, and other fields:

```bash
$ px project create --name foo --format raw
{"id":"proj_abc","name":"foo","createdAt":"2025-03-15T10:00:00Z"}
```

### Fail fast with actionable errors

When a command fails due to invalid input, the error message MUST include the correct invocatio