@root-signals/scorable-cli 0.7.0 → 0.8.0

package/README.md

@@ -258,6 +258,124 @@ Options: `--page-size`, `--cursor`, `--search`, `--evaluator-id`, `--judge-id`,
 scorable execution-log get <log_id>
 ```
 
+## OTEL Trace Evaluation Filters
+
+When traces arrive at Scorable's OTLP endpoint, evaluation filters automatically run an evaluator or judge against each matching trace. Results land back on the same trace as a child span carrying the OpenTelemetry GenAI evaluation attributes (`gen_ai.evaluation.name`, `gen_ai.evaluation.score.value`, `gen_ai.evaluation.explanation`).
+
+### Create a filter
+
+```bash
+scorable otel-filter create \
+  --name "default-truthfulness" \
+  --evaluator-id <evaluator-uuid>
+```
+
+Required: `--name` and exactly one of `--evaluator-id` or `--judge-id`. A judge target emits one eval span per inner evaluator.
+
+Options: `--filter-criteria` (JSON of conditions), `--sampling-rate` (0.0–1.0, default 1.0), `--delay-seconds` (default 10, allows late spans to land before evaluation), `--inactive`
+
+Match traces from a specific service, run a 5-second-delayed evaluation:
+
+```bash
+scorable otel-filter create \
+  --name "agent-truthfulness" \
+  --evaluator-id <evaluator-uuid> \
+  --filter-criteria '{"conditions":[{"column":"resource","type":"string","key":"service.name","operator":"=","value":"my_agent"}]}' \
+  --delay-seconds 5
+```
+
+Multi-evaluator judge target:
+
+```bash
+scorable otel-filter create --name "quality-judge" --judge-id <judge-uuid>
+```
+
+### List filters
+
+```bash
+scorable otel-filter list
+```
+
+### Delete a filter
+
+```bash
+scorable otel-filter delete <filter_id>
+```
+
+## OTEL Trace Querying
+
+### List traces
+
+```bash
+scorable otel-trace list
+```
+
+Options: `--since` / `--start-time` / `--end-time` (time window), `--page-size`, `--cursor`, `--output table|json|csv` (default `table`), `--filter` (repeatable raw expression), plus convenience shortcuts below.
+
+Convenience flags — cover the common case, AND-combined with each other and with `--filter`:
+
+| Flag                    | Effect                                 |
+| ----------------------- | -------------------------------------- |
+| `--service-name <name>` | match `resource.service.name = <name>` |
+| `--has-error`           | only traces where some span errored    |
+| `--root-name <substr>`  | substring match on the root span name  |
+| `--span-name <substr>`  | substring match on any span's name     |
+| `--agent-name <name>`   | match `gen_ai.agent.name`              |
+| `--model <name>`        | match `gen_ai.request.model`           |
+| `--tool <name>`         | match `gen_ai.tool.name`               |
+
+Time-window flags (mutually exclusive group):
+
+```bash
+scorable otel-trace list --since 1h          # last hour
+scorable otel-trace list --since 7d
+scorable otel-trace list --start-time 2026-04-30T00:00:00Z --end-time 2026-05-01T00:00:00Z
+```
+
+Common one-liners:
+
+```bash
+# All traces from a specific agent in the last 24h, exported as CSV
+scorable otel-trace list --since 24h --service-name my_agent --output csv > traces.csv
+
+# Errored traces this week
+scorable otel-trace list --since 7d --has-error
+
+# Drill into traces that hit a specific tool
+scorable otel-trace list --tool fetch_customer_data
+```
+
+For anything the shortcuts don't cover, use `--filter` directly. Format: `column;type;key;operator;value`, repeatable, AND-combined. If your instrumentation follows the OpenTelemetry [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/) — pydantic-ai, OpenLLMetry, Logfire, OpenAI/Anthropic SDKs with otel all do — every documented attribute is filterable without extra setup.
+
+```bash
+# Expensive runs — over 5k input tokens
+scorable otel-trace list --since 24h \
+  --filter 'gen_ai.usage.input_tokens;number;gen_ai.usage.input_tokens;>;5000'
+
+# Multi-turn conversation drill-down
+scorable otel-trace list \
+  --filter 'gen_ai.conversation.id;string;gen_ai.conversation.id;=;conv_5j66'
+
+# Filter on Scorable's own evaluation result spans
+scorable otel-trace list \
+  --filter 'gen_ai.evaluation.name;string;gen_ai.evaluation.name;=;Truthfulness'
+```
+
+See `scorable otel-trace list --help` for the full column / operator / type reference.
+
+### Inspect spans for a trace
+
+```bash
+scorable otel-trace spans <trace_id>
+```
+
+Options: `--output table|json|csv`. The JSON form returns the full span payload — attributes, events, status, kind, `resource_attributes` — which is what you typically want for debugging or piping to `jq`.
+
+```bash
+scorable otel-trace spans <trace_id> --output json | jq '.[0].span.attributes'
+scorable otel-trace spans <trace_id> --output csv > spans.csv
+```
+
 ## Prompt Testing
 
 Initialize a config file and run experiments:

package/dist/client.d.ts

@@ -1,7 +1,15 @@
-export declare function apiRequest(method: string, endpoint: string, options?: {
+interface RequestOptions {
     payload?: Record<string, unknown>;
     params?: Record<string, unknown>;
     apiKey?: string;
     baseUrl?: string;
-}): Promise<unknown>;
+}
+export interface ApiRequestResult {
+    ok: boolean;
+    status: number;
+    data: unknown;
+}
+export declare function apiRequestStatus(method: string, endpoint: string, options?: RequestOptions): Promise<ApiRequestResult>;
+export declare function apiRequest(method: string, endpoint: string, options?: RequestOptions): Promise<unknown>;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAQA,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,OAAO,CAAC,CAoDlB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAQA,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAQD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAoD3B;AAKD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/client.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { getApiKey, getBaseUrl } from "./auth.js";
 import { printError, printJson } from "./output.js";
 const { version } = createRequire(import.meta.url)("../package.json");
-export async function apiRequest(method, endpoint, options) {
+export async function apiRequestStatus(method, endpoint, options) {
     const apiKey = options?.apiKey ?? getApiKey();
     const baseUrl = options?.baseUrl ?? getBaseUrl();
     const seg = endpoint.endsWith("/") ? endpoint : `${endpoint}/`;
@@ -30,10 +30,10 @@ export async function apiRequest(method, endpoint, options) {
     }
     catch (e) {
         printError(`Request failed: ${e instanceof Error ? e.message : String(e)}`);
-        return null;
+        return { ok: false, status: 0, data: null };
     }
     if (response.status === 204)
-        return null;
+        return { ok: true, status: 204, data: null };
     if (!response.ok) {
         printError(`API Error: ${response.status} for ${method} ${url}`);
         try {
@@ -42,13 +42,17 @@ export async function apiRequest(method, endpoint, options) {
         catch {
             printError(`Response content: ${await response.text().catch(() => "")}`);
         }
-        return null;
+        return { ok: false, status: response.status, data: null };
     }
     try {
-        return await response.json();
+        return { ok: true, status: response.status, data: await response.json() };
     }
     catch {
         printError(`Failed to decode JSON response from API for ${url}.`);
-        return null;
+        return { ok: false, status: response.status, data: null };
     }
 }
+export async function apiRequest(method, endpoint, options) {
+    const result = await apiRequestStatus(method, endpoint, options);
+    return result.ok ? result.data : null;
+}

package/dist/commands/otel-filter/create.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerCreateCommand(otelFilter: Command): void;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/otel-filter/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-filter/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAmH/D"}

package/dist/commands/otel-filter/create.js

@@ -0,0 +1,105 @@
+import ora from "ora";
+import { requireApiKey } from "../../auth.js";
+import { apiRequest } from "../../client.js";
+import { printSuccess, printError, printJson, handleSdkError } from "../../output.js";
+export function registerCreateCommand(otelFilter) {
+    otelFilter
+        .command("create")
+        .description("Create a new OTEL trace evaluation filter. Wires either an evaluator OR a judge to incoming traces.")
+        .requiredOption("--name <name>", "Filter name")
+        .option("--evaluator-id <id>", "Evaluator UUID to run on matching traces (mutually exclusive with --judge-id)")
+        .option("--judge-id <id>", "Judge UUID to run on matching traces (mutually exclusive with --evaluator-id)")
+        .option("--filter-criteria <json>", 'Filter conditions as JSON, e.g. \'{"conditions":[{"column":"name","type":"string","key":"name","operator":"contains","value":"agent"}]}\'')
+        .option("--sampling-rate <rate>", "Sampling rate between 0.0 and 1.0", "1.0")
+        .option("--delay-seconds <seconds>", "Delay before evaluation (allows late spans)", "10")
+        .option("--inactive", "Create the filter as inactive", false)
+        .addHelpText("after", `
+Target — exactly one of --evaluator-id or --judge-id is required.
+  --evaluator-id  Runs a single evaluator (one score, one justification).
+  --judge-id      Runs a judge — a bundle of evaluators that produces an
+                  aggregate verdict plus per-evaluator scores. Use this
+                  when you've already authored a judge for the agent
+                  you're tracing.
+
+Examples:
+  # Match every span and run a single evaluator
+  $ scorable otel-filter create \\
+      --name "default-truthfulness" \\
+      --evaluator-id <evaluator-uuid>
+
+  # Run a judge (multi-evaluator) on every trace from a service
+  $ scorable otel-filter create \\
+      --name "construction-quality-judge" \\
+      --judge-id <judge-uuid> \\
+      --filter-criteria '{"conditions":[{"column":"resource","type":"string","key":"service.name","operator":"=","value":"construction_assistant_agent"}]}' \\
+      --delay-seconds 5
+
+  # Match only traces from a specific service (resource attribute), evaluator target
+  $ scorable otel-filter create \\
+      --name "construction-truthfulness" \\
+      --evaluator-id <evaluator-uuid> \\
+      --filter-criteria '{"conditions":[{"column":"resource","type":"string","key":"service.name","operator":"=","value":"construction_assistant_agent"}]}' \\
+      --delay-seconds 5
+
+  # Match by span attribute (gen_ai semantic conventions)
+  $ scorable otel-filter create \\
+      --name "agent-truthfulness" \\
+      --evaluator-id <evaluator-uuid> \\
+      --filter-criteria '{"conditions":[{"column":"gen_ai.agent.name","type":"string","key":"gen_ai.agent.name","operator":"=","value":"my_agent"}]}'`)
+        .action(async (opts) => {
+        if (!opts.evaluatorId && !opts.judgeId) {
+            printError("Either --evaluator-id or --judge-id is required.");
+            process.exit(1);
+        }
+        if (opts.evaluatorId && opts.judgeId) {
+            printError("--evaluator-id and --judge-id are mutually exclusive.");
+            process.exit(1);
+        }
+        let filterCriteria = {};
+        if (opts.filterCriteria) {
+            try {
+                filterCriteria = JSON.parse(opts.filterCriteria);
+            }
+            catch {
+                printError("Invalid JSON for --filter-criteria.");
+                process.exit(1);
+            }
+        }
+        const samplingRate = parseFloat(opts.samplingRate ?? "1.0");
+        if (Number.isNaN(samplingRate) || samplingRate < 0 || samplingRate > 1) {
+            printError("--sampling-rate must be a number between 0.0 and 1.0.");
+            process.exit(1);
+        }
+        const delaySeconds = parseInt(opts.delaySeconds ?? "10", 10);
+        if (Number.isNaN(delaySeconds) || delaySeconds < 0) {
+            printError("--delay-seconds must be a non-negative integer.");
+            process.exit(1);
+        }
+        const payload = {
+            name: opts.name,
+            filter_criteria: filterCriteria,
+            sampling_rate: samplingRate,
+            delay_seconds: delaySeconds,
+            is_active: !opts.inactive,
+        };
+        if (opts.evaluatorId)
+            payload.evaluator_id = opts.evaluatorId;
+        if (opts.judgeId)
+            payload.judge_id = opts.judgeId;
+        const spinner = ora("Creating filter...").start();
+        try {
+            const apiKey = await requireApiKey();
+            const result = await apiRequest("POST", "v1/otel/evaluation-filters", { payload, apiKey });
+            spinner.stop();
+            if (result === null) {
+                throw new Error("Filter creation failed.");
+            }
+            printSuccess("Filter created.");
+            printJson(result);
+        }
+        catch (e) {
+            spinner.stop();
+            handleSdkError(e);
+        }
+    });
+}

package/dist/commands/otel-filter/delete.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerDeleteCommand(otelFilter: Command): void;
+//# sourceMappingURL=delete.d.ts.map

package/dist/commands/otel-filter/delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-filter/delete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAwB/D"}

package/dist/commands/otel-filter/delete.js

@@ -0,0 +1,25 @@
+import ora from "ora";
+import { requireApiKey } from "../../auth.js";
+import { apiRequestStatus } from "../../client.js";
+import { printSuccess, handleSdkError } from "../../output.js";
+export function registerDeleteCommand(otelFilter) {
+    otelFilter
+        .command("delete <id>")
+        .description("Delete an OTEL trace evaluation filter")
+        .action(async (id) => {
+        const spinner = ora("Deleting...").start();
+        try {
+            const apiKey = await requireApiKey();
+            const { ok } = await apiRequestStatus("DELETE", `v1/otel/evaluation-filters/${encodeURIComponent(id)}`, { apiKey });
+            spinner.stop();
+            if (!ok) {
+                process.exit(1);
+            }
+            printSuccess(`Filter ${id} deleted.`);
+        }
+        catch (e) {
+            spinner.stop();
+            handleSdkError(e);
+        }
+    });
+}

package/dist/commands/otel-filter/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerOtelFilterCommands(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/otel-filter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-filter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQjE"}

package/dist/commands/otel-filter/index.js

@@ -0,0 +1,11 @@
+import { registerCreateCommand } from "./create.js";
+import { registerListCommand } from "./list.js";
+import { registerDeleteCommand } from "./delete.js";
+export function registerOtelFilterCommands(program) {
+    const otelFilter = program
+        .command("otel-filter")
+        .description("Manage OTEL trace evaluation filters");
+    registerCreateCommand(otelFilter);
+    registerListCommand(otelFilter);
+    registerDeleteCommand(otelFilter);
+}

package/dist/commands/otel-filter/list.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerListCommand(otelFilter: Command): void;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/otel-filter/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-filter/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAwB7D"}

package/dist/commands/otel-filter/list.js

@@ -0,0 +1,29 @@
+import ora from "ora";
+import { requireApiKey } from "../../auth.js";
+import { apiRequest } from "../../client.js";
+import { printJson, handleSdkError, printMessage } from "../../output.js";
+export function registerListCommand(otelFilter) {
+    otelFilter
+        .command("list")
+        .description("List OTEL trace evaluation filters")
+        .action(async () => {
+        const spinner = ora("Fetching...").start();
+        try {
+            const apiKey = await requireApiKey();
+            const result = await apiRequest("GET", "v1/otel/evaluation-filters", { apiKey });
+            spinner.stop();
+            if (result === null) {
+                process.exit(1);
+            }
+            if (Array.isArray(result) && result.length === 0) {
+                printMessage("No filters found.");
+                return;
+            }
+            printJson(result);
+        }
+        catch (e) {
+            spinner.stop();
+            handleSdkError(e);
+        }
+    });
+}

package/dist/commands/otel-trace/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerOtelTraceCommands(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/otel-trace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-trace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAOhE"}

package/dist/commands/otel-trace/index.js

@@ -0,0 +1,9 @@
+import { registerListCommand } from "./list.js";
+import { registerSpansCommand } from "./spans.js";
+export function registerOtelTraceCommands(program) {
+    const otelTrace = program
+        .command("otel-trace")
+        .description("Query OTEL traces ingested by Scorable");
+    registerListCommand(otelTrace);
+    registerSpansCommand(otelTrace);
+}

package/dist/commands/otel-trace/list.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerListCommand(otelTrace: Command): void;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/otel-trace/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-trace/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoFpC,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CA0P5D"}

package/dist/commands/otel-trace/list.js

@@ -0,0 +1,280 @@
+import ora from "ora";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { requireApiKey } from "../../auth.js";
+import { apiRequest } from "../../client.js";
+import { printJson, printMessage, printInfo, handleSdkError } from "../../output.js";
+import { buildTimeFilters, parseOutputFormat, resolveTimeWindow, toCsv } from "./shared.js";
+const UNICODE_CHARS = {
+    top: "─",
+    "top-mid": "┬",
+    "top-left": "┌",
+    "top-right": "┐",
+    bottom: "─",
+    "bottom-mid": "┴",
+    "bottom-left": "└",
+    "bottom-right": "┘",
+    left: "│",
+    "left-mid": "├",
+    mid: "─",
+    "mid-mid": "┼",
+    right: "│",
+    "right-mid": "┤",
+    middle: "│",
+};
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+function printTraceTable(traces) {
+    const table = new Table({
+        head: ["Trace ID", "Root Span", "Spans", "First Span"].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
+        colWidths: [34, 42, 7, 22],
+        wordWrap: true,
+    });
+    for (const t of traces) {
+        const ts = (t.first_span_at ?? "").slice(0, 19).replace("T", " ");
+        table.push([t.trace_id, truncate(t.root_span_name ?? "", 40), String(t.span_count), ts]);
+    }
+    console.log(table.toString());
+}
+function printTraceCsv(traces) {
+    const headers = [
+        "trace_id",
+        "root_span_name",
+        "span_count",
+        "first_span_at",
+        "last_span_at",
+        "input_preview",
+        "output_preview",
+    ];
+    const rows = traces.map((t) => [
+        t.trace_id,
+        t.root_span_name,
+        t.span_count,
+        t.first_span_at,
+        t.last_span_at,
+        t.input_preview,
+        t.output_preview,
+    ]);
+    process.stdout.write(toCsv(headers, rows));
+}
+export function registerListCommand(otelTrace) {
+    otelTrace
+        .command("list")
+        .description("List ingested OTEL traces, optionally filtered")
+        .option("--filter <expr>", "Filter expression (repeatable). Format: `column;type;key;operator;value`. See examples below.", (value, previous = []) => [...previous, value], [])
+        .option("--since <duration>", "Only traces from the last <duration>. Forms: 30s, 5m, 2h, 7d. Mutually exclusive with --start-time/--end-time.")
+        .option("--start-time <iso>", "Earliest first_span_at, inclusive (ISO 8601, e.g. 2026-04-30T00:00:00Z)")
+        .option("--end-time <iso>", "Latest first_span_at, exclusive (ISO 8601). Defaults to now.")
+        .option("--service-name <name>", "Match resource.service.name (=). Shortcut for --filter.")
+        .option("--has-error", "Only traces where some span ended with status ERROR. Shortcut for --filter.")
+        .option("--root-name <substr>", "Substring match on the root span name. Shortcut for --filter.")
+        .option("--span-name <substr>", "Substring match on any span's name. Shortcut for --filter.")
+        .option("--agent-name <name>", "Match gen_ai.agent.name (=). Shortcut for --filter.")
+        .option("--model <name>", "Match gen_ai.request.model (=). Shortcut for --filter.")
+        .option("--tool <name>", "Match gen_ai.tool.name (=). Shortcut for --filter.")
+        .option("--page-size <n>", "Number of traces per page", (v) => parseInt(v, 10), 25)
+        .option("--cursor <cursor>", "Pagination cursor (from a previous `next` response)")
+        .option("--output <format>", "Output format: table | json | csv", "table")
+        .addHelpText("after", `
+Filtering — three layers, pick the lowest one that fits
+
+  1. Convenience flags (covers ~80% of queries):
+       --service-name <name>     resource.service.name = <name>
+       --has-error               at least one span errored
+       --root-name <substr>      root span name contains <substr>
+       --span-name <substr>      any span name contains <substr>
+       --agent-name <name>       gen_ai.agent.name = <name>
+       --model <name>            gen_ai.request.model = <name>
+       --tool <name>             gen_ai.tool.name = <name>
+     All composable with each other and with --filter (AND-combined).
+
+  2. Time-window shortcuts:
+       --since 30s | 5m | 2h | 7d
+       --start-time / --end-time  ISO 8601 (inclusive start, exclusive end)
+     Mutually exclusive group; compile down to first_span_at filters.
+
+  3. Raw --filter (full power, anything the matcher supports):
+     One expression per --filter, repeatable, AND-combined.
+
+Raw filter expression format
+  column;type;key;operator;value
+
+  column  - what to match against (see "Columns" below)
+  type    - value type: string | number | boolean | datetime | stringOptions
+  key     - same as column for built-ins; for sentinel columns
+            (resource, attribute) this is the attribute name
+  operator - one of: = != contains "starts with" "any of" "none of"
+             > >= < <= (numeric and datetime)
+  value   - the value to match. For "any of" / "none of",
+            pipe-separate multiple values: ok|error|unset.
+            For datetime, ISO 8601: 2026-04-30T00:00:00Z
+
+Columns
+  Trace-record level (per-trace metadata):
+    name             root span name
+    span_count       total spans in trace
+    first_span_at    earliest span timestamp (datetime)
+    last_span_at     latest span timestamp (datetime)
+    input_preview    first input message snippet
+    output_preview   final output snippet
+
+  Span level (matches if any span in the trace satisfies):
+    span_name        span name (e.g. "agent run", "execute_tool")
+    has_error        boolean: span ended with status code ERROR
+    kind             1=INTERNAL 2=SERVER 3=CLIENT 4=PRODUCER 5=CONSUMER
+    status           OK | ERROR | UNSET (use "any of" / "none of")
+
+  Sentinel columns (key carries the attribute name):
+    resource         resource attribute, e.g. service.name
+    <attribute-key>  any span attribute. If your instrumentation follows the
+                     OpenTelemetry GenAI semantic conventions (pydantic-ai,
+                     OpenLLMetry, Logfire, OpenAI/Anthropic SDKs with otel
+                     all do), every documented attribute is filterable here
+                     without extra setup. Common ones:
+
+                       Request:    gen_ai.request.model
+                                   gen_ai.request.temperature
+                                   gen_ai.request.max_tokens
+                       Response:   gen_ai.response.model
+                                   gen_ai.response.finish_reasons
+                       Agent/Op:   gen_ai.agent.name / .id / .version
+                                   gen_ai.operation.name (chat|embeddings|...)
+                                   gen_ai.workflow.name
+                                   gen_ai.provider.name (openai|aws.bedrock|...)
+                       Tools:      gen_ai.tool.name / .type / .call.id
+                       Tracking:   gen_ai.conversation.id
+                       Tokens:     gen_ai.usage.input_tokens
+                                   gen_ai.usage.output_tokens
+                                   gen_ai.usage.reasoning.output_tokens
+                                   gen_ai.usage.cache_read.input_tokens
+
+                     Full registry:
+                       https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+
+Examples — convenience flags (the common case)
+
+  # All traces from a specific service, last hour
+  $ scorable otel-trace list --since 1h --service-name my_agent
+
+  # Errored traces in the last 24h, exported as CSV for spreadsheet analysis
+  $ scorable otel-trace list --since 24h --has-error --output csv > errors.csv
+
+  # All traces of a specific pydantic-ai agent on a specific model
+  $ scorable otel-trace list --agent-name my_agent --model gpt-5-mini
+
+  # Drill into traces that hit a specific tool
+  $ scorable otel-trace list --since 7d --tool fetch_customer_data
+
+  # Mix shortcuts and raw filter — they AND together
+  $ scorable otel-trace list \\
+      --service-name my_agent \\
+      --filter 'gen_ai.usage.input_tokens;number;gen_ai.usage.input_tokens;>;1000'
+
+Examples — raw --filter (when shortcuts don't fit)
+
+  # Numeric comparison (no shortcut)
+  $ scorable otel-trace list \\
+      --filter 'gen_ai.usage.input_tokens;number;gen_ai.usage.input_tokens;>;1000'
+
+  # "any of" semantics with pipe-separated values
+  $ scorable otel-trace list \\
+      --filter 'kind;stringOptions;kind;any of;3|5'
+
+  # Multi-turn debugging — every trace in a single conversation
+  $ scorable otel-trace list \\
+      --filter 'gen_ai.conversation.id;string;gen_ai.conversation.id;=;conv_5j66'
+
+  # Expensive runs — over 5k input tokens
+  $ scorable otel-trace list --since 24h \\
+      --filter 'gen_ai.usage.input_tokens;number;gen_ai.usage.input_tokens;>;5000'
+
+  # Filter by provider — e.g. only Bedrock traffic
+  $ scorable otel-trace list \\
+      --filter 'gen_ai.provider.name;string;gen_ai.provider.name;=;aws.bedrock'
+
+  # Specific time range (inclusive start, exclusive end)
+  $ scorable otel-trace list \\
+      --start-time 2026-04-30T00:00:00Z \\
+      --end-time 2026-05-01T00:00:00Z
+
+  # Pagination — pass the cursor returned in the next-page hint
+  $ scorable otel-trace list --since 7d --cursor cD0yMDI2LTA0LTMwKzEx...
+
+  # Pipe JSON to jq for ad-hoc analysis
+  $ scorable otel-trace list --since 1h --output json | jq '.results[].trace_id'`)
+        .action(async (opts) => {
+        let format;
+        let timeFilters;
+        try {
+            format = parseOutputFormat(opts.output);
+            const window = resolveTimeWindow({
+                since: opts.since,
+                startTime: opts.startTime,
+                endTime: opts.endTime,
+            });
+            timeFilters = buildTimeFilters(window);
+        }
+        catch (e) {
+            handleSdkError(e);
+        }
+        const shortcutFilters = [];
+        if (opts.serviceName)
+            shortcutFilters.push(`resource;string;service.name;=;${opts.serviceName}`);
+        if (opts.hasError)
+            shortcutFilters.push("has_error;boolean;has_error;=;true");
+        if (opts.rootName)
+            shortcutFilters.push(`name;string;name;contains;${opts.rootName}`);
+        if (opts.spanName)
+            shortcutFilters.push(`span_name;string;span_name;contains;${opts.spanName}`);
+        if (opts.agentName)
+            shortcutFilters.push(`gen_ai.agent.name;string;gen_ai.agent.name;=;${opts.agentName}`);
+        if (opts.model)
+            shortcutFilters.push(`gen_ai.request.model;string;gen_ai.request.model;=;${opts.model}`);
+        if (opts.tool)
+            shortcutFilters.push(`gen_ai.tool.name;string;gen_ai.tool.name;=;${opts.tool}`);
+        const params = {};
+        const allFilters = [...timeFilters, ...shortcutFilters, ...opts.filter];
+        if (allFilters.length > 0)
+            params.filters = allFilters.join(",");
+        if (opts.pageSize !== undefined)
+            params.page_size = opts.pageSize;
+        if (opts.cursor)
+            params.cursor = opts.cursor;
+        const showSpinner = format === "table";
+        const spinner = showSpinner ? ora("Fetching traces...").start() : null;
+        try {
+            const apiKey = await requireApiKey();
+            const result = (await apiRequest("GET", "v1/otel/traces", {
+                params,
+                apiKey,
+            }));
+            spinner?.stop();
+            if (!result)
+                return;
+            if (format === "json") {
+                printJson(result);
+                return;
+            }
+            if (format === "csv") {
+                printTraceCsv(result.results ?? []);
+                return;
+            }
+            if (!result.results || result.results.length === 0) {
+                printMessage("No traces found.");
+                return;
+            }
+            printTraceTable(result.results);
+            if (result.next) {
+                const cursor = new URL(result.next).searchParams.get("cursor");
+                if (cursor)
+                    printInfo(`Next page available. Use --cursor "${cursor}"`);
+            }
+        }
+        catch (e) {
+            spinner?.stop();
+            handleSdkError(e);
+        }
+    });
+}

package/dist/commands/otel-trace/shared.d.ts

@@ -0,0 +1,17 @@
+export type OutputFormat = "table" | "json" | "csv";
+export declare function parseOutputFormat(value: string | undefined): OutputFormat;
+export declare function parseDuration(input: string): number;
+export declare function resolveTimeWindow(opts: {
+    since?: string;
+    startTime?: string;
+    endTime?: string;
+}): {
+    start?: string;
+    end?: string;
+};
+export declare function buildTimeFilters(window: {
+    start?: string;
+    end?: string;
+}): string[];
+export declare function toCsv(headers: string[], rows: unknown[][]): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/otel-trace/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-trace/shared.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAIzE;AAaD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASnD;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CA6BA;AAGD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CASnF;AAWD,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAIlE"}

package/dist/commands/otel-trace/shared.js

@@ -0,0 +1,73 @@
+export function parseOutputFormat(value) {
+    const v = (value ?? "table").toLowerCase();
+    if (v === "table" || v === "json" || v === "csv")
+        return v;
+    throw new Error(`Invalid --output format "${value}". Use: table, json, csv`);
+}
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/i;
+const UNIT_TO_MS = {
+    ms: 1,
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+export function parseDuration(input) {
+    const match = DURATION_PATTERN.exec(input.trim());
+    if (!match) {
+        throw new Error(`Invalid duration "${input}". Use forms like 30s, 5m, 2h, 7d (suffixes: ms, s, m, h, d).`);
+    }
+    const [, num, unit] = match;
+    return Number(num) * UNIT_TO_MS[unit.toLowerCase()];
+}
+export function resolveTimeWindow(opts) {
+    if (opts.since && (opts.startTime || opts.endTime)) {
+        throw new Error("--since cannot be combined with --start-time / --end-time.");
+    }
+    const end = opts.endTime ? new Date(opts.endTime) : undefined;
+    let start;
+    if (opts.since) {
+        const ms = parseDuration(opts.since);
+        start = new Date(Date.now() - ms);
+    }
+    else if (opts.startTime) {
+        start = new Date(opts.startTime);
+    }
+    if (start && Number.isNaN(start.getTime())) {
+        throw new Error(`Invalid --start-time: "${opts.startTime}".`);
+    }
+    if (end && Number.isNaN(end.getTime())) {
+        throw new Error(`Invalid --end-time: "${opts.endTime}".`);
+    }
+    if (start && end && start.getTime() >= end.getTime()) {
+        throw new Error("--start-time must be before --end-time.");
+    }
+    return {
+        start: start?.toISOString(),
+        end: end?.toISOString(),
+    };
+}
+export function buildTimeFilters(window) {
+    const filters = [];
+    if (window.start) {
+        filters.push(`first_span_at;datetime;first_span_at;>=;${window.start}`);
+    }
+    if (window.end) {
+        filters.push(`first_span_at;datetime;first_span_at;<;${window.end}`);
+    }
+    return filters;
+}
+function csvEscape(value) {
+    if (value === null || value === undefined)
+        return "";
+    const s = typeof value === "string" ? value : String(value);
+    if (/[",\n\r]/.test(s))
+        return `"${s.replace(/"/g, '""')}"`;
+    return s;
+}
+export function toCsv(headers, rows) {
+    const lines = [headers.map(csvEscape).join(",")];
+    for (const row of rows)
+        lines.push(row.map(csvEscape).join(","));
+    return lines.join("\n") + "\n";
+}

