CLI

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

When eve build fails on discovery errors, it prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path.

eve init

eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]

Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git.

Coding-agent launches and non-interactive terminals cannot answer the location prompt and fail before writing. Pass a new directory name, such as eve init my-agent, in those environments.

After scaffolding, a human terminal usually continues into eve dev. If a coding-agent REPL is on PATH, the handoff menu can open it instead or exit without starting either process. Coding-agent launches print the next steps instead of opening the TUI, so the session does not get stuck. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched eve init.

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.

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-5.6-sol \
  --reasoning high

Pass either flag by itself to change one setting. When you pass 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 flag 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 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. Product-level packages can offer independently installable components: eve add linear lets you select the Linear Channel, Linear MCP, or both, with both selected by default. Interactive Vercel-backed setup signs in and creates or links a project when needed instead of stopping with a prerequisite. --yes installs a package's default components and 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 component or 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 selected components' 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]

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.

eve build

eve build [--profile <path>] [--skip-sandbox-prewarm]

Compiles and bundles in an invocation-owned directory under .eve/builds/, then publishes the completed host output and prints its path. Scratch workspaces are removed after success or failure.

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. 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:

eve start

eve start [--host <host>] [--port <port>]

Serves the previously built output. Prints the listening URL.

eve dev

eve dev [options]
eve dev https://your-app.vercel.app

Pass a bare URL and the UI connects to that server instead of booting a local one (same as --url), which lets you smoke-test a preview or production deployment. The interactive UI turns off in a non-TTY terminal.

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 and accepts the same URL credentials and request headers as eve dev <url>. Pass --scope <team> when the active Vercel scope does not own the deployment; EVE_VERCEL_SCOPE provides the same value for managed harnesses. See Agent Client Protocol (ACP) for client configuration and capability limits.

A fresh eve init passes --input /model. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, opens /model, then offers categorized registry next steps before the first prompt. Other input stays editable in the prompt.

For a URL target protected by HTTP Basic auth, put the credentials in the URL. eve sends them as a Basic Authorization header and strips them from the server URL before connecting:

eve dev https://user:pass@your-app.example.com

For bearer tokens or custom schemes, pass explicit headers with -H.

eve invoke

Use eve invoke to submit a turn without opening the TUI. It emits JSON after the invocation completes or reaches a blocking input or authorization event.

eve invoke "Summarize station telemetry"
result=$(eve invoke "Deploy the application")
printf '%s' "$result" | eve invoke --resume "approve"
eve invoke --json-schema

--resume reads a complete previous result from stdin. Supply text for a ready follow-up or pending input; the agent harness resolves input text against all pending requests. A ready result includes the previous turn's completed or failed outcome. An authorization-required result lists every unresolved challenge in authorizations; complete them, then resume without text. Pass explicit headers again for protected remote servers. If the URL belongs to another Vercel team, pass its slug with --scope; this does not relink the current directory. Pass the scope again when resuming. Paused invocations exit 3; failures exit 1.

Local callback-based connection authorization requires a persistent server. Run eve dev, then use eve invoke --url <dev-url> instead. If a waiting invocation receives SIGINT or SIGTERM after acceptance, it emits a final resumable running result before exiting.

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 source snapshots under .eve/dev-runtime/snapshots/ so in-flight turns hold a consistent code revision while new turns pick up rebuilds. 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.

When no authored agent/instrumentation.ts exists, local dev also records traces under .eve/traces/, and bounds that store by age, size, and a keep-newest floor. Configure it with EVE_TRACES* in .env.local; see eve traces for the rules and defaults.

eve logs

eve logs            # print the most recent diagnostic log
eve logs ls         # list logs, most recent first
eve logs <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 <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 ls; eve logs ls --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 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 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, an agent.session.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 ai.toolCall spans — and the header aggregates models, token totals, cost, and error count across the trace's step 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.

A subagent keeps its own session id but records into the trace its parent had open at dispatch, so delegated work appears under the session that caused it, tagged with agent.root.session.id. Either session id resolves to that trace. A remote agent traces under its own deployment and is not recorded here.

A session long enough to outgrow one trace — far longer than anything you will drive locally — continues into a new one. Each is a session window, numbered from zero on agent.session.window; passing a session id shows every window it produced, oldest first, and a trace id shows just that window.

One parent turn can dispatch several subagents into the same window, so a child's turn spans name the dispatch: agent.parent.session.id, agent.parent.turn.id, and agent.parent.call_id identify the tool call that created the child, and agent.subagent.name the subagent it invoked. Top-level sessions carry none of these.

Every span carries a real duration except agent.session: an idle session never closes, so it is recorded as a zero-duration marker and the span tree shows its descendant extent instead. A turn's span is written when the turn settles, so a running turn shows only its steps.

Model and tool-call spans omit their inputs and outputs by default. Set EVE_TRACES_CONTENT=on to capture system prompts, prompt messages, and response text for models, plus call arguments and results for tools. Each captured value is capped at 32 KB.

Step spans carry token counts, and cost when Vercel AI Gateway served the call. Both follow the OTel GenAI semantic conventions (gen_ai.usage.*), so a third-party backend reads them without mapping.

Retention

eve sweeps the store when a session finishes and when the dev server starts, evicting oldest-first past the bounds below — except that the newest traces and anything written in the last five minutes are always kept, so a sweep will exceed the size budget rather than drop a trace you just recorded. Set the bounds in .env.local, which eve dev loads automatically; each accepts off to disable it individually.

eve link

eve link

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. The command is interactive only; in CI, use vercel link --project <name> --yes --non-interactive instead. A running eve dev reloads env files automatically, so you don't need to restart after the pull.

eve deploy

eve deploy

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 (non-interactive runs pass the non-interactive vercel flags). When a terminal is present, an unlinked deployment signs in to Vercel if needed and then walks the eve link pickers; otherwise, it exits with guidance.

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.

See Evals for authoring evals.

eve channels list

eve channels list [--json]

Lists the user-authored channels in the current project.

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: Project layout · instrumentation.ts.

What to read next

• Project layout: what eve info discovers
• instrumentation.ts: tracing and the error catalog
• Deployment: eve build and eve start in production