@arizeai/phoenix-cli 0.12.0 → 1.0.0

package/README.md

@@ -67,16 +67,16 @@ px self update --check  # show current/latest without installing
 Automatic updates are supported for global `npm`, `pnpm`, `bun`, and standard
 `deno install -g` wrapper installs.
 
-### `px traces [directory]`
+### `px trace list [directory]`
 
 Fetch recent traces from the configured project. All output is JSON.
 
 ```bash
-px traces --limit 10                          # stdout (pretty)
-px traces --format raw --no-progress | jq    # pipe-friendly compact JSON
-px traces ./my-traces --limit 50             # save as JSON files to directory
-px traces --last-n-minutes 60 --limit 20     # filter by time window
-px traces --since 2026-01-13T10:00:00Z       # since ISO timestamp
+px trace list --limit 10                          # stdout (pretty)
+px trace list --format raw --no-progress | jq    # pipe-friendly compact JSON
+px trace list ./my-traces --limit 50             # save as JSON files to directory
+px trace list --last-n-minutes 60 --limit 20     # filter by time window
+px trace list --since 2026-01-13T10:00:00Z       # since ISO timestamp
 ```
 
 | Option                      | Description                            | Default  |
@@ -91,42 +91,42 @@ px traces --since 2026-01-13T10:00:00Z       # since ISO timestamp
 
 ```bash
 # Find ERROR traces
-px traces --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
+px trace list --limit 50 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
 
 # Sort by duration, take top 5 slowest
-px traces --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
+px trace list --limit 20 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:5]'
 
 # Extract LLM model names used
-px traces --limit 50 --format raw --no-progress | \
+px trace list --limit 50 --format raw --no-progress | \
   jq -r '.[].spans[] | select(.span_kind == "LLM") | .attributes["llm.model_name"]' | sort -u
 ```
 
 ---
 
-### `px trace <trace-id>`
+### `px trace get <trace-id>`
 
 Fetch a single trace by ID.
 
 ```bash
-px trace abc123def456
-px trace abc123def456 --format raw | jq '.spans[] | select(.status_code != "OK")'
-px trace abc123def456 --file trace.json
+px trace get abc123def456
+px trace get abc123def456 --format raw | jq '.spans[] | select(.status_code != "OK")'
+px trace get abc123def456 --file trace.json
 ```
 
 ---
 
-### `px spans [file]`
+### `px span list [file]`
 
 Fetch spans for the configured project with filtering options. Output is JSON.
 
 ```bash
-px spans --limit 50                                    # stdout (pretty)
-px spans --span-kind LLM --limit 20                    # only LLM spans
-px spans --status-code ERROR --format raw --no-progress # pipe-friendly error spans
-px spans --name chat_completion --trace-id abc123       # filter by name and trace
-px spans --parent-id null                               # root spans only
-px spans spans.json --limit 100 --include-annotations   # save to file with annotations
-px spans --last-n-minutes 30 --span-kind TOOL RETRIEVER # multiple span kinds
+px span list --limit 50                                    # stdout (pretty)
+px span list --span-kind LLM --limit 20                    # only LLM spans
+px span list --status-code ERROR --format raw --no-progress # pipe-friendly error spans
+px span list --name chat_completion --trace-id abc123       # filter by name and trace
+px span list --parent-id null                               # root spans only
+px span list spans.json --limit 100 --include-annotations   # save to file with annotations
+px span list --last-n-minutes 30 --span-kind TOOL RETRIEVER # multiple span kinds
 ```
 
 | Option                      | Description                                                                                                                      | Default  |
@@ -146,85 +146,85 @@ px spans --last-n-minutes 30 --span-kind TOOL RETRIEVER # multiple span kinds
 
 ```bash
 # Find all ERROR spans
-px spans --status-code ERROR --format raw --no-progress | jq '.[] | {name, status_code}'
+px span list --status-code ERROR --format raw --no-progress | jq '.[] | {name, status_code}'
 
 # Get LLM spans with token counts
-px spans --span-kind LLM --format raw --no-progress | \
+px span list --span-kind LLM --format raw --no-progress | \
   jq '.[] | {name, model: .attributes["llm.model_name"], tokens: (.attributes["llm.token_count.prompt"] + .attributes["llm.token_count.completion"])}'
 
 # Root spans only, sorted by name
-px spans --parent-id null --format raw --no-progress | jq 'sort_by(.name)'
+px span list --parent-id null --format raw --no-progress | jq 'sort_by(.name)'
 ```
 
 ---
 
