vendo init - Vendo

npx vendo init

One command. It scans the app with deterministic analysis, writes everything it can, and tells you the little that is left. Init never writes to a file you authored. Every file it creates is new and Vendo-owned, plus its own package.json hooks.

What init writes

Path	Framework	Contents
`app/api/vendo/[...vendo]/route.ts`	Next.js	the catch-all handler holding `createVendo()`. Under `src/app/` when that directory exists
`vendo-actions.ts`	Next.js	the server-action registration map, when the scan finds server actions
`vendo/server.ts`	Express, custom	`createVendo()` plus the adapter. `.mjs` without a `tsconfig.json`
`.vendo/tools.json`	all	tools extracted from your OpenAPI spec and routes
`.vendo/overrides.json` `.vendo/policy.json` `.vendo/brief.md`	all	stubs you own
`.vendo/theme.json` `.vendo/theme.extracted.json`	all	the extracted theme, and the scan output it was merged from
`.vendo/data/`	all	the local database, with its own `.gitignore`
`.env.example`	all	the `VENDO_BASE_URL` block — the dev shape for reference, and the instruction to set the real value in your hosting platform when you deploy — plus commented `VENDO_HOST_API_URL`, `VENDO_LOGIN_URL`, and `ANTHROPIC_API_KEY` lines. The append is idempotent
`.env.local`	all	`VENDO_BASE_URL`, from the dev-URL question, on interactive runs and with `--base-url`. Never a deployed URL
`.claude/skills/vendo-setup/`	all	the setup skill, when a `.claude/` directory exists and the skill does not

It also adds idempotent predev and prebuild hooks to package.json:

{
  "scripts": {
    "predev": "vendo sync --no-ai",
    "prebuild": "vendo sync --strict --no-ai"
  }
}

The hooks carry --no-ai explicitly, so npm run dev can never stop to ask a question or spend on inference. An existing script keeps its formatting and gets vendo sync prepended.

The one step left

Init writes no client file. Mounting the provider is yours to paste, and init prints the exact file and lines:

────────────────────────────────────────────────────────────────
ONE STEP LEFT — paste this yourself (init never edits your files)

  File: app/layout.tsx
    import { VendoProvider } from "@vendoai/vendo/react";
    … then wrap: <VendoProvider baseUrl="/api/vendo">{children}</VendoProvider>
────────────────────────────────────────────────────────────────

The same step rides the --agent write run’s receipt, in pasteEdits. Until it lands, vendo doctor fails with E-WIRE-004 and reprints it. A host with its own components writes one "use client" file holding the component registry and the provider, and mounts that instead. The registry carries component references, which cannot cross a Server Component boundary.

How detection decides

Init makes two independent, dependency-based calls before it writes anything.

Framework

Dependency	Scaffold
`next`	the catch-all route under `src/app` when that directory exists, else `app`
`express`	`vendo/server.ts`, mounted with `app.use("/api/vendo", mountVendo())`
neither	a runtime-neutral `vendo/server.ts` exporting `handleVendoRequest(request, env)`

Init checks next first, so an app with both dependencies gets the Next scaffold. A non-interactive run with no detected framework errors and asks for --framework rather than guessing. The custom scaffold takes a web Request and returns a Response, constructed lazily on the first request. Cloudflare Workers, Bun, Deno, Hono, and Lambda each mount it in one line.

Monorepos: init targets the app package, not the repo root. Detection reads the package.json of the directory init runs in, or the one you point it at (npx vendo init apps/web). Run login, doctor, and sync from that same directory: login writes the minted key to .env.local in the current working directory.

Auth

Init reads package.json and detects one auth family.

Dependency	Preset
`next-auth`, `@auth/*`	`authJs`
`@clerk/*`	`clerk`
`@supabase/*`	`supabase`
`@auth0/*`	`auth0`

A single detected family gets one [Y/n] confirm before anything is written. Decline it, or have several or none detected, and init leaves principal unwired and prints the exact one-line auth: addition. --auth <preset> answers without the prompt. The presets and when to pick each are on Auth.

The model key

Init runs a key step rather than scaffolding a model file. If a provider key is already set it says so; otherwise it offers a Vendo Cloud key inline. vendo login approves a code in the browser and appends the minted VENDO_API_KEY to .env.local without touching your other keys. You never paste a key. Init never fails on a Cloud error. vendo cloud login <email> is the email-OTP fallback.

What an interactive run asks

There is no interview. An interactive run stops only for Enter-to-accept decisions:

the detected auth preset
where the app runs in dev, prefilled from your dev script’s port — Enter accepts it, and the answer lands in .env.local as VENDO_BASE_URL
the Vendo Cloud key offer
consent for the AI judgment pass
one aggregated review, if that pass proposes a loosening
a zod bump when your pin is below 3.25
an uncertain theme slot
whether your own backend will call tools machine-to-machine (--use-case mcp)
whether to run vendo doctor on the way out

--yes answers all of them and ends with an Agent tail: block naming the files left to hand-edit.

Agent mode

npx vendo init --agent

