--- title: "CLI" description: "Reference for every eve CLI command." --- Relevant `eve` commands can run from the application root or any directory beneath it. Running `eve` with no command runs `eve init` when the current directory is not an eve project, or `eve dev` when it is. ## Commands | Command | Description | | ---------------------------------------------- | ------------------------------------------------------ | | `eve init [target]` | Create a new agent, or add one to an existing project | | `eve dev` | Start the local development server and terminal UI | | `eve remote connect --url ` | Open the terminal UI for an existing agent | | `eve remote invoke --url [prompt]` | Invoke an existing agent without a terminal UI | | `eve remote info --url ` | Inspect an existing agent | | `eve acp [url]` | Serve a local or existing agent through ACP over stdio | | `eve info` | Inspect the local application | | `eve set model [model] [--reasoning ]` | Change model and reasoning settings | | `eve build` / `eve start` | Build or serve the application | | `eve logs show [logid]` / `eve logs list` | Inspect local diagnostic logs | | `eve traces show [trace]` / `eve traces list` | Inspect local traces | | `eve link` / `eve deploy` | Link or deploy a Vercel project | | `eve eval` | Run evals against a local or remote target | | `eve add [item]` / `eve registry ` | Install and browse registry items | | `eve extension ` | Create and build extension packages | | `eve telemetry ` | Manage CLI telemetry collection | When `eve build` fails on discovery errors, it prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path. ## CLI telemetry eve collects CLI telemetry by default to improve the command-line interface. Run `eve telemetry disable` to disable it for this machine, or set `EVE_TELEMETRY_DISABLED=1` for one command. See [CLI telemetry](./telemetry) for the current data fields, exclusions, debug mode, notice, and local preference storage. ## `eve init` ```bash eve init [target] [--model ] [--reasoning ] [--channel-web-nextjs] [--non-interactive] ``` Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git. | Target | What happens | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `eve init my-agent` | Creates an agent project in `my-agent/` | | `eve init` or `eve init .` in an empty directory | Creates an agent project in the current directory | | `eve init` or `eve init .` in a directory with files other than environment metadata and no `package.json` | Refuses to overwrite the directory. Pass a new directory name, such as `eve init my-agent` | | `eve init` or `eve init .` in an existing project | Adds `agent/` plus missing `eve`, `ai`, and `zod` dependencies. Requires `package.json` and no existing `agent/` files | | `eve init path/to/app` | Adds an agent to the existing package at `path/to/app` | Existing packages do not need a target-selection prompt: run `eve init` from the project directory or `eve init path/to/app`. New projects in non-interactive environments need a new directory name, such as `eve init my-agent`. After scaffolding in an interactive human terminal, eve opens the TUI directly. Pass `-n` or `--non-interactive` to return after scaffolding instead. It still installs dependencies and follows the normal Git setup behavior. Noninteractive and coding-agent invocations return without starting an interactive session. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`. | Flag | Type | Default | Description | | ----------------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--model ` | string | `openai/gpt-6-luna-fast` | Set the root agent's AI Gateway model ID. | | `--reasoning ` | enum | `high` without `--model`; otherwise provider default | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. | | `--channel-web-nextjs` | flag | off | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead. | | `-n, --non-interactive` | flag | off | Scaffold and install dependencies without starting development. | ## `eve extension` Commands for reusable [extension](/docs/extensions) packages. An extension declares distinct authoring and distribution roots in `package.json#eve.extension` (for example `"eve": { "extension": { "source": "./extension", "dist": "./dist/extension" } }`). ### `eve extension init` ```bash eve extension init [target] ``` Creates a new extension package, installs dependencies, and initializes Git. Prints next steps instead of starting `eve dev`. | Target | What happens | | --------------------------- | ------------------------------------------------------------- | | `eve extension init my-crm` | New extension package in `my-crm/` | | `eve extension init .` | Scaffold in the current empty directory | | No target | Same as `.` for humans; coding agents get a short setup guide | Create-only: cannot target an existing project that already has a `package.json`. See [Extensions](/docs/extensions) for authoring and mount details. ### `eve extension build` ```bash eve extension build ``` Builds the complete agent-shaped extension tree into its configured dist root, emits declarations and compatibility metadata, and fills the package `exports` map. The original TypeScript source is not required in the published package. ## Set model settings Change the root agent's AI Gateway model and reasoning effort without opening the dev TUI: ```bash eve set model openai/gpt-6-sol --reasoning high eve set model --reasoning medium ``` Use `eve set model` to change the model, its reasoning effort, or both. Omit the optional model argument to keep the current model. When you set both, eve writes them to `agent/agent.ts` in one source edit. `--reasoning` accepts `provider-default`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`; `provider-default` removes the authored `reasoning` field. The command uses the same model ID validation and source editor as `/model` in the local dev TUI. It does not configure model credentials. The `model` argument cannot rewrite models defined with `defineDynamic`, an environment expression, or a provider-authored SDK model; change those models in `agent.ts`. `--reasoning` can still update an editable root config when its model comes from an SDK call. ## Registry items Commands for installing and discovering [shadcn registry](https://ui.shadcn.com/docs/registry) items. Official registry items use a kind and slug (for example, `extension/agent-browser`); URLs and configured registry addresses are also supported. ```bash eve add extension/agent-browser eve add channel/linear eve add channel/slack --skip-install eve add https://example.com/r/my-extension.json --overwrite eve registry add @acme=https://example.com/r/{name}.json eve registry search browser eve registry search browser --limit 5 eve registry search browser --registry @acme eve registry view @acme/my-extension eve add @acme/my-extension ``` `eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Interactive Vercel-backed setup signs in and creates or links a project when needed instead of stopping with a prerequisite. `--yes` accepts detected or recommended setup answers. Coding agents should use `eve add --non-interactive`, adding `--yes` to accept recommended setup values and reduce setup round trips. Explicit `--answer` values take precedence. This mode never opens an eve prompt. When a setup decision is missing, the NDJSON terminal event includes a stable question key and a safe continuation command; add the requested answer to that command. Supply answers with repeatable `--answer 'key='` options. Follow a reported `eve link` prerequisite before retrying Vercel Connect setup. Do not put secrets in command-line answers; use the integration's documented environment variable or secret store. When setup is skipped, cancelled, or needs more input after installation, eve prints or returns the matching `eve add --skip-install` continuation. It reruns the item's declared flows without reinstalling registry files. `eve registry add` records configured sources in `package.json#registries`. `eve registry list` aggregates the official catalog and all configured sources by default. `eve registry search` also includes [skills.sh](https://skills.sh), available without configuration at `@skills`, and groups results by source with each source's available result count. Search returns up to 10 matches per source by default; pass `--limit ` to request between 1 and 100. Either command can browse one supplied URL or namespace. Official and other universal items with explicit file targets do not require shadcn project configuration. ## `eve info` ```bash eve info [--json] ``` | Flag | Type | Default | Description | | -------- | ---- | ------- | ------------ | | `--json` | flag | off | Emit as JSON | Run this first when something behaves unexpectedly. It confirms a file was discovered, lists the active surface, and surfaces discovery diagnostics, all faster than booting the dev server. Static instructions appear in source order with their `system` or `user` role. Dynamic instruction results are runtime-only and do not appear here. ### JSON output `eve info --json` prints one JSON object. Scripts and CI checks can read it instead of the files under `.eve/`: | Field | Type | Description | | ------------------ | ---------------- | ----------------------------------------------------------------------------------------- | | `appRoot` | string | Application root | | `agentRoot` | string or `null` | Agent directory, or `null` when the project could not be compiled | | `layout` | string or `null` | Project layout | | `status` | string | Compile status, such as `ready` or `failed`; `unavailable` when nothing compiled | | `diagnostics` | object or `null` | Discovery diagnostic counts: `{ errors, warnings }` | | `model` | string or `null` | Root agent model id | | `instructions` | string or `null` | Static instruction files with their roles | | `skills` | string[] | Static skill names | | `tools` | string[] | Root agent tool names | | `toolInputSchemas` | object | Each tool's input schema as eve sends it to the model (see below) | | `subagents` | string[] | Declared subagent names | | `schedules` | string[] | Schedule names | | `channels` | object[] | Effective channel routes: `{ name, kind, method, urlPath }` | | `messaging` | object | Session route patterns: `{ create, messages, stream }` | | `artifacts` | object or `null` | Paths to the compiled manifest, discovery manifest, diagnostics, module map, and metadata | `toolInputSchemas.root` maps each root agent tool name to its JSON Schema, including tools from mounted extensions under their namespaced names. `toolInputSchemas.subagents` has one entry for each declared subagent, including nested subagents, and each value is the same kind of map for that subagent's own tools. Each key is the subagent's path of names from the root agent: `forecaster` for a subagent the root agent declares, and `forecaster/reviewer` for a `reviewer` subagent that `forecaster` declares. Subagents that share a name under different parents get separate entries. Each schema is the form eve sends to the model: schemas from a validation library such as Zod have `additionalProperties: false` on objects that allow no other keys, plain JSON Schema is kept as written, and tools whose calls run as `serve` tasks, including agent tools, include the optional `taskId` input eve adds. ```json { "tools": ["get_weather"], "toolInputSchemas": { "root": { "get_weather": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"], "additionalProperties": false } }, "subagents": { "forecaster": {}, "forecaster/reviewer": { "check_source": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"], "additionalProperties": false } } } } } ``` `toolInputSchemas` covers only tools compiled from tool files. It does not include provider-managed tools such as `web_search`, dynamic tools, connection tools, the tools eve generates at runtime for each subagent and remote agent, or the `eve__task_wait` and `eve__task_cancel` tools. Model providers can also transform a schema before the model reads it; those changes are not reflected here. To compute the same form for an input schema in your own code, such as in a test, call `serializeModelInputSchema(schema)` from `eve/tools`; it returns JSON Schema data and does not add `taskId`. ## `eve build` ```bash eve build [--profile ] [--skip-sandbox-prewarm] ``` Compiles and bundles in an invocation-owned directory under `.eve/builds/`, prepares sandbox artifacts, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure. Pass `--skip-sandbox-prewarm` when you only need compiled output, such as before a separate typecheck. Skipping preparation can produce output that cannot start its configured sandbox, so do not deploy that output. Authored bundles preserve custom Node.js resolution conditions supplied through `--conditions`, `-C`, or `NODE_OPTIONS`. For example, `NODE_OPTIONS="--conditions=react-server" eve build` keeps a channel's `server-only` imports on the same export used during compilation. | Flag | Type | Default | Description | | ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------- | | `--profile ` | string | off | Best-effort versioned JSON report with build-phase timings and final output-size measurements | | `--skip-sandbox-prewarm` | flag | off | Skip sandbox preparation; the output might not be deployable | Use a profile file to establish a repeatable baseline before changing the build pipeline: ```bash eve build --profile .eve/build-profiles/baseline.json ``` The report is attempted only after a successful build. It records total elapsed time, completed phase timings, and final regular-file totals for file count, raw bytes, and the sum of each file compressed with gzip. For Vercel output it also includes a subtotal for every real `.func` directory, so app and flow bundles can be compared separately. The profile path resolves from the app root and should be outside the published output directory; profile collection does not add a file to the deployment. If collection or writing fails, eve emits a warning but keeps the completed build successful. Production builds do not write through the stable compiler, host, Nitro, or Workflow files owned by `eve dev`, so builds can run while a local dev server is active. A failed build leaves the last successful `.output/` and agent summary untouched. Concurrent completed builds serialize only the final publication window. Useful stable artifacts written by inspection and development flows under `.eve/` include: | Artifact | Description | | ---------------------------------------------- | ---------------------------------------------------- | | `.eve/discovery/agent-discovery-manifest.json` | What eve found on disk | | `.eve/discovery/diagnostics.json` | Authored-shape errors and warnings | | `.eve/compile/compiled-agent-manifest.json` | The serialized authored surface eve loads at runtime | | `.eve/compile/compile-metadata.json` | Build-time metadata and paths | | `.eve/compile/module-map.mjs` | Compiled module entrypoints eve imports at runtime | ## `eve start` ```bash eve start [--host ] [--port ] ``` | Flag | Type | Default | Description | | --------------- | ------ | ------------------ | ---------------------- | | `--host ` | string | all interfaces | Host interface to bind | | `--port ` | number | `$PORT`, then 3000 | Port to listen on | Serves the previously built output. Prints the listening URL. For self-hosted deployments, copy the app source, `.output/`, and installed dependencies together. The deployment directory can differ from the build directory. Preserve the relative layout of any workspace packages used by the app; startup resolves sandbox prewarm modules from the deployed source. ## `eve dev` ```bash eve dev [options] ``` Starts a local development server and terminal UI. To connect the UI to an existing agent, use `eve remote connect --url `. | Flag | Type | Default | Description | | ----------------------------------- | ------ | ------------------ | --------------------------------------------------------------- | | `--host ` | string | all interfaces | Host interface to bind | | `--port ` | number | `$PORT`, then 2000 | Port to listen on | | `--no-ui` | flag | UI on | Start the server without an interactive UI | | `--resume` | flag | off | Attempt recovery of retained runs from previous dev invocations | | `--no-default-extensions` | flag | extensions on | Do not mount bundled development extensions | | `--name ` | string | app folder name | Title shown in the terminal UI | | `--input ` | string | none | Pre-fill the prompt input | | `--tools ` | enum | `auto-collapsed` | Tool-call rendering | | `--reasoning ` | enum | `full` | Reasoning rendering | | `--subagents ` | enum | `collapsed` | Subagent task rendering: `full`, `collapsed`, or `hidden` | | `--connection-auth ` | enum | `full` | Connection-authorization rendering | | `--assistant-response-stats ` | enum | `tokensPerSecond` | Assistant header statistic | | `--context-size ` | number | none | Model context window size | | `--logs ` | enum | `error` | Display `none`, `error`, `warn`, `debug`, or `all` logs | Local development mounts bundled development extensions without adding files to your project. Pass `--no-default-extensions` to disable them. See [Self-Modification](../guides/self-modification) for details. A fresh `eve init` opens the TUI and reuses an available model connection or opens `/login`. No Vercel project, channels, integrations, or review step is required before chat. Use `/model` to change models and settings, and `/add` to install an addition. Other `--input` text stays editable in the prompt. See [Terminal UI](../guides/dev-tui) for credential precedence and login options. ### Local development lifecycle Local dev records the last ready URL per resolved app root in `.eve/dev-server-state.v1.json`. A second interactive `eve dev` reconnects only when that URL is loopback and healthy; each terminal UI creates a fresh client session while sharing the server process. A stale or malformed record is replaced when eve starts a new server. Passing `--host`, `--port`, or a `PORT` environment value skips reconnection and reports a healthy recorded server instead. Local dev keeps immutable runtime generations under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. Each generation contains the compiled authored module graph and runtime resources rather than a recursive copy of the app or workspace. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; `/new` terminally retires that session before clearing the transcript, and the next prompt starts a fresh session with a new session-scoped sandbox on first sandbox use. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned. Local development records traces under `.eve/traces/` by default and bounds that store by age, size, and a keep-newest floor. Configure it with `EVE_TRACES*` in `.env.local`, or disable the destination with `agent/instrumentation/local.ts`; see [`eve traces`](#retention) for the rules and defaults. `eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API. See [Agent Client Protocol (ACP)](../protocols/acp) for client configuration and capability limits. ### Local workflow recovery With the built-in local Workflow World, a new `eve dev` server leaves previous invocations' runs dormant by default, including deliveries triggered by timers or hooks. A new message or control request addressed to a dormant conversation fails instead of being accepted without a response; the HTTP channel reports its usual request failure. Start a new conversation, or restart `eve dev` with `--resume` to attempt recovery. Already-open event streams are not changed by this request guard. Source-watcher rebuilds and worker restarts within the same server retain current runs' eligibility. Pass `eve dev --resume` to attempt recovery of unfinished runs from previous invocations. Recovery requires a retained snapshot with readable generation metadata. Snapshots from older eve versions with a valid `runtimeAppRoot` remain eligible. Changes to the eve framework or authored workflow sources do not prevent the attempt, but replay can fail and leave the run terminally failed after executing some work. Use `--resume` only when you want to try continuing those previous runs. Runs with malformed generation metadata remain stored and dormant for that server invocation, including later timer and hook deliveries. Startup with `--resume` reports why recovery was skipped without blocking other eligible runs. Restore malformed snapshot metadata from a backup or start a new session. Recovery eligibility is decided before startup queue delivery begins. Hot reload does not recheck admitted runs against the latest workflow sources, so follow-up turns, cancellation, and `/new` retain their existing behavior. Changing an authored workflow body while it is running can likewise cause replay failure. With the built-in local Workflow World, `eve dev` cancels unfinished runs whose runtime snapshots are missing, at startup and after snapshot pruning. This includes waiting conversations and session timeout workflows. Cancellation records the reason in the run history without a terminal warning; normal run-data retention still applies. Stopping `eve dev` does not cancel runs whose snapshots remain available, but recovering them on the next start requires `--resume`. Recovery limits: - Custom Workflow Worlds do not use this cleanup and recovery policy; `eve dev --resume` rejects them. - `eve dev --resume` refuses to attach to an already running local server. The flag requires starting a server. - `eve dev --resume` recovers workflows, not the terminal transcript or a particular TUI conversation. ## `eve remote` Use `eve remote` only with an explicit existing agent URL: ```bash eve remote connect --url https://agent.example.com eve remote invoke --url https://agent.example.com "Summarize station telemetry" eve remote info --url https://agent.example.com ``` `connect` opens the terminal UI. `info` verifies the target and prints its inspection response. Remote commands never start a local application. ### `eve remote connect` ```bash eve remote connect --url [-H "Name: value"] ``` Use `-H, --header
` for a bearer token or another custom request header; repeat it for multiple headers. For HTTP Basic authentication, put credentials in the URL. eve sends them as a Basic `Authorization` header and removes them from the target URL. ### `eve remote invoke` ```bash eve remote invoke --url [prompt] [--resume] [-H "Name: value"] [--scope ] ``` Invokes an existing agent without opening the terminal UI. It emits JSON after the invocation completes or reaches a blocking input or authorization event. | Option | Type | Default | Description | | ----------------------- | ------ | -------- | ----------------------------------------------- | | `` | string | required | Existing eve agent URL | | `[prompt]` | string | none | Prompt, follow-up, or answer to a pending input | | `-H, --header
` | string | none | Request header for the URL target; repeatable | | `--resume` | flag | off | Read a previous resumable result from stdin | | `--scope ` | string | current | Vercel team that owns the URL target | `--resume` reads a complete previous result from stdin. Supply text for a `ready` follow-up or pending input. An `authorization-required` result lists every unresolved challenge; complete them, then resume without text. Pass headers and scope again when resuming. Paused invocations exit `3`; failures exit `1`. If a waiting invocation receives `SIGINT` or `SIGTERM` after acceptance, it emits a final resumable `running` result before exiting. ### `eve remote info` ```bash eve remote info --url [-H "Name: value"] [--json] ``` Verifies the existing agent and prints its inspection response. Use `-H, --header
` for protected targets; repeat it for multiple headers. ## `eve logs` ```bash eve logs # print the most recent diagnostic log eve logs list # list logs, most recent first eve logs show # print a specific log eve logs --dump # prepend the log's environment dump eve logs --events # interleave session events from the local workflow store ``` Each interactive `eve dev` process writes a private diagnostic log under `.eve/logs/` capturing stderr, stdout (including sandbox and rebuild lines), tool failures, workflow errors, and eve framework log records — regardless of what the transcript shows. The file is JSON Lines — every line is one JSON record with `at` and `source` fields. `eve logs` reads those files back. A log id is the file name without `.log` (for example `dev-2026-07-15T12-00-00.000Z-123`). `eve logs show ` also accepts the file name, the `.eve/logs/...` path printed in the dev transcript, or any unambiguous prefix of the id with or without the `dev-` lead — so `eve logs 2026-07-15` works when a single log matches. An ambiguous prefix fails and lists the candidates. `eve logs` prints nothing but records — no path banner on either stream — so `eve logs 2>&1 | jq -c .` always parses. Discover ids and file paths with `eve logs list`; `eve logs list --json` emits a machine-readable array with `id`, `path`, `startedAt`, and `sizeBytes`. `eve logs --events` resolves session events (`session.started`, `turn.failed`, message deltas, …) from the local workflow store (`.eve/.workflow-data`) at query time and interleaves them into the output by timestamp as `source: "event"` records — the log file itself never stores them, so nothing is duplicated at capture time. Selection is by the log's time window (its start through the next log's start), so events from concurrently running `eve dev` processes may appear. 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 traces` ```bash eve traces list # list traces, most recent first eve traces list --json # emit machine-readable trace summaries eve traces show # show the most recent span tree eve traces show # show one span tree eve traces --verbose # expand every span with all attributes and events eve traces --json # dump the full trace as JSON ``` Reads the immutable OTLP/JSON segments under `.eve/traces/v1`, so `eve dev` need not be running. Accepts a full trace id, a `gen_ai.conversation.id`, or an unambiguous prefix of either. Malformed segments are skipped without hiding valid spans from the same trace. Span rows carry inline metrics when the span recorded them — `↑input`/`↓output` token counts, gateway cost, and the tool name for `execute_tool` spans. The header lists models across the trace, sums token usage and cost from step spans, and counts all error-bearing spans. `--verbose` expands each span under its tree row: status (with the error message on failures), timing, ids, every attribute (prompts, responses, and tool payloads as transcripts or pretty-printed JSON), and every span event with its offset from span start. `--json` prints the same records as JSON, one object per selected trace. With local caller trace context, the first local subagent turn uses the caller's trace. Its span is a child of the dispatch span. A remote child starts a separate root trace and links its first turn to the dispatch with `eve.link.type=agent.dispatch`. Remote requests use W3C `tracestate` to identify that dispatch span if platform HTTP handling changes `traceparent`. Later child turns start new traces. All related sessions have the same `gen_ai.conversation.id`. `agent.subagent.name` identifies the subagent. Each workflow tool call has one `execute_tool ` span. The first turn of each local session it opens with `ctx.agent` is a child of that tool span. A remote session links to the tool span from its own trace. An individual `ctx.agent` call does not create a separate dispatch span. Only agent execution uses `invoke_agent`. Outbound MCP `tools/call` requests add MCP semantic attributes to the matching `execute_tool` span. When eve has no tool span to enrich, it creates a `CLIENT` `tools/call ` span. Each `tools/list` discovery also has a `CLIENT` span. Configured OpenTelemetry propagation fields are injected into MCP `params._meta` for JSON-RPC bodies up to 1 MiB and propagation metadata up to 8 KiB; larger requests are sent unchanged. eve removes its audience and session-lineage baggage before forwarding, and keeps the input/output content-capture policy local. A call the model makes through `eve__tool` or `eve__skill` is traced exactly like a direct call to the entry it names: its `execute_tool` span carries that entry's name and input, such as `execute_tool linear__list_issues`, and a workflow tool or agent reached this way gets the same span its direct call would. A skill load has an `execute_tool eve:load-skill` span. The AI SDK's own tracing channel, which eve does not filter, still reports the `eve__tool` or `eve__skill` tool running for each such call. Each root agent turn starts a new trace. With local caller trace context, that trace includes the first turn of each local subagent it starts. Remote child turns and later local child turns start separate traces. If a worker is replaced, the new worker uses the prepared trace context for the same turn. Supply the conversation ID to show all related traces, oldest first. Every span carries a real duration. A turn's root `invoke_agent` span is written when the turn settles, so a running turn shows only its steps. Model, `execute_tool`, and memory spans retain their content by default. Set `EVE_TRACES_CONTENT=off` to omit system prompts, prompt messages, and response text for models; call arguments and results for tools; and recalled memory records. Each captured value is capped at 32 KB. Step spans carry token counts under `agent.usage.*`, and cost when Vercel AI Gateway served the call. Model spans also expose `gen_ai.usage.*` token counters. The CLI sums step-level counters only, so model and delegated-call totals are not counted twice. ### Retention eve sweeps the store when an activation's writes finish, when a session finishes, and when the dev server starts. An open conversation does not pin every completed turn's trace. Sweeps evict oldest-first past the bounds below, except that active traces, the newest traces, and anything written in the last five minutes are kept. A sweep can therefore exceed the size budget. Set the bounds in `.env.local`, which `eve dev` loads automatically; each accepts `off` to disable it individually. | Variable | Default | Effect | | ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- | | `EVE_TRACES` | on | `off` stops writing traces and stops sweeping | | `EVE_TRACES_CONTENT` | on | `off` omits model prompt/response, tool input/output, and memory-record attributes on local spans | | `EVE_TRACES_MAX_AGE_MS` | `604800000` (7d) | Age after which a trace may be evicted | | `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store | | `EVE_TRACES_RETAIN_COUNT` | `20` | Newest traces kept regardless of age or size | ## `eve link` ```bash eve link eve link --non-interactive --project [--team ] ``` Links the current directory to a Vercel project. After selecting a team, you can create a project named for the agent or link an existing project. The existing-project picker shows recent projects; type a project name and choose **Search for `''`** to search the rest of that team's projects. Vercel links the resolved project, eve verifies its project ID, and then pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`. Running it again re-links: the pickers always run, and the new choice wins. For CI or an agent, pass `--non-interactive` and `--project`. `--project` accepts the same Vercel project name or ID as `vercel link`; `--team` accepts its team ID or slug. The command never opens a picker or browser in this mode. A running `eve dev` reloads env files automatically, so you don't need to restart after the pull. ## `eve deploy` ```bash eve deploy eve deploy --non-interactive --yes [--project ] [--team ] ``` Deploys the agent to Vercel production (`vercel deploy --prod`), installing dependencies first and pulling environment variables after. An already-linked project deploys with or without a TTY. When a terminal is present, an unlinked deployment signs in to Vercel if needed and then walks the `eve link` pickers. For CI or an agent, pass `--non-interactive --yes`. `--yes` explicitly confirms the production deployment. With `--project`, eve links that Vercel project and pulls its environment before deploying; `--team` has the same ID-or-slug semantics as `eve link`. Without `--project`, the directory must already be linked. The non-interactive mode never opens a picker, browser, or login flow. ## `eve eval` ```bash eve eval [evalId...] [--url ] [options] ``` Runs all discovered evals when no eval ids are given; ids match exactly or by directory prefix (`eve eval weather` runs everything under `evals/weather/`). Exits `0` when every eval passed its checks, `1` when any eval failed (a failed check, an execution error, or a `--strict` threshold miss), `2` on configuration errors. | Flag | Type | Default | Description | | ------------------------ | ------ | ------- | ------------------------------------------------------------- | | `--url ` | string | none | Remote agent URL (skip local host startup) | | `--tag ` | string | none | Run only evals carrying a tag | | `--exclude-tag ` | string | none | Skip evals carrying a tag | | `--strict` | flag | off | Below-threshold scores also fail the exit code | | `--list` | flag | off | Print evals selected by the tag filters, without running them | | `--timeout ` | number | none | Per-eval timeout in milliseconds | | `--max-concurrency ` | number | 8 | Max concurrent eval executions | | `--json` | flag | off | Output results as JSON | | `--junit ` | string | none | Write JUnit XML results to a file | | `--skip-report` | flag | off | Skip eval-defined reporters (e.g. Braintrust) | | `--verbose` | flag | off | Stream per-eval logs and workflow run IDs to stdout | See [Evals](../evals/overview) for authoring evals. ## Recommended loop 1. Edit files under `agent/`. 2. `eve info` to confirm discovery or read diagnostics. 3. `eve dev` while iterating locally. 4. `eve build` before shipping. 5. `eve start` to smoke-test the built output locally. Related: [Agent Files](/docs/reference/agent-files) · [Instrumentation](../observability/instrumentation). ## What to read next - [Agent Files](/docs/reference/agent-files): what `eve info` discovers - [Instrumentation](../observability/instrumentation): tracing and the error catalog - [Deployment](../guides/deployment/overview): `eve build` and `eve start` in production