-### `px datasets`
+### `px dataset list`
 
 List all datasets.
 
 ```bash
-px datasets --format raw --no-progress | jq '.[].name'
+px dataset list --format raw --no-progress | jq '.[].name'
 ```
 
 ---
 
-### `px dataset <dataset-identifier>`
+### `px dataset get <dataset-identifier>`
 
 Fetch examples from a dataset.
 
 ```bash
-px dataset my-dataset --format raw | jq '.examples[].input'
-px dataset my-dataset --split train --split test
-px dataset my-dataset --version <version-id>
-px dataset my-dataset --file dataset.json
+px dataset get my-dataset --format raw | jq '.examples[].input'
+px dataset get my-dataset --split train --split test
+px dataset get my-dataset --version <version-id>
+px dataset get my-dataset --file dataset.json
 ```
 
 ---
 
-### `px experiments --dataset <name-or-id>`
+### `px experiment list --dataset <name-or-id>`
 
 List experiments for a dataset.
 
 ```bash
-px experiments --dataset my-dataset --format raw --no-progress | \
+px experiment list --dataset my-dataset --format raw --no-progress | \
   jq '.[] | {id, successful_run_count, failed_run_count}'
 ```
 
 ---
 
-### `px experiment <experiment-id>`
+### `px experiment get <experiment-id>`
 
 Fetch a single experiment with all run data (inputs, outputs, evaluations, trace IDs).
 
 ```bash
 # Find failed runs
-px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
+px experiment get RXhwZXJpbWVudDox --format raw --no-progress | \
   jq '.[] | select(.error != null) | {input, error}'
 
 # Average latency
-px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
+px experiment get RXhwZXJpbWVudDox --format raw --no-progress | \
   jq '[.[].latency_ms] | add / length'
 ```
 
 ---
 
-### `px prompts`
+### `px prompt list`
 
 List all prompts.
 
 ```bash
-px prompts --format raw --no-progress | jq '.[].name'
+px prompt list --format raw --no-progress | jq '.[].name'
 ```
 
 ---
 
-### `px prompt <prompt-identifier>`
+### `px prompt get <prompt-identifier>`
 
 Fetch a prompt. The `text` format is ideal for piping to AI assistants.
 
 ```bash
-px prompt my-evaluator --format text --no-progress | claude -p "Review this prompt"
-px prompt my-evaluator --tag production --format json | jq '.template'
+px prompt get my-evaluator --format text --no-progress | claude -p "Review this prompt"
+px prompt get my-evaluator --tag production --format json | jq '.template'
 ```
 
 | Option              | Description                        | Default  |
@@ -235,14 +235,14 @@ px prompt my-evaluator --tag production --format json | jq '.template'
 
 ---
 
-### `px projects`
+### `px project list`
 
 List all available Phoenix projects.
 
 ```bash
-px projects                                           # pretty output
-px projects --format raw --no-progress | jq '.[].name'
-px projects --limit 5
+px project list                                           # pretty output
+px project list --format raw --no-progress | jq '.[].name'
+px project list --limit 5
 ```
 
 | Option              | Description                         | Default  |
@@ -253,14 +253,14 @@ px projects --limit 5
 
 ---
 
-### `px sessions`
+### `px session list`
 
 List sessions for a project.
 
 ```bash
-px sessions                                            # latest 10 sessions
-px sessions --limit 20 --order asc                     # oldest first
-px sessions --format raw --no-progress | jq '.[].session_id'
+px session list                                            # latest 10 sessions
+px session list --limit 20 --order asc                     # oldest first
+px session list --format raw --no-progress | jq '.[].session_id'
 ```
 
 | Option                 | Description                 | Default  |
@@ -272,14 +272,14 @@ px sessions --format raw --no-progress | jq '.[].session_id'
 
 ---
 
