inspeffct 1.0.4 → 1.0.6

package/dist/bin.js

@@ -2,8 +2,8 @@
 import * as NodeRuntime from '@effect/platform-node/NodeRuntime';
 import * as NodeServices from '@effect/platform-node/NodeServices';
 import * as Effect10 from 'effect/Effect';
-import * as Command5 from 'effect/unstable/cli/Command';
-import * as Argument2 from 'effect/unstable/cli/Argument';
+import * as Command6 from 'effect/unstable/cli/Command';
+import * as Argument3 from 'effect/unstable/cli/Argument';
 import * as Context4 from 'effect/Context';
 import * as Fiber from 'effect/Fiber';
 import * as FileSystem from 'effect/FileSystem';
@@ -332,9 +332,9 @@ var randomUUID = Effect10.gen(function* () {
     hex.slice(10, 16).join("")
   ].join("-");
 });
-var ExecutionId = class extends Context4.Service()("inspeffct/ExecutionId") {
+var RunId = class extends Context4.Service()("inspeffct/RunId") {
 };
-var layer3 = Layer8.effect(ExecutionId, randomUUID);
+var layer3 = Layer8.effect(RunId, randomUUID);
 var isSchema = (u) => typeof u === "object" && u !== null && "ast" in u;
 var getMembers = (schema) => "members" in schema && Array.isArray(schema.members) ? schema.members : "cases" in schema ? Object.values(schema.cases) : [schema];
 var evolveNested = (schema, evolve2) => {
@@ -516,13 +516,13 @@ var create_otel_tables_default = Effect10.gen(function* () {
 });
 var create_span_exits_table_default = Effect10.void;
 var simplify_span_exits_default = Effect10.void;
-var add_execution_id_default = Effect10.gen(function* () {
+var add_run_id_default = Effect10.gen(function* () {
   const sql = yield* SqlClient5.SqlClient;
-  yield* sql`ALTER TABLE spans ADD COLUMN execution_id TEXT NOT NULL DEFAULT ''`.pipe(
-    Effect10.withSpan("add_spans_execution_id")
+  yield* sql`ALTER TABLE spans ADD COLUMN run_id TEXT NOT NULL DEFAULT ''`.pipe(
+    Effect10.withSpan("add_spans_run_id")
   );
-  yield* sql`CREATE INDEX idx_spans_execution_id ON spans(execution_id)`.pipe(
-    Effect10.withSpan("create_idx_spans_execution_id")
+  yield* sql`CREATE INDEX idx_spans_run_id ON spans(run_id)`.pipe(
+    Effect10.withSpan("create_idx_spans_run_id")
   );
 });
 
@@ -594,7 +594,7 @@ var DbExternalSpan = ExternalSpan.pipe(
 );
 var DbAnySpan = Schema.Union([DbSpan, DbExternalSpan]);
 var TraceSummary = Schema.Struct({
-  execution_id: Schema.String,
+  run_id: Schema.String,
   trace_id: Schema.String,
   span_count: NumberFromBigInt,
   root_span_name: Schema.NullOr(Schema.String),
@@ -620,7 +620,7 @@ var MigrationsLoader = Migrator.fromRecord({
   "0001_create_otel_tables": create_otel_tables_default,
   "0002_create_span_exits_table": create_span_exits_table_default,
   "0003_simplify_span_exits": simplify_span_exits_default,
-  "0004_add_execution_id": add_execution_id_default
+  "0004_add_run_id": add_run_id_default
 });
 var runMigrations = Migrator.make({})({
   loader: MigrationsLoader
@@ -630,14 +630,14 @@ var layer5 = (config) => Layer8.effectContext(
     const sql = yield* SqliteClient.SqliteClient;
     yield* runMigrations;
     const storage = Storage.of({
-      persistSpan: (span, executionId) => Effect10.gen(function* () {
+      persistSpan: (span, runId) => Effect10.gen(function* () {
         const changed = yield* (
           // @ts-ignore TS28 false positive from SqlSchema service inference
           SqlSchema.findOne({
             Request: DbAnySpan,
             Result: Schema.Struct({ span_id: Schema.String }),
             execute: (db) => {
-              const row = { ...db, execution_id: executionId };
+              const row = { ...db, run_id: runId };
               return sql`
                     INSERT INTO spans ${sql.insert(row)}
                     ON CONFLICT(span_id) DO UPDATE SET
@@ -756,22 +756,22 @@ var layer5 = (config) => Layer8.effectContext(
       }),
       getTraces: (filters = {}) => SqlSchema.findAll({
         Request: Schema.Struct({
-          executionId: Schema.optional(Schema.String),
           limit: Schema.optional(Schema.Number),
+          runId: Schema.optional(Schema.String),
           since: Schema.optional(Schema.BigInt),
           status: Schema.optional(Schema.Number)
         }),
         Result: TraceSummary,
         execute: (req) => sql`
                 SELECT 
-                  s.execution_id,
+                  s.run_id,
                   s.trace_id,
                   COUNT(*) as span_count,
                   (
                     SELECT name
                     FROM spans
                     WHERE trace_id = s.trace_id
-                      AND execution_id = s.execution_id
+                      AND run_id = s.run_id
                       AND parent_span_id IS NULL
                     LIMIT 1
                   ) as root_span_name,
@@ -786,7 +786,7 @@ var layer5 = (config) => Layer8.effectContext(
                   ) as status
                 FROM spans s
                 WHERE ${sql.and([
-          req.executionId !== void 0 ? sql`s.execution_id = ${req.executionId}` : sql`1=1`,
+          req.runId !== void 0 ? sql`s.run_id = ${req.runId}` : sql`1=1`,
           req.since !== void 0 ? sql`s.start_time >= ${req.since}` : sql`1=1`,
           req.status !== void 0 ? sql`
                       CASE
@@ -796,7 +796,7 @@ var layer5 = (config) => Layer8.effectContext(
                       END = ${req.status}
                     ` : sql`1=1`
         ])}
-                GROUP BY s.execution_id, s.trace_id
+                GROUP BY s.run_id, s.trace_id
                 ORDER BY start_time DESC
                 ${req.limit !== void 0 ? sql`LIMIT ${req.limit}` : sql``}
               `
@@ -807,10 +807,11 @@ var layer5 = (config) => Layer8.effectContext(
         // @ts-ignore TS28 false positive from SqlSchema service inference
         SqlSchema.findAll({
           Request: Schema.Struct({
-            executionId: Schema.optional(Schema.String),
             limit: Schema.optional(Schema.Number),
             minDuration: Schema.optional(Schema.BigInt),
             name: Schema.optional(Schema.String),
+            runId: Schema.optional(Schema.String),
+            spanId: Schema.optional(Schema.String),
             status: Schema.optional(Schema.Number),
             traceId: Schema.optional(Schema.String)
           }),
@@ -819,7 +820,8 @@ var layer5 = (config) => Layer8.effectContext(
                 SELECT s.*
                 FROM spans s
                 WHERE ${sql.and([
-            req.executionId !== void 0 ? sql`s.execution_id = ${req.executionId}` : sql`1=1`,
+            req.runId !== void 0 ? sql`s.run_id = ${req.runId}` : sql`1=1`,
+            req.spanId !== void 0 ? sql`s.span_id = ${req.spanId}` : sql`1=1`,
             req.traceId !== void 0 ? sql`s.trace_id = ${req.traceId}` : sql`1=1`,
             req.name !== void 0 ? req.name.includes("%") ? sql`s.name LIKE ${req.name}` : sql`s.name = ${req.name}` : sql`1=1`,
             req.minDuration !== void 0 ? sql`(s.end_time - s.start_time) >= ${req.minDuration}` : sql`1=1`,
@@ -849,7 +851,7 @@ var EventCollector = class extends Context4.Service()("inspeffct/EventCollector"
 var layer6 = Layer8.effect(
   EventCollector,
   Effect10.gen(function* () {
-    const executionId = yield* ExecutionId;
+    const runId = yield* RunId;
     const storage = yield* Storage;
     return EventCollector.of({
       collect: (message) => Effect10.gen(function* () {
@@ -863,12 +865,10 @@ var layer6 = Layer8.effect(
           case "TracerSpanNotification": {
             const { instrumentationId, span } = message;
             yield* Effect10.logDebug(`${message._tag} from ${instrumentationId}`);
-            if (span._tag === "Span" && span.status._tag === "Ended") {
-              yield* storage.persistSpan(span, executionId);
-              yield* Effect10.logDebug(
-                `Persisted span ${span.name} (${span.spanId}) with exit ${span.status.exit._tag} to storage`
-              );
-            }
+            yield* storage.persistSpan(span, runId);
+            yield* Effect10.logDebug(
+              `Persisted span (${span.traceId}, ${span.spanId}) to storage`
+            );
             break;
           }
           case "TracerSpanEventNotification": {
@@ -1139,16 +1139,16 @@ var buildEnv = (bootloaderPath, ipcPath) => {
   };
 };
 var makeServicesLayer = (dataPath) => {
-  const executionIdLayer = layer3;
+  const runIdLayer = layer3;
   const storageLayer = layer5({ filename: dataPath });
   const eventCollectorLayer = layer6.pipe(
-    Layer8.provide(executionIdLayer),
+    Layer8.provide(runIdLayer),
     Layer8.provide(storageLayer)
   );
   const bootloaderPathLayer = layer.pipe(Layer8.provide(NodePath.layer));
   return Layer8.mergeAll(
-    executionIdLayer,
     layer8,
+    runIdLayer,
     bootloaderPathLayer,
     layer7.pipe(
       Layer8.provide(layer2),
@@ -1163,12 +1163,12 @@ var makeServicesLayer = (dataPath) => {
 var makeReadOnlyLayer = (dataPath) => layer5({ filename: dataPath });
 
 // src/cli/connect.ts
-var command = Command5.make(
+var command = Command6.make(
   "connect",
   {
     data: dataOption,
-    url: Argument2.string("url").pipe(
-      Argument2.withDescription("WebSocket URL of the inspector (ws://...)")
+    url: Argument3.string("url").pipe(
+      Argument3.withDescription("WebSocket URL of the inspector (ws://...)")
     )
   },
   ({ data, url }) => Effect10.gen(function* () {
@@ -1182,7 +1182,19 @@ var command = Command5.make(
     Effect10.scoped,
     Effect10.provide(makeServicesLayer(data))
   )
-).pipe(Command5.withDescription("Connect to an existing inspector endpoint"));
+).pipe(
+  Command6.withDescription("Connect to an existing CDP inspector endpoint"),
+  Command6.withExamples([
+    {
+      command: "inspeffct connect ws://127.0.0.1:9229/<id>",
+      description: "Connect to a running Node.js inspector endpoint"
+    },
+    {
+      command: "inspeffct connect --data .inspeffct.db ws://127.0.0.1:9229/<id>",
+      description: "Persist captured data to a specific SQLite database"
+    }
+  ])
+);
 var NODE_INSPECTOR_REGEX = /Debugger listening on (ws:\/\/[^\s]+)/;
 var BUN_INSPECTOR_REGEX = /https:\/\/debug\.bun\.sh\/#([^\s]+)/;
 var parseInspectorUrl = (chunk, decoder) => {
@@ -1197,7 +1209,7 @@ var parseInspectorUrl = (chunk, decoder) => {
   }
   return void 0;
 };
-var command2 = Command5.make(
+var command2 = Command6.make(
   "run",
   {
     data: dataOption,
@@ -1205,17 +1217,17 @@ var command2 = Command5.make(
       Flag3.optional,
       Flag3.withHidden
     ),
-    args: Argument2.string("command").pipe(
-      Argument2.withDescription("The command to run"),
-      Argument2.variadic({ min: 0 })
+    args: Argument3.string("command").pipe(
+      Argument3.withDescription("The command to run"),
+      Argument3.variadic({ min: 0 })
     )
   },
   ({ args, data, encodedCommand }) => Effect10.gen(function* () {
     const resolvedArgs = Option3.isSome(encodedCommand) ? JSON.parse(Buffer.from(encodedCommand.value, "base64url").toString("utf8")) : args;
     const [rawExecutable, ...commandArgs] = resolvedArgs;
     const executable = rawExecutable === "node" ? process.execPath : rawExecutable;
-    const executionId = yield* ExecutionId;
-    yield* Console2.log(`Execution ID: ${executionId}`);
+    const runId = yield* RunId;
+    yield* Console2.log(`Inspeffct Run ID: ${runId}`);
     yield* Effect10.logDebug(`Running: ${executable} ${commandArgs.join(" ")}`);
     yield* Effect10.logDebug(`Data file: ${data}`);
     const bootloaderPath = yield* getPath;
@@ -1268,7 +1280,19 @@ var command2 = Command5.make(
     Effect10.scoped,
     Effect10.provide(makeServicesLayer(data))
   )
-).pipe(Command5.withDescription("Run a command with Effect instrumentation"));
+).pipe(
+  Command6.withDescription("Run a command with Effect instrumentation"),
+  Command6.withExamples([
+    {
+      command: "inspeffct run -- node app.js",
+      description: "Run a Node.js application with instrumentation"
+    },
+    {
+      command: "inspeffct run --data .inspeffct.db -- node --inspect app.js",
+      description: "Capture data in a specific SQLite database"
+    }
+  ])
+);
 var getSpanId = (span) => span.spanId;
 var getTraceId = (span) => span.traceId;
 var getParentSpanId = (span) => span._tag === "Span" ? span.parentSpanId : null;
@@ -1321,6 +1345,7 @@ var formatStatusDoc = (status) => {
   }
 };
 var field = (label, value) => `${label}: ${value}`;
+var dim = (text) => `\x1B[2m${text}\x1B[22m`;
 var renderDoc = (doc) => doc;
 var statusSymbol = (status, hasEndTime) => {
   if (!hasEndTime) {
@@ -1360,6 +1385,17 @@ var formatSpanLine = (span) => {
   const duration = endTime !== null ? formatDuration(endTime - startTime) : "running";
   return `${symbol} ${getSpanName(span)} (${duration}) [${getSpanId(span)}]`;
 };
+var formatAttributeValue = (value) => {
+  const json = JSON.stringify(value);
+  return json === void 0 ? "undefined" : json;
+};
+var formatSpanAttributesLine = (span) => {
+  const attributes = Object.entries(getAttributes(span));
+  if (attributes.length === 0) {
+    return null;
+  }
+  return attributes.map(([key, value]) => `${key}=${formatAttributeValue(value)}`).join(", ");
+};
 var renderGraphNode = (graph, nodeIndex, prefix, isLast, isRoot) => {
   const spanOpt = Graph.getNode(graph, nodeIndex);
   if (Option3.isNone(spanOpt)) return "";
@@ -1375,10 +1411,13 @@ var renderGraphNode = (graph, nodeIndex, prefix, isLast, isRoot) => {
   const connector = isRoot ? "" : isLast ? "\u2514\u2500 " : "\u251C\u2500 ";
   const line = `${prefix}${connector}${formatSpanLine(span)}`;
   const childPrefix = isRoot ? "" : prefix + (isLast ? "   " : "\u2502  ");
+  const attributePrefix = isRoot ? "  " : `${childPrefix}   `;
+  const attributesLine = formatSpanAttributesLine(span);
+  const attributeDoc = attributesLine === null ? [] : [`${attributePrefix}${dim(attributesLine)}`];
   const childDocs = children.map(
     (child, i) => renderGraphNode(graph, child.index, childPrefix, i === children.length - 1, false)
   );
-  return [line, ...childDocs.filter((doc) => doc.length > 0)].join("\n");
+  return [line, ...attributeDoc, ...childDocs.filter((doc) => doc.length > 0)].join("\n");
 };
 var renderSpanGraph = (graph) => {
   const roots = [];
@@ -1393,13 +1432,133 @@ var renderSpanGraph = (graph) => {
   return rootDocs.filter((doc) => doc.length > 0).join("\n");
 };
 
-// src/cli/spans.ts
-var command3 = Command5.make(
+// src/cli/span.ts
+var attributesToObject = (attributes) => Object.fromEntries(attributes);
+var command3 = Command6.make(
+  "span",
+  {
+    data: dataOption,
+    json: jsonOption,
+    traceId: Argument3.string("trace-id").pipe(
+      Argument3.withDescription("The trace ID containing the span")
+    ),
+    spanId: Argument3.string("span-id").pipe(
+      Argument3.withDescription("The span ID to display")
+    )
+  },
+  ({ data, json, spanId, traceId }) => Effect10.gen(function* () {
+    const storage = yield* Storage;
+    const spans = yield* storage.getSpans({ spanId, traceId });
+    const span = spans[0];
+    if (span === void 0) {
+      yield* Console2.log(`No span found for trace: ${traceId}, span: ${spanId}`);
+      return;
+    }
+    const events = yield* storage.getSpanEvents({ traceId, spanId });
+    const links = yield* storage.getSpanLinks({ traceId, spanId });
+    const startTime = getStartTime(span);
+    const endTime = getEndTime(span);
+    const durationNanos = endTime !== null ? endTime - startTime : null;
+    if (json) {
+      const output = {
+        span: {
+          spanId: getSpanId(span),
+          traceId: getTraceId(span),
+          parentSpanId: getParentSpanId(span),
+          name: getSpanName(span),
+          kind: getSpanKind(span),
+          statusCode: getStatusCode(span),
+          statusMessage: getStatusMessage(span),
+          startTime: formatTimestamp(startTime),
+          endTime: endTime !== null ? formatTimestamp(endTime) : null,
+          durationMs: durationNanos !== null ? Number(durationNanos / 1000000n) : null,
+          attributes: getAttributes(span),
+          isExternal: isExternalSpan(span)
+        },
+        events: events.map((event) => ({
+          name: event.name,
+          time: formatTimestamp(event.time),
+          attributes: attributesToObject(event.attributes)
+        })),
+        links: links.map((link) => ({
+          linkedSpanId: link.linkedSpanId,
+          linkedTraceId: link.linkedTraceId,
+          attributes: attributesToObject(link.attributes)
+        }))
+      };
+      yield* Console2.log(JSON.stringify(output, null, 2));
+    } else {
+      const fields = [
+        field("Span", getSpanId(span)),
+        field("Name", getSpanName(span)),
+        field("Trace", getTraceId(span)),
+        field("Kind", String(getSpanKind(span))),
+        field("Status", formatStatusDoc(getStatusCode(span))),
+        field("Started", formatTimestamp(startTime)),
+        field("Duration", durationNanos !== null ? formatDuration(durationNanos) : "running")
+      ];
+      const parentSpanId = getParentSpanId(span);
+      if (parentSpanId !== null) {
+        fields.push(field("Parent", parentSpanId));
+      }
+      if (endTime !== null) {
+        fields.push(field("Ended", formatTimestamp(endTime)));
+      }
+      const statusMessage = getStatusMessage(span);
+      if (statusMessage !== null) {
+        fields.push(field("Status Message", statusMessage));
+      }
+      const attrs = getAttributes(span);
+      if (Object.keys(attrs).length > 0) {
+        fields.push(field("Attrs", JSON.stringify(attrs)));
+      }
+      const eventDocs = events.length === 0 ? ["Events: none"] : [
+        `Events (${events.length}):`,
+        ...events.map((event) => {
+          const attrs2 = attributesToObject(event.attributes);
+          const lines = [`  ${event.name} @ ${formatTimestamp(event.time)}`];
+          if (Object.keys(attrs2).length > 0) {
+            lines.push(`    ${field("Attrs", JSON.stringify(attrs2))}`);
+          }
+          return lines.join("\n");
+        })
+      ];
+      const linkDocs = links.length === 0 ? ["Links: none"] : [
+        `Links (${links.length}):`,
+        ...links.map((link) => {
+          const attrs2 = attributesToObject(link.attributes);
+          const lines = [`  ${link.linkedTraceId}/${link.linkedSpanId}`];
+          if (Object.keys(attrs2).length > 0) {
+            lines.push(`    ${field("Attrs", JSON.stringify(attrs2))}`);
+          }
+          return lines.join("\n");
+        })
+      ];
+      yield* Console2.log(renderDoc([...fields, "", ...eventDocs, "", ...linkDocs].join("\n")));
+    }
+  }).pipe(
+    Effect10.scoped,
+    Effect10.provide(makeReadOnlyLayer(data))
+  )
+).pipe(
+  Command6.withDescription("Show detailed span information"),
+  Command6.withExamples([
+    {
+      command: "inspeffct span <trace-id> <span-id>",
+      description: "Show span details with events and links"
+    },
+    {
+      command: "inspeffct span --json <trace-id> <span-id>",
+      description: "Print span details as JSON"
+    }
+  ])
+);
+var command4 = Command6.make(
   "spans",
   {
     data: dataOption,
-    executionId: Flag3.string("execution-id").pipe(
-      Flag3.withDescription("Filter by execution ID"),
+    runId: Flag3.string("run-id").pipe(
+      Flag3.withDescription("Filter by run ID"),
       Flag3.optional
     ),
     json: jsonOption,
@@ -1412,17 +1571,21 @@ var command3 = Command5.make(
       Flag3.withDescription("Filter by span name (use % for wildcards)"),
       Flag3.optional
     ),
+    spanId: Flag3.string("span-id").pipe(
+      Flag3.withDescription("Filter by span ID"),
+      Flag3.optional
+    ),
     status: Flag3.string("status").pipe(
       Flag3.withDescription("Filter by status: ok, error, unset"),
       Flag3.optional
     ),
-    trace: Flag3.string("trace").pipe(
+    trace: Flag3.string("trace-id").pipe(
       Flag3.withAlias("t"),
       Flag3.withDescription("Filter by trace ID"),
       Flag3.optional
     )
   },
-  ({ data, executionId, json, limit, minDuration, name, status, trace }) => Effect10.gen(function* () {
+  ({ data, json, limit, minDuration, name, runId, spanId, status, trace }) => Effect10.gen(function* () {
     const storage = yield* Storage;
     let statusCode;
     if (Option3.isSome(status)) {
@@ -1441,7 +1604,8 @@ var command3 = Command5.make(
       }
     }
     const filters = {
-      ...Option3.isSome(executionId) ? { executionId: executionId.value } : {},
+      ...Option3.isSome(runId) ? { runId: runId.value } : {},
+      ...Option3.isSome(spanId) ? { spanId: spanId.value } : {},
       ...Option3.isSome(trace) ? { traceId: trace.value } : {},
       ...Option3.isSome(name) ? { name: name.value } : {},
       ...statusCode !== void 0 ? { status: statusCode } : {},
@@ -1508,14 +1672,30 @@ var command3 = Command5.make(
     Effect10.scoped,
     Effect10.provide(makeReadOnlyLayer(data))
   )
-).pipe(Command5.withDescription("List spans with optional filters"));
-var command4 = Command5.make(
+).pipe(
+  Command6.withDescription("List spans with optional filters (from multiple traces)"),
+  Command6.withExamples([
+    {
+      command: "inspeffct spans --trace-id <trace-id>",
+      description: "List spans for a trace"
+    },
+    {
+      command: "inspeffct spans --run-id <run-id>",
+      description: "List spans captured during a specific run"
+    },
+    {
+      command: "inspeffct spans --span-id <span-id>",
+      description: "Find a span directly by ID"
+    }
+  ])
+);
+var command5 = Command6.make(
   "trace",
   {
     data: dataOption,
     json: jsonOption,
-    traceId: Argument2.string("trace-id").pipe(
-      Argument2.withDescription("The trace ID to display")
+    traceId: Argument3.string("trace-id").pipe(
+      Argument3.withDescription("The trace ID to display")
     )
   },
   ({ data, json, traceId }) => Effect10.gen(function* () {
@@ -1578,14 +1758,26 @@ var command4 = Command5.make(
     Effect10.scoped,
     Effect10.provide(makeReadOnlyLayer(data))
   )
-).pipe(Command5.withDescription("Show a trace as a tree view"));
-var command5 = Command5.make(
+).pipe(
+  Command6.withDescription("Show a trace as a tree view with its spans as well"),
+  Command6.withExamples([
+    {
+      command: "inspeffct trace <trace-id>",
+      description: "Show a trace tree"
+    },
+    {
+      command: "inspeffct trace --json <trace-id>",
+      description: "Print the trace tree as JSON"
+    }
+  ])
+);
+var command6 = Command6.make(
   "traces",
   {
     data: dataOption,
     json: jsonOption,
-    executionId: Flag3.string("execution-id").pipe(
-      Flag3.withDescription("Filter by execution ID"),
+    runId: Flag3.string("run-id").pipe(
+      Flag3.withDescription("Filter by run ID"),
       Flag3.optional
     ),
     limit: limitOption,
@@ -1598,7 +1790,7 @@ var command5 = Command5.make(
       Flag3.optional
     )
   },
-  ({ data, executionId, json, limit, since, status }) => Effect10.gen(function* () {
+  ({ data, json, limit, runId, since, status }) => Effect10.gen(function* () {
     const storage = yield* Storage;
     let statusCode;
     if (Option3.isSome(status)) {
@@ -1623,7 +1815,7 @@ var command5 = Command5.make(
       sinceNanos = nowNanos - durationNanos;
     }
     const filters = {
-      ...Option3.isSome(executionId) ? { executionId: executionId.value } : {},
+      ...Option3.isSome(runId) ? { runId: runId.value } : {},
       ...statusCode !== void 0 ? { status: statusCode } : {},
       ...sinceNanos !== void 0 ? { since: sinceNanos } : {},
       ...Option3.isSome(limit) ? { limit: limit.value } : {}
@@ -1667,14 +1859,35 @@ var command5 = Command5.make(
     Effect10.scoped,
     Effect10.provide(makeReadOnlyLayer(data))
   )
-).pipe(Command5.withDescription("List traces with optional filters"));
+).pipe(
+  Command6.withDescription("List traces with optional filters"),
+  Command6.withExamples([
+    {
+      command: "inspeffct traces",
+      description: "List recent traces"
+    },
+    {
+      command: "inspeffct traces --run-id <run-id>",
+      description: "List traces captured during a specific run"
+    },
+    {
+      command: "inspeffct traces --status error --since 1h",
+      description: "List recent traces that contain errors"
+    }
+  ])
+);
 
 // src/cli.ts
-var command6 = Command5.make("inspeffct").pipe(
-  Command5.withDescription("Inspect Effect applications without code changes"),
-  Command5.withSubcommands([command2, command, command5, command4, command3])
+var command7 = Command6.make("inspeffct").pipe(
+  Command6.withDescription(
+    "Run your Effect application with `npx inspeffct run ...` to start capturing data, and then inspect data with the CLI."
+  ),
+  Command6.withSubcommands([
+    { group: "Capture", commands: [command2, command] },
+    { group: "Inspect", commands: [command6, command5, command4, command3] }
+  ])
 );
-var cli = Command5.runWith(command6, {
+var cli = Command6.runWith(command7, {
   version: "0.0.1"
 });
 var encodeRunSeparator = (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inspeffct",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "description": "A CLI to help agents and humans inspect Effect applications",
   "license": "MIT",