--agent changes how init’s questions travel, not what init asks. Called with no answers, it detects what it can and prints ONE JSON object holding the questions it still needs answered. It writes nothing and exits 0. Each question carries its options, the recommended pick, and the flag that answers it. Your coding agent relays them to you in chat, then re-runs init with your answers as flags:

npx vendo init --agent --use-case embedded --auth clerk --byo

That run writes. Pass every answer on the first call and there is no ask pass at all: init writes in one go. The status field tells the two runs apart, so an agent never has to guess whether the repo was touched.

`status`	Carries
`questions`	`detected` (framework and any auth preset), and `questions`: each one a chat-ready `prompt` with its `options`
`written`	`wrote` (every file of the install), `pasteEdits` (the mount and any other paste), `tools`, `riskRecommendations`, and `judgment`, whose `checklist` names the four calls only a reader of the code can make

The answer flags are the ones init already has: --use-case, --auth, --cloud-key or --byo, and --base-url. Nothing else is asked — the MCP path asks no extra question of its own, it asks the Cloud one in its own words, and --cloud-key/--byo answer it. The zod bump, uncertain theme slots, and the closing live check never surface in agent mode. They take exactly the defaults --yes takes.

Every flag

vendo init [dir]. dir is the app to initialize and defaults to the current directory.

Flag	Values	Answers
`--use-case <name>`	`embedded`, `agent-loop`, `mcp`	how people will use the agent
`--auth <preset>`	`authJs`, `clerk`, `supabase`, `auth0`, `jwt`, `none`	which auth preset to wire
`--cloud-key <key>`	a `vnd_` key	writes an existing Vendo Cloud key to `.env.local`
`--byo`		declines the Cloud key offer
`--ai` / `--no-ai`		force the AI judgment and theme pass on or off
`--base-url <url>`	a full `http(s)` URL	where the app runs in dev
`--theme <slot=value>`	repeatable	answers an uncertain theme slot
`--framework <name>`	`next`, `express`, `custom`	overrides framework detection
`--engine <name>`	`claude`, `codex`, `npx`	pins the AI-pass engine instead of first-available
`--posture <name>`	`local`, `broker`	which authorization server fronts the door. Not asked — `broker` opts out of the dev sign-in key. `--use-case mcp` only
`--service-key`		the dev sign-in key, which a local door wires by default. `--use-case mcp` only
`--yes`		skip every prompt and take the detected defaults
`--agent`		ask through a coding agent: print the questions as JSON, or write when the answers ride along
`--force`		regenerate Vendo-owned files under `.vendo/`. Never replaces host source
`--check` / `--no-check`		run `vendo doctor` at the end, or skip it

--cloud-key and --byo answer the same question, as do --ai and --no-ai and --check and --no-check. Passing both halves of a pair exits 1. --posture or --service-key without --use-case mcp exits 1 rather than being silently ignored, and so does --service-key with --posture broker: a Cloud-fronted door provisions its own key, so accepting one there would discard it. --ai-polish is the older spelling of --ai. --posture broker with a dev URL that is not https:// exits 1 too: Vendo Cloud registers that origin as the tenant’s forwarding address and refuses one that is not https, so the door would be written and then fail on its first request. Take --posture local, which is zero config and works on http, or pass an https origin. This one is checked against the URL the run resolved rather than the flags alone, so it also catches a broker posture picked at the prompt.

--base-url is a DEV URL: it lands in .env.local as VENDO_BASE_URL, which is what your own agent loop, any backend process, and the MCP door need before their first tool call. Production is never set here — set VENDO_BASE_URL in your hosting platform’s environment settings when you deploy. A deployed URL in .env.local would repoint local dev’s discovery, callbacks, and credential forwarding at the deployed origin.

Init rejects an option it does not recognize and exits 1 before doing anything. A flag an older CLI does not support can never be silently dropped.

Re-running init

Init only creates what is missing. A rerun on a wired app prints “Already wired” and still re-runs extraction, the theme reconcile, and the AI-pass offer. Day to day you do not re-run init at all. The predev and prebuild hooks call vendo sync on every build, which is what keeps .vendo/tools.json current. Re-run init when the detected surface changes in a way sync cannot scaffold for, such as adding Express to a Next app. Starting over or removing Vendo is on Uninstall.

Verify

vendo doctor owns verification.

npx vendo doctor

Doctor reads the repo: wiring, the .vendo/ files, the tool catalog, and the model credential in your environment. It needs no running app. vendo doctor --json is the machine-readable gate agents loop on.

Right after a release, package managers with a cooldown hold the new version back. pnpm 11 fails loud with “no versions available”; npm’s opt-in min-release-age instead resolves silently to an older version, which init then pins.Check what you got with npm ls @vendoai/vendo. To take the current release anyway, pass --min-release-age=0 on npm, or exclude Vendo in pnpm-workspace.yaml:

minimumReleaseAgeExclude:
  - vendoai
  - "@vendoai/*"

​What init writes

​The one step left

​How detection decides

​Framework

​Auth

​The model key

​What an interactive run asks

​Agent mode

​Every flag

​Re-running init

​Verify

What init writes

The one step left

How detection decides

Framework

Auth

The model key

What an interactive run asks

Agent mode

Every flag

Re-running init

Verify