CLI Reference

Purpose and Scope

The eve command-line interface is the operational entry point for an eve project. It is used to scaffold an agent, inspect what the filesystem authoring model discovered, compile the generated artifacts, run local development, connect the terminal UI to a deployed agent, link a directory to Vercel, deploy production builds, and run evals. This page is written as a command reference, but it also explains how the commands fit into eve’s default HTTP channel so that CLI behavior is easier to reason about when moving between local and deployed environments.

The official command model treats the eve binary as something you run from the app root. Each command first loads .env and .env.local from that root, so command behavior depends on the same environment that the agent runtime, channel credentials, and deployment settings use. Running eve without a subcommand is equivalent to running eve dev, which makes the local development terminal UI the default experience for new projects.

The CLI is not separate from the application surface. The eve channel documentation identifies the default HTTP API as the interface used by the terminal UI, useEveAgent, curl, and SDK clients when they start sessions, send messages, and stream events. That matters for CLI users because local development, remote UI attachment, health checks, and session inspection all depend on the same canonical routes rather than a private side channel. Sources: docs/channels/eve.mdx

Relevant Source Files

• docs/channels/eve.mdx — Documents the default eve HTTP channel, including the terminal UI’s relationship to the channel, canonical /eve/v1/* routes, session creation, follow-up messages, streaming, CORS, and auth behavior that CLI-driven workflows rely on.

Command Reference

The most important operational distinction is between commands that change project state and commands that observe or run the project. eve init, eve link, and eve deploy are stateful: they create files, connect project metadata, or publish a production deployment. eve info, eve build, eve start, eve dev, and eve eval are execution-oriented: they resolve the app, compile it, serve it, open the local UI, or run validation. Treating those groups differently helps teams decide which commands belong in onboarding scripts, local workflows, CI jobs, and release automation.

eve init [target] is the command to use when you want eve to create the conventional agent layout or add that layout to an existing project. The generated project is expected to include the filesystem primitives that eve discovers, such as instructions, tools, skills, channels, schedules, and configuration. For the default HTTP channel specifically, the channel docs note that eve init scaffolds agent/channels/eve.ts with a production auth placeholder so developers replace it before going live. Sources: docs/channels/eve.mdx

eve info is the safest command to run when the project does not behave as expected, because it prints the resolved application rather than starting a model turn. Use it after adding a tool, moving a skill, editing a schedule, or changing a channel file. Its output is meant to reveal both the positive discovery result and diagnostics, including routes and artifact paths. In practice, this makes eve info the bridge between the filesystem authoring model and the runtime shape that eve build, eve dev, and eve deploy will use.

Development and Local Operation

eve dev is the default local loop. It starts the local dev server and opens the terminal UI, giving developers a fast path from editing files to testing an agent turn. Because the eve channel is the default HTTP API and is enabled even when agent/channels/eve.ts does not exist, the terminal UI can talk to the standard session endpoints without requiring every project to author a custom HTTP channel. The channel docs explicitly describe the terminal UI as one of the clients that uses this API to start sessions, send messages, and stream events. Sources: docs/channels/eve.mdx

The alternate form, eve dev <url>, keeps the UI but changes the target. Instead of booting a local server, the UI connects to an existing server URL, such as a remote deployment. This is useful when investigating production-only configuration, Vercel service wiring, route authorization, or a deployed model/provider environment. Since remote access goes through the same channel routes, the remote deployment must expose the eve channel and must allow the caller under its configured auth policy.

For low-level debugging, the channel routes documented for eve are also the routes that explain what the CLI and clients are ultimately exercising. The app exposes GET /eve/v1/health, GET /eve/v1/info, POST /eve/v1/session, POST /eve/v1/session/:sessionId, and GET /eve/v1/session/:sessionId/stream. A session response includes a sessionId for stream and inspection access and a continuationToken for follow-up turns. The stream endpoint emits newline-delimited JSON events, which is why local and remote UIs can render turn progress incrementally. Sources: docs/channels/eve.mdx

# start the default local development flow
npx eve@latest dev
 
# equivalent default when the eve binary is already installed
eve
 
# attach the terminal UI to a deployed or separately running app
eve dev https://example-agent.vercel.app

Build, Start, Link, and Deploy Flow

Use eve build when you want to compile the project rather than run a hot development loop. The command compiles .eve/ artifacts, builds the host output, and prints the output directory. That output is what eve start serves from .output/. A common local release check is therefore to run eve info, then eve build, then eve start, and finally exercise the HTTP channel routes or the client application against the printed listening URL.

eve link and eve deploy are the Vercel-oriented commands. Linking associates the local directory with a Vercel project and pulls AI Gateway credentials. Deployment publishes the agent to Vercel production and links first if needed. These commands are often used after the local channel auth policy has been made production-safe, because the generated default file intentionally includes a placeholder that returns a setup-focused unauthorized response until replaced. Deleting the generated file falls back to built-in Vercel OIDC plus local development auth, which still does not admit browser users in production. Sources: docs/channels/eve.mdx

The channel auth details are important during deployment because eve dev <url>, browser clients, SDK clients, and other services are all ordinary callers of the deployed HTTP API. The auth option controls access to /eve/v1/info and the session routes. Built-in helpers cover local development and trusted Vercel-issued infrastructure, while public applications are expected to wire their own Clerk, Auth.js, OIDC/JWT, API-key, or custom verifier policy. Treat successful deployment and successful client access as separate checks.

# inspect discovered app shape before publishing
eve info
 
# compile and smoke-test the built app
eve build
eve start
 
# prepare Vercel association and credentials
eve link
 
# deploy to production
eve deploy

Evals and Release Validation

eve eval runs evals against a local app or a remote target. Conceptually, it belongs after eve info and before or after deployment, depending on what you want to validate. Local evals are useful while authoring instructions, tools, and skills because they run near the edited filesystem state. Remote evals are useful after deployment because they exercise the real hosted channel, production environment variables, provider credentials, and route authorization decisions.

When an eval target is remote, the same route and auth considerations apply as with eve dev <url>. The target must expose the eve HTTP API and the eval runner must be authorized to call it. The channel documentation’s distinction between session IDs, continuation tokens, and streaming routes gives teams a practical debugging vocabulary when evals fail: a start-session failure points to request shape or auth, a follow-up failure points to continuation handling, and a stream failure points to event delivery or cursor behavior. Sources: docs/channels/eve.mdx

A practical validation sequence for teams is to run eve info first, because it catches discovery and configuration surprises without invoking the agent. Next, run local evals against the development server or built output. Then deploy and run a smaller remote eval suite to verify that production credentials, auth, and channel routing are correct. This separates authoring correctness from hosting correctness and makes failures easier to triage.

HTTP Channel Details Relevant to CLI Users

The default eve channel is mounted under /eve/v1/session* and is enabled by default, even when an app does not define agent/channels/eve.ts. Most apps only create that file to customize route auth or CORS. This defaulting behavior is what lets scaffolds, local tools, and clients work immediately: there is always a canonical HTTP session surface unless the developer intentionally changes channel configuration. Sources: docs/channels/eve.mdx

CORS is intentionally separate from route authorization. The eve channel leaves CORS untouched by default. Developers can pass cors: true for permissive browser access or provide an options object to narrow origins, methods, and headers. Route auth still runs on the actual session requests, so enabling browser preflight support does not by itself make a deployed agent public. CLI users usually notice this when a terminal workflow works but a browser frontend fails preflight or lacks user-facing auth.

The session route flow is simple enough to test without the CLI. POST /eve/v1/session starts a turn and returns the handles needed for follow-up and streaming. POST /eve/v1/session/:sessionId sends a follow-up, and GET /eve/v1/session/:sessionId/stream streams events as application/x-ndjson; charset=utf-8. Knowing those primitives helps when diagnosing whether a CLI command failed to start the server, failed to authenticate, or reached the server but could not complete a session. Sources: docs/channels/eve.mdx

# minimal health and session checks against a running deployment
curl https://<deployment>/eve/v1/health
 
curl -X POST https://<deployment>/eve/v1/session \
  -H "Content-Type: application/json" \
  -d '{"message":"What is the weather in Paris?"}'
 
curl -N https://<deployment>/eve/v1/session/<sessionId>/stream

Next Steps

Start with eve init [target] for a new project or eve info for an existing one. Use eve dev for the everyday editing loop, eve build and eve start for compiled smoke tests, eve link and eve deploy for production release, and eve eval for behavioral validation. If any CLI workflow reaches a server but fails at interaction time, inspect the eve channel configuration first: auth, CORS, and the /eve/v1/* routes define whether local tools, browser clients, SDKs, and remote terminal UI sessions can access the agent.