@root-signals/scorable-cli 0.7.0 → 0.9.0

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

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import ora from "ora";
+import { requireApiKey } from "../../auth.js";
+import { apiRequestStatus } from "../../client.js";
+import { printError, printSuccess, handleSdkError } from "../../output.js";
+import { loadFilterYaml } from "../../lib/filter-yaml.js";
+import { CliError } from "../../types.js";
+export function registerValidateCommand(otelFilter) {
+    otelFilter
+        .command("validate")
+        .description("Validate an OTEL trace evaluation filter spec without saving")
+        .requiredOption("-f, --from-file <path>", "Filter spec path (YAML or JSON)")
+        .addHelpText("after", `
+Useful in CI to fail builds on a bad manifest before applying.
+
+Exit codes:
+  0   schema valid; no warnings
+  0   schema valid; warnings written to stderr (e.g. rules don't match any recent span)
+  2   schema invalid (local Zod failure or server 400)
+
+Example:
+  $ scorable otel-filter validate -f ./filter.yaml`)
+        .action(async (opts) => {
+        let source;
+        try {
+            source = fs.readFileSync(opts.fromFile, "utf8");
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            printError(`Failed to read --from-file: ${msg}`);
+            throw new CliError(1, msg);
+        }
+        let payload;
+        try {
+            payload = loadFilterYaml(source);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            printError(msg);
+            throw new CliError(2, msg);
+        }
+        const spinner = ora("Validating filter...").start();
+        try {
+            const apiKey = await requireApiKey();
+            const result = await apiRequestStatus("POST", "v1/otel/evaluation-filters/validate", {
+                payload,
+                apiKey,
+            });
+            spinner.stop();
+            if (!result.ok) {
+                if (result.status === 400) {
+                    throw new CliError(2, "Filter schema validation failed.");
+                }
+                throw new CliError(1, `Validation request failed (status ${result.status}).`);
+            }
+            const data = (result.data ?? {});
+            const warnings = Array.isArray(data.warnings) ? data.warnings : [];
+            if (warnings.length > 0) {
+                for (const w of warnings) {
+                    console.error(`warning: ${w}`);
+                }
+            }
+            printSuccess("OK");
+        }
+        catch (e) {
+            spinner.stop();
+            if (e instanceof CliError)
+                throw e;
+            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])) {