The Open Framework for Building Agents
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 <url> |
Open the terminal UI for an existing agent |
eve remote invoke --url <url> [prompt] |
Invoke an existing agent without a terminal UI |
eve remote info --url <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 <effort>] |
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 <command> |
Install and browse registry items |
eve extension <command> |
Create and build extension packages |
eve telemetry <command> |
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 for the current data fields, exclusions, debug mode, notice, and local preference storage.
eve init
eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--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 <model> |
string | openai/gpt-6-luna-fast |
Set the root agent's AI Gateway model ID. |
--reasoning <effort> |
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 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
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 for authoring and mount details.
eve extension build
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:
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 items. Official registry items use a kind and slug (for example, extension/agent-browser); URLs and configured registry addresses are also supported.
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 <item> --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=<JSON value>' 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 <item> --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, 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 <count> 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
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.
{
"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
eve build [--profile <path>] [--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, so compilation and the bundle resolve each package to the same export.
For example, NODE_OPTIONS="--conditions=react-server" eve build selects the react-server
export of packages that publish one.
eve loads server-only and client-only imports as empty modules in every bundle it builds. Code
shared with a Next.js app can keep these imports without a resolution condition, and your app does
not need to depend on either package.
| Flag | Type | Default | Description |
|---|---|---|---|
--profile <path> |
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:
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. For self-hosted output it includes deploymentId, the content-derived build identity eve passes to the Workflow World as WORKFLOW_DEPLOYMENT_ID when that variable isn't already set. 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
eve start [--host <host>] [--port <port>] [--no-schedules]
| Flag | Type | Default | Description |
|---|---|---|---|
--host <host> |
string | all interfaces | Host interface to bind |
--port <port> |
number | $PORT, then 3000 |
Port to listen on |
--no-schedules |
flag | schedules on | Start without running authored cron schedules |
Serves the previously built output. Prints the listening URL, and a schedules disabled line when --no-schedules or EVE_SCHEDULES_DISABLED turns schedules off. HTTP requests and workflow jobs continue to run.
Set EVE_SCHEDULES_DISABLED=1 or true (case-insensitive) to disable authored cron schedules at runtime, including when you run node .output/server/index.mjs directly. Unset, empty, and other values leave schedules enabled. --no-schedules sets the variable to 1 only for the spawned server; omitting the flag preserves any value you already set. The same build can run with schedules enabled or disabled.
Use this setting when scaling self-hosted replicas. It also disables authored cron dispatch on Vercel if set there, but does not affect explicit schedule dispatch in eve dev.
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
eve dev [options]
Starts a local development server and terminal UI. To connect the UI to an existing agent, use eve remote connect --url <url>.
| Flag | Type | Default | Description |
|---|---|---|---|
--host <host> |
string | all interfaces | Host interface to bind |
--port <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 <name> |
string | app folder name | Title shown in the terminal UI |
--input <text> |
string | none | Pre-fill the prompt input |
--tools <mode> |
enum | auto-collapsed |
Tool-call rendering |
--reasoning <mode> |
enum | full |
Reasoning rendering |
--subagents <mode> |
enum | collapsed |
Subagent task rendering: full, collapsed, or hidden |
--connection-auth <mode> |
enum | full |
Connection-authorization rendering |
--assistant-response-stats <mode> |
enum | tokensPerSecond |
Assistant header statistic |
--context-size <tokens> |
number | none | Model context window size |
--logs <mode> |
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 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 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 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) 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 --resumerejects them. eve dev --resumerefuses to attach to an already running local server. The flag requires starting a server.eve dev --resumerecovers workflows, not the terminal transcript or a particular TUI conversation.
eve remote
Use eve remote only with an explicit existing agent URL:
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
eve remote connect --url <url> [-H "Name: value"]
Use -H, --header <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
eve remote invoke --url <url> [prompt] [--resume] [-H "Name: value"] [--scope <team>]
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 |
|---|---|---|---|
<url> |
string | required | Existing eve agent URL |
[prompt] |
string | none | Prompt, follow-up, or answer to a pending input |
-H, --header <header> |
string | none | Request header for the URL target; repeatable |
--resume |
flag | off | Read a previous resumable result from stdin |
--scope <team> |
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
eve remote info --url <url> [-H "Name: value"] [--json]
Verifies the existing agent and prints its inspection response. Use -H, --header <header> for protected targets; repeat it for multiple headers.
eve logs
eve logs # print the most recent diagnostic log
eve logs list # list logs, most recent first
eve logs show <logid> # 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 <logid> 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
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 <trace> # 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 <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 <tool> 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. When a model call's prompt messages exceed the cap, the oldest are dropped first and agent.input.messages.omitted records how many.
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
eve link
eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>]
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 '<name>' 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
eve deploy
eve deploy --non-interactive --yes [--project <name-or-id>] [--team <team-id-or-slug>]
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
eve eval [evalId...] [--url <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.
Without --url, eve eval starts its own local server on a free port with state under .eve/eval-servers/<run id>/, removed when the run ends. It runs beside an eve dev session for the same agent without attaching to it or changing it.
| Flag | Type | Default | Description |
|---|---|---|---|
--url <url> |
string | none | Remote agent URL (skip local host startup) |
--tag <tag...> |
string | none | Run only evals carrying a tag |
--exclude-tag <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 <ms> |
number | none | Per-eval timeout in milliseconds |
--max-concurrency <n> |
number | 8 | Max concurrent eval executions |
--json |
flag | off | Output results as JSON |
--junit <path> |
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 for authoring evals.
Recommended loop
- Edit files under
agent/. eve infoto confirm discovery or read diagnostics.eve devwhile iterating locally.eve buildbefore shipping.eve startto smoke-test the built output locally.
Related: Agent Files · Instrumentation.
What to read next
- Agent Files: what
eve infodiscovers - Instrumentation: tracing and the error catalog
- Deployment:
eve buildandeve startin production