# Eve CLI reference

> Commands and flags for `eve init`, `info`, `build`, `start`, `dev`, `link`, `deploy`, `eval`, and `channels` subcommands.

- Repository: withastro/flue-with-vercel-eve
- GitHub: https://github.com/withastro/flue
- Human docs: https://grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6
- Complete Markdown: https://grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6/llms-full.txt

## Source Files

- `vercel-eve:docs/reference/cli.md`
- `vercel-eve:README.md`
- `vercel-eve:packages/eve/package.json`
- `vercel-eve:scripts/dev.mjs`
- `vercel-eve:docs/reference/typescript-api.md`
- `vercel-eve:docs/getting-started.mdx`

---

---
title: "Eve CLI reference"
description: "Commands and flags for `eve init`, `info`, `build`, `start`, `dev`, `link`, `deploy`, `eval`, and `channels` subcommands."
---

The `eve` binary ships with the `eve` npm package (`bin: eve`) and runs from your application root — the current working directory. Invoking `eve` with no subcommand runs `eve dev`. Most commands load local environment files before work begins; `eve info` inspects the tree without requiring a running server.

## Command overview

| Command | Description |
| --- | --- |
| `eve init [target]` | Scaffold a new agent, or add one to an existing project |
| `eve info` | Print resolved application details, discovery diagnostics, and artifact paths |
| `eve build` | Compile `.eve/` artifacts and build the Nitro host output |
| `eve start` | Serve the built `.output/` application |
| `eve dev` | Start the local dev server and open the terminal UI |
| `eve dev <url>` | Connect the terminal UI to an existing server URL |
| `eve link` | Link the directory to a Vercel project and pull AI Gateway credentials |
| `eve deploy` | Deploy the agent to Vercel production |
| `eve eval` | Run evals against the local app or a remote target |
| `eve channels add [kind]` | Scaffold a channel (`slack` or `web`) |
| `eve channels list` | List user-authored channels |

## Global behavior

**Application root.** Every command resolves the app root from `process.cwd()`. Run commands from the directory that contains `agent/` and `package.json`.

**Node engine.** The `eve` package requires Node `>=24`.

**Environment files.** `eve dev`, `eve build`, `eve start`, and `eve eval` load development env files from the app root, highest precedence first:

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

Variables already set in the parent process keep precedence on first load. Subsequent reloads (for example after `eve link` updates `.env.local` during `eve dev`) refresh values from these files. A running `eve dev` reloads env files automatically after linking.

**Default subcommand.** An empty argv list is rewritten to `["dev"]` before parsing.

## `eve init`

Scaffolds a new Eve agent or adds agent files to an existing npm project.

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

### Target modes

| Target | Behavior |
| --- | --- |
| `my-agent` (name) | Creates a new subdirectory `my-agent/` with a full scaffold |
| `.` or omitted | Scaffolds in the current directory when empty, or updates it like `eve init .` |
| Existing directory | Adds `agent/` and missing `eve`, `ai`, and `zod` dependencies; requires `package.json` and no existing `agent/` |

Either mode installs dependencies, initializes Git for fresh scaffolds, and hands off to `eve dev` through the detected package manager. When the CLI is launched by a coding agent, it prints the dev command instead of spawning the interactive TUI. Fresh scaffolds pass `--input /model` so the TUI opens the model setup flow.

`eve init` does not create or link a Vercel project.

<ParamField body="--channel-web-nextjs" type="flag">
Add the Web Chat application (a Next.js app) during a fresh scaffold. Rejected when adding to an existing project — run `eve channels add web` there instead.
</ParamField>

## `eve info`

Prints the resolved application: discovered tools, skills, subagents, schedules, channels, HTTP routes, compile status, and artifact paths. Run this first when discovery or routing behaves unexpectedly.

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

<ParamField body="--json" type="flag">
Emit a machine-readable JSON document with `appRoot`, `agentRoot`, `model`, `tools`, `channels`, `messaging` route paths, and `.eve/` artifact locations.
</ParamField>

Human output includes compile status (`ready`, `failed`, or `unavailable`), discovery error and warning counts, and the active session messaging routes (`create`, `continue`, `stream`).

## `eve build`

Compiles authored files under `agent/` into `.eve/` and builds the Nitro host output directory.

```bash
eve build
```

No flags. On success, prints the built output path (typically under `.output/`). On discovery errors, throws with a full diagnostics report listing severity, message, and source path for each item, plus the diagnostics artifact path.

### `.eve/` artifacts

These files are written under `.eve/` and preserved even on partial failure:

| Artifact | Purpose |
| --- | --- |
| `.eve/discovery/agent-discovery-manifest.json` | Filesystem discovery results |
| `.eve/discovery/diagnostics.json` | Authored-shape errors and warnings |
| `.eve/compile/compiled-agent-manifest.json` | Serialized surface the runtime loads |
| `.eve/compile/compile-metadata.json` | Build-time metadata and paths |
| `.eve/compile/module-map.mjs` | Compiled module entrypoints |

## `eve start`

Serves the previously built production output at `.output/server/index.mjs`.

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

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

<ParamField body="--port" type="number" default="$PORT, then 3000">
Port to listen on. Accepts `0` through `65535`.
</ParamField>

Prints the listening URL and blocks until the server exits or receives `SIGINT`/`SIGTERM`. Exits with an error if `.output/` is missing — run `eve build` first.

## `eve dev`

Starts the local development server or connects the terminal UI to an existing URL.

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

Pass a bare URL as the only argument (rewritten internally to `--url`) to smoke-test a preview or production deployment without booting a local server.

### UI modes