package/dist/commands/otel-trace/spans.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerSpansCommand(otelTrace: Command): void;
+//# sourceMappingURL=spans.d.ts.map

package/dist/commands/otel-trace/spans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.d.ts","sourceRoot":"","sources":["../../../src/commands/otel-trace/spans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoFpC,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CA+E7D"}

package/dist/commands/otel-trace/spans.js

@@ -0,0 +1,135 @@
+import ora from "ora";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { requireApiKey } from "../../auth.js";
+import { apiRequest } from "../../client.js";
+import { printJson, printMessage, handleSdkError } from "../../output.js";
+import { parseOutputFormat, toCsv } from "./shared.js";
+const UNICODE_CHARS = {
+    top: "─",
+    "top-mid": "┬",
+    "top-left": "┌",
+    "top-right": "┐",
+    bottom: "─",
+    "bottom-mid": "┴",
+    "bottom-left": "└",
+    "bottom-right": "┘",
+    left: "│",
+    "left-mid": "├",
+    mid: "─",
+    "mid-mid": "┼",
+    right: "│",
+    "right-mid": "┤",
+    middle: "│",
+};
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+function printSpanTable(spans) {
+    const table = new Table({
+        head: ["Span ID", "Parent", "Name", "Error", "Timestamp"].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
+        colWidths: [18, 18, 38, 7, 22],
+        wordWrap: true,
+    });
+    for (const s of spans) {
+        const ts = (s.timestamp ?? "").slice(0, 19).replace("T", " ");
+        const parent = s.parent_span_id || chalk.dim("(root)");
+        const errorMark = s.span?.has_error ? chalk.red("✖") : "";
+        table.push([s.span_id, parent, truncate(s.span?.name ?? "", 36), errorMark, ts]);
+    }
+    console.log(table.toString());
+}
+function printSpanCsv(spans) {
+    const headers = [
+        "span_id",
+        "parent_span_id",
+        "name",
+        "kind",
+        "has_error",
+        "status_code",
+        "timestamp",
+    ];
+    const rows = spans.map((s) => [
+        s.span_id,
+        s.parent_span_id,
+        s.span?.name ?? "",
+        s.span?.kind ?? "",
+        s.span?.has_error ?? "",
+        s.span?.status?.code ?? "",
+        s.timestamp,
+    ]);
+    process.stdout.write(toCsv(headers, rows));
+}
+export function registerSpansCommand(otelTrace) {
+    otelTrace
+        .command("spans <trace_id>")
+        .description("List all spans for a given trace")
+        .option("--output <format>", "Output format: table | json | csv", "table")
+        .addHelpText("after", `
+Output formats
+  table  Default. Pretty-printed columnar view: span_id, parent, name, error, timestamp.
+  json   Full payload — including attributes, events, links, status, kind, resource_attributes.
+         Use this for debugging or scripting.
+  csv    Flattened columns: span_id, parent_span_id, name, kind, has_error, status_code, timestamp.
+         Useful for spreadsheet analysis.
+
+Examples
+  # Tabular overview of all spans in a trace
+  $ scorable otel-trace spans 7b6e5bd99494c4ee46fbfd39b194c499
+
+  # Full span data for jq-piping
+  $ scorable otel-trace spans 7b6e5bd99494c4ee46fbfd39b194c499 --output json | jq '.[0].span'
+
+  # Inspect just the span attributes
+  $ scorable otel-trace spans <trace_id> --output json | \\
+      jq '.[].span | {name, attributes}'
+
+  # Pull resource attributes (e.g. service.name) from the first span
+  $ scorable otel-trace spans <trace_id> --output json | jq '.[0].span.resource_attributes'
+
+  # CSV for a quick latency / error overview
+  $ scorable otel-trace spans <trace_id> --output csv > spans.csv
+
+Tip
+  Find a trace_id first with \`scorable otel-trace list\`, then drill down here.`)
+        .action(async (traceId, opts) => {
+        let format;
+        try {
+            format = parseOutputFormat(opts.output);
+        }
+        catch (e) {
+            handleSdkError(e);
+        }
+        const showSpinner = format === "table";
+        const spinner = showSpinner ? ora(`Fetching spans for trace ${traceId}...`).start() : null;
+        try {
+            const apiKey = await requireApiKey();
+            const result = (await apiRequest("GET", `v1/otel/traces/${encodeURIComponent(traceId)}/spans`, { apiKey }));
+            spinner?.stop();
+            if (result === null)
+                return;
+            if (!Array.isArray(result)) {
+                throw new Error("Unexpected spans response: expected an array.");
+            }
+            const spans = result;
+            if (format === "json") {
+                printJson(spans);
+                return;
+            }
+            if (format === "csv") {
+                printSpanCsv(spans);
+                return;
+            }
+            if (spans.length === 0) {
+                printMessage(`No spans found for trace ${traceId}.`);
+                return;
+            }
+            printSpanTable(spans);
+        }
+        catch (e) {
+            spinner?.stop();
+            handleSdkError(e);
+        }
+    });
+}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiDpC,wBAAgB,SAAS,IAAI,OAAO,CAqBnC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmDpC,wBAAgB,SAAS,IAAI,OAAO,CAuBnC"}

package/dist/index.js

@@ -11,6 +11,8 @@ import { registerExecutionLogCommands } from "./commands/execution-log/index.js"
 import { registerAuthCommands } from "./commands/auth/index.js";
 import { registerSkillsAddCommand } from "./commands/skills-add.js";
 import { registerFileCommands } from "./commands/file/index.js";
+import { registerOtelFilterCommands } from "./commands/otel-filter/index.js";
+import { registerOtelTraceCommands } from "./commands/otel-trace/index.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 function buildBanner(ver) {
     const logo = chalk.hex("#4D9FFF");
@@ -63,6 +65,8 @@ export function createCli() {
     registerAuthCommands(program);
     registerSkillsAddCommand(program);
     registerFileCommands(program);
+    registerOtelFilterCommands(program);
+    registerOtelTraceCommands(program);
     return program;
 }
 if (realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@root-signals/scorable-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CLI for Scorable",
   "license": "Apache-2.0",
   "author": "Scorable",