CLI

evestack is the whole command. Eight things:

evestack create [name]        scaffold an agent, a database and a dashboard
evestack status               is it up? what do I run?
evestack tour                 a guided first run, on a stack that is already up
evestack open                 the dashboard URL and its password, in a browser
evestack verify               check every part and name the fix for anything broken
evestack skills               teach your coding agent this project
evestack attach [dir]         add evestack to an eve project you already have
evestack doctor               a run stopped moving — read-only forensics

npx create-evestack [name] is the same scaffolder as evestack create, under the name npm's create-* convention leads people to. Same code, same prompts, same flags — a bug is fixed once.

-h / --help and -V / --version work anywhere, and asking never writes, starts or opens anything. Each command's --help prints its own options; the top-level one is the command list and nothing else.

A bare evestack inside a project runs status. Outside one it prints the command list and exits 0 — typing the program's name is not an error. A command it does not recognise gets one suggestion if there is a close one (evestack verfiy → Did you mean evestack verify?) and never a guess if there is not.

Which one am I looking for

The three checking commands answer different questions, and it is worth being able to pick:

evestack create / npx create-evestack

npx evestack create [name] [--yes] [--verbose]
npx create-evestack [name] [--yes] [--verbose]

Four questions, all asked before any work starts, so the install and the image pull are a wait you can walk away from:

1. Where — the directory.
2. Model — OpenAI, Anthropic or Ollama, and a key if you have one.
3. Tools — Composio, on by default.
4. Bring it up — whether to start Postgres, create the schema and pull the dashboard.

What it generates

• The agent project, from templates/default
• .env.local with a uniquely generated EVESTACK_AUTH_PASSWORD — never a shipped default
• .env with the generated database password, which is the only file Compose interpolates from
• .gitignore covering .env*, so a generated credential can't be accidentally committed
• docker-compose.yml for Postgres, with the dashboard behind a profile

It finishes by drawing the four moving parts with the ports this project chose — they are not always 2000, 5433 and 4000, because a second scaffold on the same machine moves them — and then offers to start the agent, which is the only step left.

Why the scaffolder has zero dependencies

A scaffolder that installs a prompt library before asking its first question is slower than the thing it scaffolds — and every dependency is another supply-chain surface for a tool that writes files and credentials to your disk. It's built on Node's built-in readline, crypto, and fs only.

Exit codes

0 only when the project was created and its dependencies installed. If npm install fails, or node_modules/eve is missing afterwards, it exits 1 and prints what to run — so a && chain or a CI step stops there rather than walking into an empty node_modules.

If you accept the offer to start the agent, the exit code becomes the agent's.

Two real bugs this caught

An early version exited 0 — success — having created nothing, whenever stdin wasn't an interactive terminal (a CI run, a piped heredoc). readline's question() never resolves after stdin hits EOF, and Node exits cleanly once the event loop empties. Silent success is the worst failure mode for a scaffolder, so --yes and non-TTY detection now race every prompt against stdin closing, and fall back to a sane default instead of hanging or vanishing.

The second was the same failure mode wearing a different hat. The template copy skipped any source path matching node_modules, tested against the absolute path — and npx stages a package at ~/.npm/_npx/<hash>/node_modules/create-evestack/template/…, so every file was skipped and npx create-evestack produced an empty directory. It worked perfectly from a monorepo checkout, where no node_modules appears in the path, which is exactly why nothing caught it. The filter now matches path segments of the path relative to the template root, and CI scaffolds from an npx-shaped directory on every PR.

evestack status

evestack status [--json]

The glance. Four parts — the agent, Postgres and the dashboard probed in parallel, plus the model configuration, which is read from .env.local rather than called, because a status command that spends money is one people stop typing — with the command that fixes anything that is down printed under it. Read-only: the Postgres connection is pinned default_transaction_read_only = on by the same helper doctor uses, so it is safe to point at production.

It reports two things about Postgres beyond reachability: whether the workflow schema was ever created (forgetting db:bootstrap is a distinct state with a distinct fix, not a green tick), and how many runs and memories are in it.