-### `px session <session-id>`
+### `px session get <session-id>`
 
 View a session's conversation flow.
 
 ```bash
-px session my-session-id
-px session my-session-id --file session.json
-px session my-session-id --include-annotations --format raw | jq '.traces'
+px session get my-session-id
+px session get my-session-id --file session.json
+px session get my-session-id --include-annotations --format raw | jq '.traces'
 ```
 
 | Option                  | Description                            | Default  |
@@ -291,6 +291,21 @@ px session my-session-id --include-annotations --format raw | jq '.traces'
 
 ---
 
+### `px annotation-config list`
+
+List annotation configurations defined in your Phoenix instance.
+
+```bash
+px annotation-config list --format raw --no-progress | jq '.[].name'
+```
+
+| Option              | Description                | Default  |
+| ------------------- | -------------------------- | -------- |
+| `--format <format>` | `pretty`, `json`, or `raw` | `pretty` |
+| `--no-progress`     | Suppress progress output   | —        |
+
+---
+
 ### `px auth status`
 
 Show current Phoenix authentication status, including the configured endpoint, whether you are authenticated or anonymous, and an obscured API key.
@@ -431,8 +446,8 @@ px docs fetch --refresh                      # clear output dir and re-download
 All commands output JSON. Use `--format raw` for compact JSON and `--no-progress` to suppress stderr when piping:
 
 ```bash
-px traces --format raw --no-progress | jq ...
-px datasets --format raw --no-progress | jq ...
+px trace list --format raw --no-progress | jq ...
+px dataset list --format raw --no-progress | jq ...
 ```
 
 Trace JSON structure:

package/build/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,wBAAgB,aAAa,IAAI,OAAO,CA2BvC;AAGD,wBAAsB,IAAI,CAAC,EACzB,IAAmB,GACpB,GAAE;IACD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,wBAAgB,aAAa,IAAI,OAAO,CAsBvC;AAGD,wBAAsB,IAAI,CAAC,EACzB,IAAmB,GACpB,GAAE;IACD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrB"}

package/build/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { printBanner } from "./banner.js";
-import { createAnnotationConfigCommand, createApiCommand, createAuthCommand, createDatasetCommand, createDatasetsCommand, createDocsCommand, createExperimentCommand, createExperimentsCommand, createProjectsCommand, createPromptCommand, createPromptsCommand, createSessionCommand, createSessionsCommand, createSelfCommand, createSpansCommand, createTraceCommand, createTracesCommand, } from "./commands/index.js";
+import { createAnnotationConfigCommand, createApiCommand, createAuthCommand, createDatasetCommand, createDocsCommand, createExperimentCommand, createProjectCommand, createPromptCommand, createSessionCommand, createSelfCommand, createSpanCommand, createTraceCommand, } from "./commands/index.js";
 import { CLI_VERSION } from "./version.js";
 export function createProgram() {
     const program = new Command();
@@ -11,17 +11,12 @@ export function createProgram() {
     // Register commands
     program.addCommand(createAnnotationConfigCommand());
     program.addCommand(createAuthCommand());
-    program.addCommand(createProjectsCommand());
-    program.addCommand(createTracesCommand());
+    program.addCommand(createProjectCommand());
     program.addCommand(createTraceCommand());
-    program.addCommand(createSpansCommand());
-    program.addCommand(createDatasetsCommand());
+    program.addCommand(createSpanCommand());
     program.addCommand(createDatasetCommand());
-    program.addCommand(createSessionsCommand());
     program.addCommand(createSessionCommand());
-    program.addCommand(createExperimentsCommand());
     program.addCommand(createExperimentCommand());
-    program.addCommand(createPromptsCommand());
     program.addCommand(createPromptCommand());
     program.addCommand(createApiCommand());
     program.addCommand(createDocsCommand());

package/build/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,6BAA6B,EAC7B,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAClC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAE7B,oBAAoB;IACpB,OAAO,CAAC,UAAU,CAAC,6BAA6B,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,OAAO,CAAC,UAAU,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,UAAU,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,UAAU,CAAC,wBAAwB,EAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,UAAU,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC9C,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAExC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yBAAyB;AACzB,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,EACzB,IAAI,GAAG,OAAO,CAAC,IAAI,MAGjB,EAAE;IACJ,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAEhC,8CAA8C;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,WAAW,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EACL,6BAA6B,EAC7B,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAClC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAE7B,oBAAoB;IACpB,OAAO,CAAC,UAAU,CAAC,6BAA6B,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,UAAU,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,UAAU,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC9C,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAExC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yBAAyB;AACzB,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,EACzB,IAAI,GAAG,OAAO,CAAC,IAAI,MAGjB,EAAE;IACJ,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAEhC,8CAA8C;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,WAAW,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}

package/build/commands/auth.d.ts

@@ -1,11 +1,27 @@
+import type { componentsV1 } from "@arizeai/phoenix-client";
 import { Command } from "commander";
+type ViewerUser = componentsV1["schemas"]["GetViewerResponseBody"]["data"];
 /**
  * Obscure an API key for display using asterisks.
  * Shows a fixed number of asterisks regardless of key length for security.
  */
 export declare function obscureApiKey(apiKey: string): string;
+interface FetchViewerSuccess {
+    status: "success";
+    user: ViewerUser;
+}
+interface FetchViewerError {
+    status: "network_error" | "auth_error" | "not_found" | "unknown_error";
+    message: string;
+}
+export type FetchViewerResult = FetchViewerSuccess | FetchViewerError;
+/**
+ * Format auth status output in gh-style format.
+ */
+export declare function formatAuthStatus(endpoint: string, result: FetchViewerResult, apiKey?: string): string;
 /**
  * Create the auth command with subcommands
  */
 export declare function createAuthCommand(): Command;
+export {};
 //# sourceMappingURL=auth.d.ts.map

package/build/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpD;AA8CD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAS3C"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,KAAK,UAAU,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAO3E;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED,UAAU,kBAAkB;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,eAAe,CAAC;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;AAuCtE;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAiCR;AA6DD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAS3C"}

