Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): rename eve trace to eve traces (#1413)

Chad Hietala38cdff84a153
diff --git a/.changeset/trace-cli-plural.md b/.changeset/trace-cli-plural.md
new file mode 100644
index 000000000..cbdb38add
--- /dev/null
+++ b/.changeset/trace-cli-plural.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Renames the `eve trace` CLI command to `eve traces` so it matches the `/traces` TUI command and the plural `eve logs` command. `eve traces ls` and `eve traces <trace>` work as before; the old singular form is removed.
diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.md
index c01ece21d..39acdf485 100644
--- a/docs/guides/instrumentation.md
+++ b/docs/guides/instrumentation.md
@@ -13,7 +13,7 @@ When no authored `instrumentation.ts` exists, `eve dev` records agent, AI SDK, a
The directory is an immutable OTLP/JSON spool and remains available after `eve dev` exits, subject to the [retention policy](#local-trace-retention) below. Inspection tools may build a query index from these segments, but the index is derived and can be rebuilt without changing the captured trace data.
-Use `eve trace ls` to list captured traces and `eve trace <trace>` to inspect a session's span tree.
+Use `eve traces ls` to list captured traces and `eve traces <trace>` to inspect a session's span tree.
When a model call is served by Vercel AI Gateway, its `agent.step` span also carries the cost the gateway reported: `gen_ai.usage.cost` (raw inference, USD), `gen_ai.usage.gateway_cost` (with the gateway surcharge), `gen_ai.usage.input_cost` / `gen_ai.usage.output_cost` (the split), and `gen_ai.generation.id` for reconciliation with the gateway dashboard. These attributes only exist for gateway-served calls — other providers emit nothing. Cost per turn is the sum across the turn's step spans.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index f99ca05e9..fecb19244 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -17,8 +17,8 @@ The `eve` binary (`bin: eve`) runs from your app root, and every command first l
| `eve dev <url>` | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server |
| `eve logs [logid]` | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted) |
| `eve logs ls` | List `eve dev` diagnostic logs, most recent first |
-| `eve trace ls` | List locally captured agent traces, most recent first |
-| `eve trace [trace]` | Show a local span tree (the most recent when omitted) |
+| `eve traces ls` | List locally captured agent traces, most recent first |
+| `eve traces [trace]` | Show a local span tree (the most recent when omitted) |
| `eve link` | Link the directory to a Vercel project and pull AI Gateway credentials |
| `eve deploy` | Deploy the agent to Vercel production (links first if needed) |
| `eve eval` | Run evals against the local app or a remote target |
@@ -244,16 +244,16 @@ A log id is the file name without `.log` (for example `dev-2026-07-15T12-00-00.0
Each log has a same-named `.dump` sibling holding environment diagnostics and session stats as one JSON document. `eve logs --dump` (with or without a log id) prepends that document to the JSONL log body; the combined output is a valid JSON value stream (`eve logs --dump | jq -c .`), one self-contained report to attach to an issue. When a log has no dump, the flag is silently a no-op.
-## `eve trace`
+## `eve traces`
```bash
-eve trace ls # list traces, most recent first
-eve trace ls --json # emit machine-readable trace summaries
-eve trace # show the most recent span tree
-eve trace <trace> # show one span tree
+eve traces ls # list traces, most recent first
+eve traces ls --json # emit machine-readable trace summaries
+eve traces # show the most recent span tree
+eve traces <trace> # show one span tree
```
-`eve trace ls` reads the immutable OTLP/JSON segments captured under `.eve/traces/v1`; `eve dev` does not need to be running. `eve trace` accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed or incomplete segments are skipped without hiding valid spans from the same trace.
+`eve traces ls` reads the immutable OTLP/JSON segments captured under `.eve/traces/v1`; `eve dev` does not need to be running. `eve traces` accepts a full trace id, an `agent.session.id`, or an unambiguous prefix of either. Malformed or incomplete segments are skipped without hiding valid spans from the same trace.
## `eve link`
diff --git a/packages/eve/src/cli/commands/trace.integration.test.ts b/packages/eve/src/cli/commands/trace.integration.test.ts
index 19f57c016..92f7f0791 100644
--- a/packages/eve/src/cli/commands/trace.integration.test.ts
+++ b/packages/eve/src/cli/commands/trace.integration.test.ts
@@ -14,7 +14,7 @@ import {
const TRACE_ONE = "1".repeat(32);
const TRACE_TWO = "2".repeat(32);
-describe("eve trace", () => {
+describe("eve traces", () => {
const roots: string[] = [];
afterEach(async () => {
diff --git a/packages/eve/src/cli/commands/trace.ts b/packages/eve/src/cli/commands/trace.ts
index 3c5a4de6b..f77f6eee3 100644
--- a/packages/eve/src/cli/commands/trace.ts
+++ b/packages/eve/src/cli/commands/trace.ts
@@ -84,7 +84,7 @@ export function resolveLocalTrace(traces: readonly LocalTrace[], reference: stri
if (matches.length === 1) return matches[0]!;
if (matches.length === 0) {
throw new Error(
- `No local trace matches "${sanitizeForTerminal(reference)}". Run \`eve trace ls\` to list traces.`,
+ `No local trace matches "${sanitizeForTerminal(reference)}". Run \`eve traces ls\` to list traces.`,
);
}
throw ambiguousTraceError(matches, reference);
diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.ts
index 0433cc7eb..9bc5162d8 100644
--- a/packages/eve/src/cli/run.test.ts
+++ b/packages/eve/src/cli/run.test.ts
@@ -114,10 +114,10 @@ describe("CLI command registration", () => {
log: (message: string) => output.push(message),
};
- await runCli(["trace", "--help"], logger).catch(() => {});
+ await runCli(["traces", "--help"], logger).catch(() => {});
const help = output.join("\n");
- expect(help).toContain("Usage: eve trace [options] [trace]");
+ expect(help).toContain("Usage: eve traces [options] [trace]");
expect(help).not.toContain("show <trace>");
expect(help).toContain("ls");
});
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index 6985dddae..7d3292930 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -606,8 +606,8 @@ function createCliProgram(logger: CliLogger, runtime: CliRuntimeOverrides): Comm
});
const traces = program
- .command("trace [trace]")
- .usage("[options] [trace]\n eve trace ls [options]")
+ .command("traces [trace]")
+ .usage("[options] [trace]\n eve traces ls [options]")
.description("Show a local `eve dev` trace (the most recent when trace is omitted).")
.action(async (reference: string | undefined) => {
const { runTraceShowCommand } = await import("#cli/commands/trace.js");
diff --git a/research/provider-neutral-local-observability.md b/research/provider-neutral-local-observability.md
index a373ff515..8f597c2f0 100644
--- a/research/provider-neutral-local-observability.md
+++ b/research/provider-neutral-local-observability.md
@@ -197,7 +197,7 @@ local-tracing work.
convention and proves the trace tree in memory. Production remains unchanged.
4. **Persistence.** Write session traces as OTLP/JSON, restore provider-owned session context across
dev worker restarts, and apply payload capture policy. No browser UI.
-5. **Inspection.** Add minimal `eve trace ls` and `eve trace [trace]` commands. A graphical viewer is a
+5. **Inspection.** Add minimal `eve traces ls` and `eve traces [trace]` commands. A graphical viewer is a
separate design after the trace model stabilizes.
6. **Public providers.** Promote the proven lifecycle contract into public hooks and migrate OTel,
Vercel, Braintrust, and custom instrumentation onto it.