# CLI reference

> All eve commands (init, info, build, start, dev, link, deploy, eval, channels), flags, exit codes, .eve/ artifact paths, and the recommended edit-info-dev-build-start loop.

- Repository: vercel/eve
- GitHub: https://github.com/vercel/eve
- Human docs: https://grok-wiki.com/public/docs/vercel-eve-759e1d74a10f
- Complete Markdown: https://grok-wiki.com/public/docs/vercel-eve-759e1d74a10f/llms-full.txt

## Source Files

- `docs/reference/cli.md`
- `packages/eve/src/cli/run.ts`
- `packages/eve/src/cli/commands/register-project-commands.ts`
- `packages/eve/src/cli/commands/init.ts`
- `packages/eve/src/cli/commands/info.ts`
- `packages/eve/src/evals/cli/eval.ts`

---

---
title: "CLI reference"
description: "All eve commands (init, info, build, start, dev, link, deploy, eval, channels), flags, exit codes, .eve/ artifact paths, and the recommended edit-info-dev-build-start loop."
---

The `eve` binary (`packages/eve/bin/eve.js`) resolves the application root from the current working directory and registers commands through Commander. Invoking `eve` with no subcommand runs `eve dev`. Commands that start servers or run evals load development environment files from the app root before executing.

## Command summary

| Command | Description |
| --- | --- |
| `eve init [target]` | Scaffold a new agent, or add one to an existing project directory |
| `eve info` | Print resolved application paths, discovered surface, messaging routes, and artifact locations |
| `eve build` | Compile `.eve/` artifacts and build host output; prints the output directory |
| `eve start` | Serve the built `.output/` app; prints the listening URL |
| `eve dev` | Start the local dev server and open the terminal UI |
| `eve dev <url>` | Connect the UI to an existing server URL instead of booting locally |
| `eve link` | Link the directory to a Vercel project and pull AI Gateway credentials |
| `eve deploy` | Deploy the agent to Vercel production (links first when needed) |
| `eve eval` | Run evals against the local app or a remote target |
| `eve channels add [kind]` | Scaffold a channel interactively, or by kind (`slack` \| `web`) |
| `eve channels list` | List user-authored channels |

Global flags apply to the root program:

| Flag | Description |
| --- | --- |
| `-V, --version` | Print the installed `eve` package version |
| `-h, --help` | Print command help |

## Environment loading

`eve build`, `eve start`, `eve dev`, and `eve eval` load development environment files from the app root. Files are merged in this order (later files override earlier ones; parent-process variables set before the first load keep precedence):

1. `.env`
2. `.env.development`
3. `.env.local`
4. `.env.development.local`

`eve info`, `eve init`, `eve link`, `eve deploy`, and `eve channels` do not load these files at the command handler. The dev and production servers reload env files when their watchers detect changes.

## Exit codes

| Code | When |
| --- | --- |
| `0` | Command completed successfully; help requested (`--help`); `eve eval` when every eval passed |
| `1` | Runtime or validation error; agent-scoped command run outside an Eve project; `eve link`/`eve deploy`/`eve channels` failure; `eve eval` when any eval failed or `--strict` threshold miss |
| `2` | `eve eval` configuration errors (no evals discovered, no evals matching filters, invalid numeric flags) |

Uncaught errors in the top-level binary set `process.exitCode = 1`. `eve eval` calls `process.exit()` with the resolved code after the run completes.

<Warning>
Agent-scoped commands (`eve link`, `eve deploy`, `eve channels add`, `eve channels list`) exit `1` with this message when the working directory has no Eve agent:

`No Eve agent in this directory. Run eve init <name>, then run this command from inside the new project.`
</Warning>

## `.eve/` artifact paths

Compiler-owned artifacts are written under `.eve/` during discovery and compile. They are preserved even on partial failure so diagnostics remain inspectable.

:::files
.eve/
├── discovery/
│   ├── agent-discovery-manifest.json   # What Eve found on disk
│   └── diagnostics.json              # Authored-shape errors and warnings
├── compile/
│   ├── compiled-agent-manifest.json  # Serialized surface the runtime loads
│   ├── compile-metadata.json         # Build metadata, status, and digests
│   ├── module-map.mjs                # Compiled module entrypoints
│   ├── channel-instrumentation.d.ts  # Channel instrumentation types
│   └── workspace-resources/          # Materialized workspace skill resources
├── dev-process.pid                   # Active `eve dev` process (local dev only)
├── dev-runtime/
│   ├── current.json                  # Pointer to active runtime snapshot
│   └── snapshots/                    # Immutable dev runtime source snapshots
├── evals/
│   └── <timestamp>/                  # Per-run eval artifacts (summary, results)
├── nitro/                            # Nitro build cache (dev and build)
├── nitro-output/                     # Staged Nitro surface output (Vercel builds)
├── sandbox-cache/                    # Local sandbox templates and snapshots
├── agent-summary.json                # Vercel build agent summary
└── bootstrap.mjs                     # Compiled artifacts bootstrap
:::