package/build/commands/auth.js

@@ -1,8 +1,8 @@
 import { Command } from "commander";
+import { createPhoenixClient } from "../client.js";
 import { resolveConfig } from "../config.js";
 import { ExitCode } from "../exitCodes.js";
 import { writeError, writeOutput } from "../io.js";
-import { formatTable } from "./formatTable.js";
 /**
  * Obscure an API key for display using asterisks.
  * Shows a fixed number of asterisks regardless of key length for security.
@@ -13,30 +13,115 @@ export function obscureApiKey(apiKey) {
     }
     return "************************************";
 }
+/**
+ * Extract an HTTP status code from the phoenix-client middleware error message.
+ * The middleware throws errors like: "https://example.org/api/v1/user: 401 Unauthorized"
+ */
+function parseStatusCode(error) {
+    const match = error.message.match(/:\s*(\d{3})\s/);
+    return match ? parseInt(match[1], 10) : null;
+}
+/**
+ * Fetch the authenticated viewer from the Phoenix server.
+ * Gracefully handles network errors, auth failures, and missing endpoints.
+ */
+async function fetchViewer(config) {
+    try {
+        const client = createPhoenixClient({ config });
+        const response = await client.GET("/v1/user");
+        return { status: "success", user: response.data.data };
+    }
+    catch (error) {
+        // TypeError is thrown by the Fetch API for network-level failures
+        if (error instanceof TypeError) {
+            return { status: "network_error", message: error.message };
+        }
+        if (error instanceof Error) {
+            const statusCode = parseStatusCode(error);
+            if (statusCode === 401 || statusCode === 403) {
+                return { status: "auth_error", message: error.message };
+            }
+            if (statusCode === 404) {
+                return { status: "not_found", message: error.message };
+            }
+            return { status: "unknown_error", message: error.message };
+        }
+        return { status: "unknown_error", message: String(error) };
+    }
+}
+/**
+ * Format auth status output in gh-style format.
+ */
+export function formatAuthStatus(endpoint, result, apiKey) {
+    const lines = [endpoint];
+    if (result.status === "success") {
+        const user = result.user;
+        if (user.auth_method === "ANONYMOUS") {
+            lines.push("  \u2713 Authentication not required (anonymous)");
+        }
+        else {
+            lines.push(`  \u2713 Logged in as ${user.username} (api key)`);
+            lines.push(`  - Role: ${user.role}`);
+        }
+    }
+    else if (result.status === "auth_error") {
+        lines.push("  \u2717 Authentication failed (invalid or expired token)");
+    }
+    else if (result.status === "not_found") {
+        lines.push("  - Could not verify token (server does not support user endpoint)");
+    }
+    else {
+        // network_error or unknown_error
+        if (apiKey) {
+            lines.push("  \u2717 Token configured but could not verify (server unreachable)");
+        }
+        else {
+            lines.push("  \u2717 Could not connect to server");
+        }
+    }
+    if (apiKey) {
+        lines.push(`  - Token: ${obscureApiKey(apiKey)}`);
+    }
+    return lines.join("\n");
+}
+function exitCodeForResult(result) {
+    switch (result.status) {
+        case "success":
+        // 404 means the server is an older version without /v1/user — the token
+        // may still be valid, we just can't verify it. Not a failure.
+        case "not_found":
+            return ExitCode.SUCCESS;
+        case "auth_error":
+            return ExitCode.AUTH_REQUIRED;
+        case "network_error":
+            return ExitCode.NETWORK_ERROR;
+        case "unknown_error":
+            return ExitCode.FAILURE;
+    }
+}
 /**
  * Auth status command handler
  */
 async function authStatusHandler(options) {
-    // Resolve configuration
     const config = resolveConfig({
         cliOptions: {
             endpoint: options.endpoint,
             apiKey: options.apiKey,
         },
     });
-    // Check if endpoint is configured
     if (!config.endpoint) {
         writeError({
             message: "Configuration Error:\n  - Phoenix endpoint not configured",
         });
         process.exit(ExitCode.INVALID_ARGUMENT);
     }
-    const row = {
-        endpoint: config.endpoint,
-        status: config.apiKey ? "authenticated" : "anonymous",
-        "api key": config.apiKey ? obscureApiKey(config.apiKey) : "not set",
-    };
-    writeOutput({ message: formatTable([row]) });
+    const result = await fetchViewer(config);
+    const output = formatAuthStatus(config.endpoint, result, config.apiKey);
+    writeOutput({ message: output });
+    const code = exitCodeForResult(result);
+    if (code !== ExitCode.SUCCESS) {
+        process.exit(code);
+    }
 }
 /**
  * Create the auth status subcommand

package/build/commands/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAO5C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,sCAAsC,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,iBAAiB,CAAC,OAA0B;IACzD,wBAAwB;IACxB,MAAM,MAAM,GAAG,aAAa,CAAC;QAC3B,UAAU,EAAE;YACV,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB;KACF,CAAC,CAAC;IAEH,kCAAkC;IAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,UAAU,CAAC;YACT,OAAO,EAAE,2DAA2D;SACrE,CAAC,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,GAAG,GAA2B;QAClC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW;QACrD,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;KACpE,CAAC;IAEF,WAAW,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB;IAC9B,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEtC,OAAO;SACJ,WAAW,CAAC,4CAA4C,CAAC;SACzD,MAAM,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;SAClD,MAAM,CAAC,iBAAiB,EAAE,oCAAoC,CAAC;SAC/D,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAE7B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC,OAAO,CAAC,WAAW,CAAC,+BAA+B,CAAC,CAAC;IAErD,kBAAkB;IAClB,OAAO,CAAC,UAAU,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAE9C,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"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"}

package/build/commands/dataset.d.ts

@@ -1,6 +1,11 @@
 import { Command } from "commander";
 /**
- * Create the dataset command
+ * Create the `dataset get` command
+ */
+export declare function createDatasetGetCommand(): Command;
+export declare function createDatasetListCommand(): Command;
+/**
+ * Create the `dataset` command with subcommands
  */
 export declare function createDatasetCommand(): Command;
 //# sourceMappingURL=dataset.d.ts.map

