---
title: "CLI"
description: "eve command reference: info, build, start, dev, eval."
---

The `eve` binary (`bin: eve`) runs from your app root, and every command loads `.env`/`.env.local` from that root before it does anything else.

## Commands

| Command                   | Does                                                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `eve info`                | Print the resolved application: discovered tools, skills, subagents, schedules, channels, routes, artifact paths, and discovery diagnostics |
| `eve build`               | Compile `.eve/` artifacts and build the 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 (e.g. a remote deployment) instead of booting a local server                                       |
| `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                                                                                                                 |

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

## `eve info`

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

| Flag     | Effect       |
| -------- | ------------ |
| `--json` | Emit as JSON |

When something behaves unexpectedly, run this first. It confirms a file was discovered, lists the active surface, and surfaces discovery diagnostics, all faster than booting the dev server.

## `eve build`

```bash
eve build
```

No flags. Compiles to `.eve/` and builds the host output, then prints the built output path.

Useful artifacts written under `.eve/` (preserved even on partial failure):

| Artifact                                       | Tells you                                            |
| ---------------------------------------------- | ---------------------------------------------------- |
| `.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 <host>] [--port <port>]
```

| Flag            | Effect                                               |
| --------------- | ---------------------------------------------------- |
| `--host <host>` | Host interface to bind                               |
| `--port <port>` | Port to listen on (defaults to `$PORT`, then `3000`) |

Serves the previously built output. Prints the listening URL.

## `eve dev`

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

Pass a bare URL as the only argument and the UI connects to that server instead of booting a local one (same as `--url`). That's handy for smoke-testing a preview or production deployment. The interactive UI turns off in a non-TTY terminal.

| Flag                                | Effect                                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| `--host <host>`                     | Host interface to bind                                                                    |
| `--port <port>`                     | Port to listen on (defaults to `$PORT`, then `3000`)                                      |
| `-u, --url <url>`                   | Connect to an existing server URL instead of starting one                                 |
| `--repl`                            | Use the classic line-based REPL instead of the terminal UI                                |
| `--no-ui`                           | Start the server without an interactive UI                                                |
| `--name <name>`                     | Title shown in the terminal UI (defaults to the app folder name)                          |
| `--tools <mode>`                    | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
| `--reasoning <mode>`                | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
| `--subagents <mode>`                | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`         |
| `--connection-auth <mode>`          | Connection-authorization rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
| `--assistant-response-stats <mode>` | Assistant header statistic: `tokens` \| `tokensPerSecond`                                 |
| `--context-size <tokens>`           | Model context window size, shown as a usage percentage                                    |
| `--logs <mode>`                     | Server/agent logs to show: `all` \| `stderr` \| `none`                                    |

Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight sessions keep a consistent code revision while new prompts pick up rebuilds. `eve dev` prunes stale runtime snapshots and old local sandbox templates in the background on startup; stopping `eve dev` and deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/` is safe when you want a manual cleanup.

## `eve eval`

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

Runs all discovered evals when no eval ids are given. Exits `0` when every case passed its checks, `1` when any case failed (a failed check, an execution error, or a `--strict` threshold miss), `2` on configuration errors.

| Flag                    | Effect                                                |
| ----------------------- | ----------------------------------------------------- |
| `--url <url>`           | Remote agent URL (skip local host startup)            |
| `--tag <tag...>`        | Run only cases (or evals) carrying a tag              |
| `--case <id...>`        | Run only specific case ids                            |
| `--strict`              | Below-threshold scores also fail the exit code        |
| `--list`                | Print discovered evals and cases without running them |
| `--timeout <ms>`        | Per-case timeout in milliseconds                      |
| `--max-concurrency <n>` | Max concurrent case executions per eval               |
| `--json`                | Output results as JSON                                |
| `--skip-report`         | Skip eval-defined reporters (e.g. Braintrust)         |

See [Evals](../advanced/evals) 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: [Project layout](./project-layout) · [instrumentation.ts](../advanced/instrumentation).

## What to read next

- [Project layout](./project-layout): what `eve info` discovers
- [instrumentation.ts](../advanced/instrumentation): tracing and the error catalog
- [Deployment](../advanced/deployment): `eve build` and `eve start` in production