Production host output lands outside `.eve/`:

| Path | When |
| --- | --- |
| `.output/` | Local `eve build` / `eve start` |
| `.vercel/output/` | Builds running with `VERCEL` set |

`eve info` prints artifact paths, workflow build directory, output directory, and the active messaging route contract.

## Recommended loop

<Steps>
<Step title="Edit agent files">
Change instructions, skills, tools, connections, channels, or `agent/agent.ts` under `agent/`.
</Step>
<Step title="Verify discovery">
Run `eve info` to confirm files were discovered and read diagnostics before starting a server.
</Step>
<Step title="Iterate locally">
Run `eve dev` for watch-mode rebuilds, sandbox prewarm, and the terminal UI.
</Step>
<Step title="Build for shipping">
Run `eve build` to compile `.eve/` artifacts and produce host output.
</Step>
<Step title="Smoke-test production output">
Run `eve start` against the built `.output/` directory before deploying.
</Step>
</Steps>

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

## `eve init`

```bash
eve init [target] [--channel-web-nextjs]
```

Creates a new Eve agent or adds one to an existing project. No prompts; dependencies install automatically.

**Target modes**

| Target | Behavior |
| --- | --- |
| `my-agent` (name) | Scaffold a fresh project in `my-agent/` |
| `.` or existing directory | Add an agent to that project (`package.json` required; `agent/` must not exist) |
| Omitted | Same as `eve init .` |

Either mode installs dependencies, initializes Git for fresh scaffolds, and runs `eve dev` through the project's package manager. When launched by a coding agent, init prints the dev command instead of spawning the TUI.

<ParamField body="--channel-web-nextjs" type="flag">
Add the Web Chat application (Next.js). Rejected when adding to an existing project; run `eve channels add web` afterward.
</ParamField>

## `eve info`

```bash
eve info [--json]
```

Prints resolved application paths, compile status, discovery summary, artifact locations, and messaging routes (`POST` create/continue, `GET` stream). Run this first when discovery or routing behaves unexpectedly.

<ParamField body="--json" type="flag">
Emit the stable machine-readable contract: `appRoot`, `agentRoot`, `layout`, `status`, `diagnostics`, `model`, `instructions`, `skills`, `tools`, `channels`, `messaging`, and `artifacts`.
</ParamField>

## `eve build`

```bash
eve build
```

No flags. Compiles discovery and compile artifacts under `.eve/`, builds Nitro host output, and prints `built output at <path>`. On Vercel (`VERCEL` set), also runs sandbox prewarm, emits workflow functions, and writes `.vercel/output/`.

## `eve start`

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

Serves the previously built `.output/server/index.mjs`. Loads development env files, prewarms built-app sandboxes, polls `/eve/v1/health`, and blocks until SIGINT/SIGTERM or the server exits. Prints `server listening at <url>`.

<ParamField body="--host" type="string">
Host interface to bind. Defaults to `0.0.0.0`.
</ParamField>

<ParamField body="--port" type="number">
Port to listen on. Defaults to `$PORT`, then `3000`.
</ParamField>

## `eve dev`

```bash
eve dev [options]
eve dev https://your-app.example.com
```

Starts the development Nitro server with authored-source watching, runtime snapshot staging, and optional terminal UI. Pass a bare URL as the only argument (equivalent to `--url`) to connect the UI to a remote deployment.

<Note>
Default bind address is `127.0.0.1` and default port is `$PORT` then `2000`. The interactive UI is disabled on non-TTY terminals (`--no-ui` or piped stdout).
</Note>

Local dev writes the active server PID to `.eve/dev-process.pid`. Starting a second `eve dev` while that process is running exits with the PID and a `kill` command. Runtime snapshots live under `.eve/dev-runtime/snapshots/` so in-flight sessions keep a consistent code revision while new prompts pick up rebuilds.

<ParamField body="--host" type="string">
Host interface to bind. Cannot be used with `--url`.
</ParamField>

<ParamField body="--port" type="number">
Port to listen on. Cannot be used with `--url`. Defaults to `$PORT`, then `2000`. When omitted, Eve retries on port conflicts.
</ParamField>

<ParamField body="-u, --url" type="string">
Connect the terminal UI to an existing server URL instead of starting one. Cannot combine with `--host`, `--port`, or `--no-ui`.
</ParamField>

<ParamField body="--no-ui" type="flag">
Start the server without the interactive UI. Headless mode prints `server listening at <url>`.
</ParamField>

<ParamField body="--name" type="string">
Title shown in the terminal UI. Defaults to the app folder name (or remote host for `--url`).
</ParamField>

<ParamField body="--input" type="string">
Pre-fill the prompt input after launching the UI. Requires the interactive UI.
</ParamField>

<ParamField body="--tools" type="enum">
Tool-call rendering: `full` | `collapsed` | `auto-collapsed` | `hidden`. Default: `auto-collapsed`.
</ParamField>