package/build/commands/dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../../src/commands/dataset.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsLpC;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAyB9C"}
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../../src/commands/dataset.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsRpC;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAqBjD;AAED,wBAAgB,wBAAwB,IAAI,OAAO,CAalD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAM9C"}

package/build/commands/dataset.js

@@ -5,6 +5,34 @@ import { getConfigErrorMessage, resolveConfig } from "../config.js";
 import { ExitCode, getExitCodeForError } from "../exitCodes.js";
 import { writeError, writeOutput, writeProgress } from "../io.js";
 import { formatDatasetExamplesOutput, } from "./formatDataset.js";
+import { formatDatasetsOutput } from "./formatDatasets.js";
+/**
+ * Fetch all datasets from Phoenix
+ */
+async function fetchDatasets(client, options = {}) {
+    const allDatasets = [];
+    let cursor;
+    const pageLimit = options.limit || 100;
+    do {
+        const response = await client.GET("/v1/datasets", {
+            params: {
+                query: {
+                    cursor,
+                    limit: pageLimit,
+                },
+            },
+        });
+        if (response.error || !response.data) {
+            throw new Error(`Failed to fetch datasets: ${response.error}`);
+        }
+        allDatasets.push(...response.data.data);
+        cursor = response.data.next_cursor || undefined;
+        if (options.limit && allDatasets.length >= options.limit) {
+            break;
+        }
+    } while (cursor);
+    return allDatasets;
+}
 /**
  * Fetch dataset examples from Phoenix
  */