When Postgres and the dashboard are both unreachable it checks Docker before printing two compose commands that would fail, and says that instead.

evestack tour

evestack tour [--yes] [--message=TEXT] [--no-open]

A guided first run, four steps, on a stack that is already up. It confirms the parts are answering, sends one real message to your agent and streams the reply into the terminal, then links you to that same turn in the dashboard and explains what each surface just showed you.

That one message is a real model call — a fraction of a cent on gpt-5-mini, free and slower on Ollama. Nothing else in the tour calls a model, and it says so before it sends anything.

With no terminal to ask, it refuses and exits 3. In CI, under a pipe, or with stdin closed, the confirmation has nobody to answer it — so the tour stops rather than treating silence as consent, and names --yes as the way to accept the charge up front. It used to send the message.

It needs the agent, Postgres and a model key. The dashboard is step 3 rather than a prerequisite — a turn is a turn whether or not anything is watching — so with the container down it still runs and prints the link.

evestack verify

evestack verify [--open | --no-open] [--json]

Runs the project's own scripts/verify.mjs and groups its eleven checks in dependency order — foundation (.env.local, Docker, Postgres, the schema, pgvector), model (the provider key, embeddings), then the stack (the agent, the dashboard, trace ingest). The eleventh, dashboard image — does the running container's version match the tag your compose file pins? — runs only once the dashboard answers, and prints under other, the catch-all group that exists so a check can never be silently dropped. For anything broken it names the command that fixes it, and it exits 1 if a required check failed, so CI can run it too.

Grouping is the point: a red dashboard and a red postgres used to read as equally urgent when one of them is why the other failed. Fix the highest red line first.

It does not reimplement the checks: it executes the script that shipped with your project, so a globally installed CLI cannot report problems against rules your project does not have. A project made by attach has no scripts/ of its own, and there it falls back to the copy inside create-evestack.

evestack open

evestack open [--no-open]

Prints the dashboard URL, the username and the password, says whether anything is answering there, and opens a browser. It exists because the scaffolder prints the credentials exactly once into a terminal that then scrolls, and the only recovery path was knowing which key of .env.local held the password.

The port comes from EVESTACK_DASHBOARD_URL, which is where the chosen dashboard port is recorded — the scaffolder does not assume 4000. --no-open prints and stops. Exit 1 means nothing is answering yet.

evestack skills

evestack skills [--dir=PATH] [--print] [--force] [--json]

Writes the evestack skill pack — SKILL.md plus four reference files — where your coding agent will find it, so it knows this project without being told. The same pack the landing page's Set up your agent button copies. Full detail in Set up with an agent.

The pack is fetched from the site rather than bundled into this package, so it cannot ship stale — which is the trade: it needs a network connection, and says so plainly when it does not have one.

evestack attach

npx evestack attach [dir] [--yes] [--dry-run]

Adds evestack to an eve project you already have, without overwriting anything, and prints an undo line for everything it writes.

evestack doctor

evestack doctor [options]

Read-only forensics for a durable job that is dead: it never writes to your database, and when there is something to fix it prints the SQL and lets you decide. Safe to point at production.

A flag that takes a value needs it as --flag=VALUE. --limit 50 is refused rather than guessed at, because the alternative is a silent run with the default and a stray positional argument.

Exit codes

Doctor's codes are the ones the repro scripts in contract/runtime/repro use, so an operator who has run those already knows what they mean.

create and attach use the same shape: 0 is a project you can run, 1 is one you cannot.

status, verify, open, tour and doctor all work from anywhere inside the project directory — they walk up looking for the project's env files, because evestack is on PATH and gets typed from wherever you happen to be. Outside a project they all say so, rather than failing at whatever they tried next.

Output

Every command shares one renderer, so colour, width and glyphs are decided in one place (packages/create-evestack/ui.mjs, copied verbatim into each scaffold as scripts/ui.mjs).

Colour is off unless stdout is a terminal. Piping, redirecting to a file, or paging gets plain text — which is what makes a doctor report safe to paste into an issue. Three environment variables override the decision:

TERM=dumb is treated as no colour. The brand blue needs a 256-colour terminal and falls back to cyan without one.