<ParamField body="--reasoning" type="enum">
Reasoning rendering: `full` | `collapsed` | `auto-collapsed` | `hidden`. Default: `full`.
</ParamField>

<ParamField body="--subagents" type="enum">
Subagent-section rendering: `full` | `collapsed` | `auto-collapsed` | `hidden`. Default: `auto-collapsed`.
</ParamField>

<ParamField body="--connection-auth" type="enum">
Connection-authorization rendering: `full` | `collapsed` | `auto-collapsed` | `hidden`. Default: `full`.
</ParamField>

<ParamField body="--assistant-response-stats" type="enum">
Assistant header statistic: `tokens` | `tokensPerSecond`. Default: `tokensPerSecond`.
</ParamField>

<ParamField body="--context-size" type="number">
Model context window size, shown as a usage percentage in the UI.
</ParamField>

<ParamField body="--logs" type="enum">
Server/agent logs to show: `all` | `stderr` | `sandbox` | `none`. Default: `stderr`.
</ParamField>

<Tip>
For manual cleanup after stopping `eve dev`, delete `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`.
</Tip>

## `eve link`

```bash
eve link
```

Interactive only. Walks Vercel team and project pickers, runs `vercel link`, pulls environment variables, and verifies an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) landed in `.env.local`. Re-linking always runs the pickers; the new choice wins. A running `eve dev` reloads env files automatically.

In CI, use `vercel link --project <name> --yes` instead.

## `eve deploy`

```bash
eve deploy
```

Deploys to Vercel production (`vercel deploy --prod`). Installs dependencies and pulls environment variables. An already-linked project deploys with or without a TTY. An unlinked directory runs the `eve link` pickers when a terminal is present; otherwise exits `1` with guidance to run `eve link` first.

## `eve eval`

```bash
eve eval [evalId...] [--url <url>] [options]
```

Runs all discovered evals when no ids are given. Ids match exactly or by directory prefix (`eve eval weather` runs everything under `evals/weather/`). Eval files use the `*.eval.ts` extension under `evals/`.

Without `--url`, eval starts a local dev server on `127.0.0.1` with port `0` (ephemeral), runs evals, then closes the server.

<ParamField body="--url" type="string">
Remote agent URL. Skips local host startup.
</ParamField>

<ParamField body="--tag" type="string[]">
Run only evals carrying any of the given tags.
</ParamField>

<ParamField body="--strict" type="flag">
Below-threshold scores also fail the exit code (exit `1`).
</ParamField>

<ParamField body="--list" type="flag">
Print discovered evals without running them.
</ParamField>

<ParamField body="--timeout" type="number">
Per-eval timeout in milliseconds (non-negative integer).
</ParamField>

<ParamField body="--max-concurrency" type="number">
Max concurrent eval executions (positive integer). Default: `8` when neither flag nor `evals.config.ts` sets it.
</ParamField>

<ParamField body="--json" type="flag">
Output run summary as JSON.
</ParamField>

<ParamField body="--junit" type="string">
Write JUnit XML results to the given file path.
</ParamField>

<ParamField body="--skip-report" type="flag">
Skip eval-defined reporters (for example Braintrust).
</ParamField>

<ParamField body="--verbose" type="flag">
Stream per-eval `t.log` lines to stdout.
</ParamField>

Run artifacts are written under `.eve/evals/<timestamp>/` (`summary.json`, `results.jsonl`, per-eval detail files).

## `eve channels add`

```bash
eve channels add [kind] [-f] [-y]
```

Scaffolds a channel into `agent/channels/`. Known kinds: `slack`, `web`. With no `kind`, prompts interactively (requires a TTY). The flow may link to Vercel, configure services, and deploy when adding channels.

<ParamField body="-f, --force" type="flag">
Overwrite existing channel files.
</ParamField>

<ParamField body="-y, --yes" type="flag">
Assume yes for confirmations. Requires an explicit `kind`.
</ParamField>

## `eve channels list`

```bash
eve channels list [--json]
```

Lists user-authored channel names from the current project.

<ParamField body="--json" type="flag">
Output `{ channels: string[] }` as JSON.
</ParamField>

## Related pages

<CardGroup>
<Card title="Quickstart" href="/quickstart">
Scaffold with `eve init`, verify with `eve info`, iterate with `eve dev`, and create HTTP sessions.
</Card>
<Card title="Project layout" href="/project-layout">
Authored slots under `agent/` and what compiles into `.eve/` artifacts.
</Card>
<Card title="Auth and deployment" href="/auth-and-deployment">
`eve link`/`eve deploy` flows, Vercel output, and production verification.
</Card>
<Card title="Instrumentation and evals" href="/instrumentation-and-evals">
Authoring evals, judges, and `eve eval` reporters.
</Card>
<Card title="Channels" href="/channels">
`defineChannel` authoring and platform channel factories.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Discovery diagnostics, dev server PID conflicts, and common failure modes.
</Card>
</CardGroup>