| Mode | When |
| --- | --- |
| Terminal UI | Interactive TTY and no `--no-ui` |
| Headless | `--no-ui`, or stdin/stdout is not a TTY |

In headless mode the server keeps running and prints `server listening at <url>`. Non-TTY terminals without `--no-ui` receive a warning that the interactive UI is disabled.

### Flags

<ParamField body="--host" type="string" default="127.0.0.1">
Host interface for the local dev server. Cannot be combined with `--url`.
</ParamField>

<ParamField body="--port" type="number" default="$PORT, then 2000">
Port for the local dev server. When omitted, Eve retries up to 10 consecutive ports if the default is in use. Cannot be combined with `--url`.
</ParamField>

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

<ParamField body="--no-ui" type="flag">
Start the server without the interactive terminal UI.
</ParamField>

<ParamField body="--name" type="string" default="humanized app folder name">
Title shown in the terminal UI header. For remote URLs, defaults to the URL host.
</ParamField>

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

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

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

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

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

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

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

<ParamField body="--logs" type="enum" default="stderr">
Server and agent logs to surface inline: `all`, `stderr`, `sandbox`, or `none`.
</ParamField>

### Dev server lifecycle

Local dev writes the active server PID to `.eve/dev-process.pid`. Starting a second `eve dev` for the same agent while that process is running exits with the PID and a `kill` command to stop it.

Dev mode keeps immutable runtime snapshots under `.eve/dev-runtime/snapshots/` so in-flight sessions hold a consistent code revision while new prompts pick up rebuilds. On startup, `eve dev` prunes stale runtime snapshots and old local sandbox templates in the background.

## `eve link`

Links the current directory to a Vercel project, then pulls environment variables so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`.

```bash
eve link
```

Interactive only. The command walks team and project pickers; re-linking always runs the pickers and the new choice wins. In CI, use `vercel link --project <name> --yes` instead. Exits with code `1` when the directory is not an Eve project or the terminal is not interactive.

## `eve deploy`

Deploys the agent to Vercel production via `vercel deploy --prod`, installing dependencies first and pulling environment variables after.

```bash
eve deploy
```

| Scenario | Behavior |
| --- | --- |
| Already linked | Deploys immediately, with or without a TTY |
| Unlinked + interactive terminal | Walks the same team/project pickers as `eve link` |
| Unlinked + non-interactive | Exits with guidance to run `eve link` or `vercel link` first |

On success, prints the production URL when available.

## `eve eval`

Runs eval modules discovered under `evals/` (files matching `*.eval.ts`).

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

With no eval IDs, runs all discovered evals. IDs match exactly or by directory prefix — `eve eval weather` runs everything under `evals/weather/`.

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Every eval passed its gate assertions (and soft thresholds when `--strict` is set) |
| `1` | At least one eval failed a check, hit an execution error, or missed a threshold under `--strict` |
| `2` | Configuration error (no evals discovered, no evals matching filters, invalid flag values) |

Without `--url`, eval starts a local dev server on `127.0.0.1` with port `0` (OS-assigned) and tears it down when finished.

<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">
Treat below-threshold scores as failures in addition to gate assertion failures.
</ParamField>

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

<ParamField body="--timeout" type="number">
Per-eval timeout in milliseconds. Must be a non-negative integer.
</ParamField>

<ParamField body="--max-concurrency" type="number" default="8">
Maximum concurrent eval executions. Must be a positive integer. Config-level `maxConcurrency` in eval config is used when this flag is omitted.
</ParamField>

<ParamField body="--json" type="flag">
Output results as JSON (suppresses the console reporter).
</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 such as Braintrust.
</ParamField>

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

## `eve channels`

Manage user-authored channel modules under `agent/channels/`.

### `eve channels add`

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

Scaffolds a channel. With no `kind`, prompts interactively. Pass `slack` or `web` to scaffold directly.

<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` and an interactive terminal for kind-less runs.
</ParamField>

### `eve channels list`

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

Lists user-authored channels in the current project.

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

## Recommended workflow

<Steps>
<Step title="Author under agent/">
Edit instructions, tools, skills, channels, and `agent.ts` configuration.
</Step>

<Step title="Verify discovery">
Run `eve info` to confirm files were discovered and read diagnostics before starting the dev server.
</Step>

<Step title="Iterate locally">
Run `eve dev` and exercise the agent through the terminal UI or HTTP routes.
</Step>

<Step title="Build and smoke-test">
Run `eve build`, then `eve start` to verify the production artifact locally.
</Step>

<Step title="Link and deploy">
Run `eve link` to pull gateway credentials, then `eve deploy` for Vercel production.
</Step>
</Steps>

## Related pages

<CardGroup cols={2}>
<Card title="Installation" href="/installation">
Prerequisites, package managers, and first-install commands for Eve projects.
</Card>

<Card title="Eve quickstart" href="/eve-quickstart">
Run `eve init`, start `eve dev`, inspect with `eve info`, and send the first session message.
</Card>

<Card title="Eve project layout" href="/eve-project-layout">
What `eve info` discovers under `agent/` and how path-derived naming works.
</Card>

<Card title="Eve deployment" href="/eve-deployment">
Build `.eve/` artifacts, configure Vercel env, and verify production routes.
</Card>

<Card title="Eve HTTP protocol reference" href="/eve-http-protocol-reference">
Session routes, NDJSON events, and `continuationToken` follow-ups served by `eve dev` and `eve start`.
</Card>

<Card title="Runtime models" href="/runtime-models">
Compare Eve sessions and turns with Flue sessions and workflow runs.
</Card>
</CardGroup>