@@ -127,6 +155,49 @@ async function datasetHandler(datasetIdentifier, options) {
         process.exit(getExitCodeForError(error));
     }
 }
+/**
+ * Handler for `dataset list`
+ */
+async function datasetListHandler(options) {
+    try {
+        const config = resolveConfig({
+            cliOptions: {
+                endpoint: options.endpoint,
+                apiKey: options.apiKey,
+            },
+        });
+        if (!config.endpoint) {
+            const errors = [
+                "Phoenix endpoint not configured. Set PHOENIX_HOST environment variable or use --endpoint flag.",
+            ];
+            writeError({ message: getConfigErrorMessage({ errors }) });
+            process.exit(ExitCode.INVALID_ARGUMENT);
+        }
+        const client = createPhoenixClient({ config });
+        writeProgress({
+            message: "Fetching datasets...",
+            noProgress: !options.progress,
+        });
+        const datasets = await fetchDatasets(client, {
+            limit: options.limit,
+        });
+        writeProgress({
+            message: `Found ${datasets.length} dataset(s)`,
+            noProgress: !options.progress,
+        });
+        const output = formatDatasetsOutput({
+            datasets,
+            format: options.format,
+        });
+        writeOutput({ message: output });
+    }
+    catch (error) {
+        writeError({
+            message: `Error fetching datasets: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        process.exit(getExitCodeForError(error));
+    }
+}
 /**
  * Collect multiple --split options into an array
  */
@@ -134,11 +205,10 @@ function collectSplits(value, previous) {
     return previous.concat([value]);
 }
 /**
- * Create the dataset command
+ * Create the `dataset get` command
  */
-export function createDatasetCommand() {
-    const command = new Command("dataset");
-    command
+export function createDatasetGetCommand() {
+    return new Command("get")
         .description("Fetch examples from a dataset")
         .argument("<dataset-identifier>", "Dataset name or ID")
         .option("--endpoint <url>", "Phoenix API endpoint")
@@ -149,6 +219,25 @@ export function createDatasetCommand() {
         .option("--split <name>", "Filter by split name (can be used multiple times)", collectSplits, [])
         .option("--version <id>", "Fetch from a specific dataset version")
         .action(datasetHandler);
+}
+export function createDatasetListCommand() {
+    return new Command("list")
+        .description("List all available Phoenix datasets")
+        .option("--endpoint <url>", "Phoenix API endpoint")
+        .option("--api-key <key>", "Phoenix API key for authentication")
+        .option("--format <format>", "Output format: pretty, json, or raw", "pretty")
+        .option("--no-progress", "Disable progress indicators")
+        .option("--limit <number>", "Maximum number of datasets to fetch", parseInt)
+        .action(datasetListHandler);
+}
+/**
+ * Create the `dataset` command with subcommands
+ */
+export function createDatasetCommand() {
+    const command = new Command("dataset");
+    command.description("Manage Phoenix datasets");
+    command.addCommand(createDatasetListCommand());
+    command.addCommand(createDatasetGetCommand());
     return command;
 }
 //# sourceMappingURL=dataset.js.map