@arizeai/phoenix-cli 0.0.4 → 0.2.0

package/README.md

@@ -1,44 +1,307 @@
-# @arizeai/phoenix-cli
+<h1 align="center" style="border-bottom: none">
+    <div>
+        <a href="https://phoenix.arize.com/?utm_medium=github&utm_content=header_img&utm_campaign=phoenix-cli">
+            <picture>
+                <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg">
+                <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix-white.svg">
+                <img alt="Arize Phoenix logo" src="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg" width="100" />
+            </picture>
+        </a>
+        <br>
+        @arizeai/phoenix-cli
+    </div>
+</h1>
 
-A command-line interface for [Arize Phoenix](https://github.com/Arize-ai/phoenix).
+<p align="center">
+    <a href="https://www.npmjs.com/package/@arizeai/phoenix-cli">
+        <img src="https://img.shields.io/npm/v/%40arizeai%2Fphoenix-cli" alt="NPM Version">
+    </a>
+    <a href="https://arize.com/docs/phoenix/">
+        <img src="https://img.shields.io/badge/docs-blue?logo=typescript&logoColor=white" alt="Documentation">
+    </a>
+    <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8e8e8b34-7900-43fa-a38f-1f070bd48c64&page=js/packages/phoenix-cli/README.md" />
+</p>
 
-> **Note:** This package is currently under development and not yet ready for use.
+A command-line interface for [Arize Phoenix](https://github.com/Arize-ai/phoenix). Fetch traces, list datasets, and export experiment results directly from your terminal—or pipe them into AI coding agents like Claude Code, Cursor, Codex, and Gemini CLI.
 
 ## Installation
 
 ```bash
-# Install globally
 npm install -g @arizeai/phoenix-cli
+```
+
+Or run directly with npx:
 
-# Or use with npx
+```bash
 npx @arizeai/phoenix-cli
 ```
 
-## Usage
+## Quick Start
 
 ```bash
-# View help
-phoenix-cli --help
+# Configure your Phoenix instance
+export PHOENIX_HOST=http://localhost:6006
+export PHOENIX_PROJECT=my-project
+export PHOENIX_API_KEY=your-api-key  # if authentication is enabled
 
-# TODO: Add usage examples here
+# Fetch the most recent trace
+px traces --limit 1
+
+# Fetch a specific trace by ID
+px trace abc123def456
+
+# Export traces to a directory
+px traces ./my-traces --limit 50
 ```
 
+## Environment Variables
+
+| Variable                 | Description                                          |
+| ------------------------ | ---------------------------------------------------- |
+| `PHOENIX_HOST`           | Phoenix API endpoint (e.g., `http://localhost:6006`) |
+| `PHOENIX_PROJECT`        | Project name or ID                                   |
+| `PHOENIX_API_KEY`        | API key for authentication (if required)             |
+| `PHOENIX_CLIENT_HEADERS` | Custom headers as JSON string                        |
+
+CLI flags take priority over environment variables.
+
 ## Commands
 
-> **Coming Soon:** Commands will be added to interact with Phoenix prompts, datasets, experiments, and more.
+### `px projects`
+
+List all available projects.
 
-## Development
+```bash
+px projects
+px projects --format raw  # JSON output for piping
+```
 
-This package is part of the Phoenix monorepo and uses the existing `@arizeai/phoenix-client` library.
+### `px traces [directory]`
 
-### Building
+Fetch recent traces from the configured project.
 
 ```bash
-pnpm build
+px traces --limit 10                          # Output to stdout
+px traces ./my-traces --limit 10              # Save to directory
+px traces --last-n-minutes 60 --limit 20      # Filter by time
+px traces --since 2026-01-13T10:00:00Z        # Since timestamp
+px traces --format raw --no-progress | jq     # Pipe to jq
 ```
 
-### Testing
+| Option                      | Description                               | Default  |
+| --------------------------- | ----------------------------------------- | -------- |
+| `[directory]`               | Save traces as JSON files to directory    | stdout   |
+| `-n, --limit <number>`      | Number of traces to fetch (newest first)  | 10       |
+| `--last-n-minutes <number>` | Only fetch traces from the last N minutes | —        |
+| `--since <timestamp>`       | Fetch traces since ISO timestamp          | —        |
+| `--format <format>`         | `pretty`, `json`, or `raw`                | `pretty` |
+| `--no-progress`             | Disable progress output                   | —        |
+
+### `px trace <trace-id>`
+
+Fetch a specific trace by ID.
+
+```bash
+px trace abc123def456
+px trace abc123def456 --file trace.json      # Save to file
+px trace abc123def456 --format raw | jq      # Pipe to jq
+```
+
+| Option              | Description                    | Default  |
+| ------------------- | ------------------------------ | -------- |
+| `--file <path>`     | Save to file instead of stdout | stdout   |
+| `--format <format>` | `pretty`, `json`, or `raw`     | `pretty` |
+
+### `px datasets`
+
+List all available datasets.
 
 ```bash
-pnpm test
+px datasets
+px datasets --format json                    # JSON output
+px datasets --format raw --no-progress | jq  # Pipe to jq
 ```
+
+| Option              | Description                | Default  |
+| ------------------- | -------------------------- | -------- |
+| `--format <format>` | `pretty`, `json`, or `raw` | `pretty` |
+| `--limit <number>`  | Maximum number of datasets | —        |
+
+### `px dataset <dataset-identifier>`
+
+Fetch examples from a dataset.
+
+```bash
+px dataset query_response                        # Fetch all examples
+px dataset query_response --split train          # Filter by split
+px dataset query_response --split train --split test  # Multiple splits
+px dataset query_response --version <version-id> # Specific version
+px dataset query_response --file dataset.json    # Save to file
+px dataset query_response --format raw | jq '.examples[].input'
+```
+
+| Option           | Description                              | Default  |
+| ---------------- | ---------------------------------------- | -------- |
+| `--split <name>` | Filter by split (can be used repeatedly) | —        |
+| `--version <id>` | Fetch from specific dataset version      | latest   |
+| `--file <path>`  | Save to file instead of stdout           | stdout   |
+| `--format <fmt>` | `pretty`, `json`, or `raw`               | `pretty` |
+
+### `px experiments --dataset <name-or-id>`
+
+List experiments for a dataset, optionally exporting full data to files.
+
+```bash
+px experiments --dataset my-dataset                 # List experiments
+px experiments --dataset my-dataset --format json   # JSON output
+px experiments --dataset my-dataset ./experiments   # Export to directory
+```
+
+| Option                   | Description                               | Default  |
+| ------------------------ | ----------------------------------------- | -------- |
+| `--dataset <name-or-id>` | Dataset name or ID (required)             | —        |
+| `[directory]`            | Export experiment JSON files to directory | stdout   |
+| `--format <format>`      | `pretty`, `json`, or `raw`                | `pretty` |
+| `--limit <number>`       | Maximum number of experiments             | —        |
+
+### `px experiment <experiment-id>`
+
+Fetch a single experiment with all run data.
+
+```bash
+px experiment RXhwZXJpbWVudDox
+px experiment RXhwZXJpbWVudDox --file exp.json   # Save to file
+px experiment RXhwZXJpbWVudDox --format json     # JSON output
+```
+
+| Option              | Description                    | Default  |
+| ------------------- | ------------------------------ | -------- |
+| `--file <path>`     | Save to file instead of stdout | stdout   |
+| `--format <format>` | `pretty`, `json`, or `raw`     | `pretty` |
+
+## Output Formats
+
+**`pretty`** (default) — Human-readable tree view:
+
+```
+┌─ Trace: abc123def456
+│
+│  Input: What is the weather in San Francisco?
+│  Output: The weather is currently sunny...
+│
+│  Spans:
+│  └─ ✓ agent_run (CHAIN) - 1250ms
+│     ├─ ✓ llm_call (LLM) - 800ms
+│     └─ ✓ tool_execution (TOOL) - 400ms
+└─
+```
+
+**`json`** — Formatted JSON with indentation.
+
+**`raw`** — Compact JSON for piping to `jq` or other tools.
+
+## JSON Structure
+
+```json
+{
+  "traceId": "abc123def456",
+  "spans": [
+    {
+      "name": "chat_completion",
+      "context": {
+        "trace_id": "abc123def456",
+        "span_id": "span-1"
+      },
+      "span_kind": "LLM",
+      "parent_id": null,
+      "start_time": "2026-01-17T10:00:00.000Z",
+      "end_time": "2026-01-17T10:00:01.250Z",
+      "status_code": "OK",
+      "attributes": {
+        "llm.model_name": "gpt-4",
+        "llm.token_count.prompt": 512,
+        "llm.token_count.completion": 256,
+        "input.value": "What is the weather?",
+        "output.value": "The weather is sunny..."
+      }
+    }
+  ],
+  "rootSpan": { ... },
+  "startTime": "2026-01-17T10:00:00.000Z",
+  "endTime": "2026-01-17T10:00:01.250Z",
+  "duration": 1250,
+  "status": "OK"
+}
+```
+
+Spans include [OpenInference](https://github.com/Arize-ai/openinference) semantic attributes like `llm.model_name`, `llm.token_count.*`, `input.value`, `output.value`, `tool.name`, and `exception.*`.
+
+## Examples
+
+### Debug failed traces
+
+```bash
+px traces --limit 20 --format raw --no-progress | jq '.[] | select(.status == "ERROR")'
+```
+
+### Find slowest traces
+
+```bash
+px traces --limit 10 --format raw --no-progress | jq 'sort_by(-.duration) | .[0:3]'
+```
+
+### Extract LLM models used
+
+```bash
+px traces --limit 50 --format raw --no-progress | \
+  jq -r '.[].spans[] | select(.span_kind == "LLM") | .attributes["llm.model_name"]' | sort -u
+```
+
+### Count errors
+
+```bash
+px traces --limit 100 --format raw --no-progress | jq '[.[] | select(.status == "ERROR")] | length'
+```
+
+### List datasets and experiments
+
+```bash
+# List all datasets
+px datasets --format raw --no-progress | jq '.[].name'
+# Output: "query_response"
+
+# List experiments for a dataset
+px experiments --dataset query_response --format raw --no-progress | \
+  jq '.[] | {id, successful_run_count, failed_run_count}'
+# Output: {"id":"RXhwZXJpbWVudDox","successful_run_count":249,"failed_run_count":1}
+
+# Export all experiment data for a dataset to a directory
+px experiments --dataset query_response ./experiments/
+```
+
+### Analyze experiment results
+
+```bash
+# Get input queries and latency from an experiment
+px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
+  jq '.[] | {query: .input.query, latency_ms, trace_id}'
+
+# Find failed runs in an experiment
+px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
+  jq '.[] | select(.error != null) | {query: .input.query, error}'
+# Output: {"query":"looking for complex fodmap meal ideas","error":"peer closed connection..."}
+
+# Calculate average latency across runs
+px experiment RXhwZXJpbWVudDox --format raw --no-progress | \
+  jq '[.[].latency_ms] | add / length'
+```
+
+---
+
+## Community
+
+- 🌍 [Slack community](https://arize-ai.slack.com/join/shared_invite/zt-11t1vbu4x-xkBIHmOREQnYnYDH1GDfCg)
+- 📚 [Documentation](https://arize.com/docs/phoenix)
+- 🌟 [GitHub](https://github.com/Arize-ai/phoenix)
+- 🐞 [Report bugs](https://github.com/Arize-ai/phoenix/issues)
+- 𝕏 [@ArizePhoenix](https://twitter.com/ArizePhoenix)

package/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAeA,wBAAgB,IAAI,SAuBnB"}

package/build/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { createDatasetCommand, createDatasetsCommand, createExperimentCommand, createExperimentsCommand, createProjectsCommand, createTraceCommand, createTracesCommand, } from "./commands/index.js";
+import { Command } from "commander";
+// Phoenix CLI Main Logic
+export function main() {
+    const program = new Command();
+    program
+        .name("px")
+        .description("Phoenix CLI - AI observability from the command line")
+        .version("0.0.4");
+    // Register commands
+    program.addCommand(createProjectsCommand());
+    program.addCommand(createTracesCommand());
+    program.addCommand(createTraceCommand());
+    program.addCommand(createDatasetsCommand());
+    program.addCommand(createDatasetCommand());
+    program.addCommand(createExperimentsCommand());
+    program.addCommand(createExperimentCommand());
+    // Show help if no command provided
+    if (process.argv.length === 2) {
+        program.help();
+    }
+    program.parse();
+}
+//# sourceMappingURL=cli.js.map

package/build/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,yBAAyB;AACzB,MAAM,UAAU,IAAI;IAClB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,IAAI,CAAC;SACV,WAAW,CAAC,sDAAsD,CAAC;SACnE,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,oBAAoB;IACpB,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,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;IAE9C,mCAAmC;IACnC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,EAAE,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/build/client.d.ts

@@ -0,0 +1,49 @@
+import { type PhoenixClient } from "@arizeai/phoenix-client";
+import type { PhoenixConfig } from "./config.js";
+export interface CreatePhoenixClientOptions {
+    /**
+     * Resolved Phoenix CLI configuration.
+     */
+    config: PhoenixConfig;
+}
+/**
+ * Create a Phoenix client from configuration
+ */
+export declare function createPhoenixClient({ config, }: CreatePhoenixClientOptions): PhoenixClient;
+export interface ResolveProjectIdOptions {
+    /**
+     * Phoenix API client.
+     */
+    client: PhoenixClient;
+    /**
+     * Project identifier to resolve.
+     *
+     * Phoenix project IDs are hex-encoded strings. If `projectIdentifier` looks like a hex string,
+     * it's treated as an ID; otherwise it's treated as a name and resolved via the API.
+     */
+    projectIdentifier: string;
+}
+/**
+ * Resolve project identifier to project ID
+ * If the identifier looks like a Phoenix project ID (hex string), returns it as-is; otherwise fetches by name.
+ */
+export declare function resolveProjectId({ client, projectIdentifier, }: ResolveProjectIdOptions): Promise<string>;
+export interface ResolveDatasetIdOptions {
+    /**
+     * Phoenix API client.
+     */
+    client: PhoenixClient;
+    /**
+     * Dataset identifier to resolve.
+     *
+     * Phoenix dataset IDs are hex-encoded strings. If `datasetIdentifier` looks like a hex string,
+     * it's treated as an ID; otherwise it's treated as a name and resolved via the API.
+     */
+    datasetIdentifier: string;
+}
+/**
+ * Resolve dataset identifier to dataset ID
+ * If the identifier looks like a Phoenix dataset ID (hex string), returns it as-is; otherwise fetches by name.
+ */
+export declare function resolveDatasetId({ client, datasetIdentifier, }: ResolveDatasetIdOptions): Promise<string>;
+//# sourceMappingURL=client.d.ts.map

package/build/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,GACP,EAAE,0BAA0B,GAAG,aAAa,CAqB5C;AAED,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAWD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,MAAM,EACN,iBAAiB,GAClB,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2B3C;AAED,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAWD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,MAAM,EACN,iBAAiB,GAClB,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC3C"}

package/build/client.js

@@ -0,0 +1,96 @@
+import { createClient } from "@arizeai/phoenix-client";
+/**
+ * Create a Phoenix client from configuration
+ */
+export function createPhoenixClient({ config, }) {
+    const baseUrl = config.endpoint;
+    if (!baseUrl) {
+        throw new Error("Phoenix endpoint not configured");
+    }
+    const headers = {
+        ...(config.headers || {}),
+    };
+    if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    return createClient({
+        options: {
+            baseUrl,
+            headers,
+        },
+    });
+}
+function looksLikePhoenixProjectId(projectIdentifier) {
+    // Project IDs are hex-encoded strings (e.g., "a1b2c3d4e5f6...")
+    const trimmed = projectIdentifier.trim();
+    if (!trimmed)
+        return false;
+    // Check if the string is a valid hex string (only 0-9, a-f, A-F)
+    return /^[0-9a-fA-F]+$/.test(trimmed);
+}
+/**
+ * Resolve project identifier to project ID
+ * If the identifier looks like a Phoenix project ID (hex string), returns it as-is; otherwise fetches by name.
+ */
+export async function resolveProjectId({ client, projectIdentifier, }) {
+    if (looksLikePhoenixProjectId(projectIdentifier)) {
+        return projectIdentifier;
+    }
+    // Otherwise, fetch the project by name to get its ID
+    try {
+        const response = await client.GET("/v1/projects/{project_identifier}", {
+            params: {
+                path: {
+                    project_identifier: projectIdentifier,
+                },
+            },
+        });
+        if (response.error || !response.data) {
+            throw new Error(`Failed to resolve project "${projectIdentifier}": ${response.error}`);
+        }
+        return response.data.data.id;
+    }
+    catch (error) {
+        throw new Error(`Failed to resolve project "${projectIdentifier}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function looksLikePhoenixDatasetId(datasetIdentifier) {
+    // Dataset IDs are hex-encoded strings (e.g., "a1b2c3d4e5f6...")
+    const trimmed = datasetIdentifier.trim();
+    if (!trimmed)
+        return false;
+    // Check if the string is a valid hex string (only 0-9, a-f, A-F)
+    return /^[0-9a-fA-F]+$/.test(trimmed);
+}
+/**
+ * Resolve dataset identifier to dataset ID
+ * If the identifier looks like a Phoenix dataset ID (hex string), returns it as-is; otherwise fetches by name.
+ */
+export async function resolveDatasetId({ client, datasetIdentifier, }) {
+    if (looksLikePhoenixDatasetId(datasetIdentifier)) {
+        return datasetIdentifier;
+    }
+    // Otherwise, fetch the dataset by name to get its ID
+    try {
+        const response = await client.GET("/v1/datasets", {
+            params: {
+                query: {
+                    name: datasetIdentifier,
+                    limit: 1,
+                },
+            },
+        });
+        if (response.error || !response.data) {
+            throw new Error(`Failed to resolve dataset "${datasetIdentifier}": ${response.error}`);
+        }
+        const datasets = response.data.data;
+        if (datasets.length === 0) {
+            throw new Error(`Dataset not found: "${datasetIdentifier}"`);
+        }
+        return datasets[0].id;
+    }
+    catch (error) {
+        throw new Error(`Failed to resolve dataset "${datasetIdentifier}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=client.js.map

package/build/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,yBAAyB,CAAC;AAW3E;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,MAAM,GACqB;IAC3B,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC;IAEhC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;KAC1B,CAAC;IAEF,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;IAED,OAAO,YAAY,CAAC;QAClB,OAAO,EAAE;YACP,OAAO;YACP,OAAO;SACR;KACF,CAAC,CAAC;AACL,CAAC;AAgBD,SAAS,yBAAyB,CAAC,iBAAyB;IAC1D,gEAAgE;IAChE,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC;IACzC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,iEAAiE;IACjE,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EACrC,MAAM,EACN,iBAAiB,GACO;IACxB,IAAI,yBAAyB,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACjD,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,mCAAmC,EAAE;YACrE,MAAM,EAAE;gBACN,IAAI,EAAE;oBACJ,kBAAkB,EAAE,iBAAiB;iBACtC;aACF;SACF,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,8BAA8B,iBAAiB,MAAM,QAAQ,CAAC,KAAK,EAAE,CACtE,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,8BAA8B,iBAAiB,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9G,CAAC;IACJ,CAAC;AACH,CAAC;AAgBD,SAAS,yBAAyB,CAAC,iBAAyB;IAC1D,gEAAgE;IAChE,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC;IACzC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,iEAAiE;IACjE,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EACrC,MAAM,EACN,iBAAiB,GACO;IACxB,IAAI,yBAAyB,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACjD,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE;YAChD,MAAM,EAAE;gBACN,KAAK,EAAE;oBACL,IAAI,EAAE,iBAAiB;oBACvB,KAAK,EAAE,CAAC;iBACT;aACF;SACF,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,8BAA8B,iBAAiB,MAAM,QAAQ,CAAC,KAAK,EAAE,CACtE,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QACpC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,uBAAuB,iBAAiB,GAAG,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,8BAA8B,iBAAiB,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9G,CAAC;IACJ,CAAC;AACH,CAAC"}

package/build/commands/dataset.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.d.ts","sourceRoot":"","sources":["../../src/commands/dataset.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6KpC;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAyB9C"}

package/build/commands/dataset.js

@@ -0,0 +1,153 @@
+import { createPhoenixClient, resolveDatasetId } from "../client.js";
+import { getConfigErrorMessage, resolveConfig } from "../config.js";
+import { writeError, writeOutput, writeProgress } from "../io.js";
+import { formatDatasetExamplesOutput, } from "./formatDataset.js";
+import { Command } from "commander";
+import * as fs from "fs";
+/**
+ * Fetch dataset examples from Phoenix
+ */
+async function fetchDatasetExamples(client, datasetId, options = {}) {
+    const response = await client.GET("/v1/datasets/{id}/examples", {
+        params: {
+            path: {
+                id: datasetId,
+            },
+            query: {
+                version_id: options.versionId,
+                split: options.splits,
+            },
+        },
+    });
+    if (response.error || !response.data) {
+        throw new Error(`Failed to fetch dataset examples: ${response.error}`);
+    }
+    return response.data.data;
+}
+/**
+ * Fetch dataset metadata for display name
+ */
+async function fetchDatasetName(client, datasetId) {
+    try {
+        const response = await client.GET("/v1/datasets/{id}", {
+            params: {
+                path: {
+                    id: datasetId,
+                },
+            },
+        });
+        if (response.error || !response.data) {
+            return undefined;
+        }
+        return response.data.data.name;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Dataset command handler
+ */
+async function datasetHandler(datasetIdentifier, options) {
+    try {
+        const userSpecifiedFormat = process.argv.includes("--format") ||
+            process.argv.some((arg) => arg.startsWith("--format="));
+        // Resolve configuration
+        const config = resolveConfig({
+            cliOptions: {
+                endpoint: options.endpoint,
+                apiKey: options.apiKey,
+            },
+        });
+        // Validate that we have endpoint
+        if (!config.endpoint) {
+            const errors = [
+                "Phoenix endpoint not configured. Set PHOENIX_HOST environment variable or use --endpoint flag.",
+            ];
+            writeError({ message: getConfigErrorMessage({ errors }) });
+            process.exit(1);
+        }
+        // Create client
+        const client = createPhoenixClient({ config });
+        writeProgress({
+            message: `Resolving dataset: ${datasetIdentifier}`,
+            noProgress: !options.progress,
+        });
+        // Resolve dataset ID
+        const datasetId = await resolveDatasetId({
+            client,
+            datasetIdentifier,
+        });
+        // Fetch dataset name for display
+        const datasetName = await fetchDatasetName(client, datasetId);
+        writeProgress({
+            message: `Fetching examples from dataset ${datasetName || datasetId}...`,
+            noProgress: !options.progress,
+        });
+        // Fetch dataset examples
+        const data = await fetchDatasetExamples(client, datasetId, {
+            versionId: options.version,
+            splits: options.split,
+        });
+        writeProgress({
+            message: `Found ${data.examples.length} example(s)`,
+            noProgress: !options.progress,
+        });
+        // Determine output format
+        const outputFormat = options.file
+            ? "json"
+            : options.format || "pretty";
+        if (options.file && userSpecifiedFormat && options.format !== "json") {
+            writeError({
+                message: `Warning: --format is ignored when writing to a file; writing JSON to ${options.file}`,
+            });
+        }
+        // Format output
+        const output = formatDatasetExamplesOutput({
+            data,
+            datasetName,
+            format: outputFormat,
+        });
+        if (options.file) {
+            fs.writeFileSync(options.file, output, "utf-8");
+            writeProgress({
+                message: `Wrote dataset to ${options.file}`,
+                noProgress: !options.progress,
+            });
+        }
+        else {
+            writeOutput({ message: output });
+        }
+    }
+    catch (error) {
+        writeError({
+            message: `Error fetching dataset: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        process.exit(1);
+    }
+}
+/**
+ * Collect multiple --split options into an array
+ */
+function collectSplits(value, previous) {
+    return previous.concat([value]);
+}
+/**
+ * Create the dataset command
+ */
+export function createDatasetCommand() {
+    const command = new Command("dataset");
+    command
+        .description("Fetch examples from a dataset")
+        .argument("<dataset-identifier>", "Dataset name or ID")
+        .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("--file <path>", "Save output to file instead of stdout")
+        .option("--split <name>", "Filter by split name (can be used multiple times)", collectSplits, [])
+        .option("--version <id>", "Fetch from a specific dataset version")
+        .action(datasetHandler);
+    return command;
+}
+//# sourceMappingURL=dataset.js.map