vendo init

What vendo init scans, every file it writes, how framework and auth detection decide, and how —agent hands its questions to a coding agent.

npm install @vendoai/vendo
npx vendo init

The vendo bin ships in @vendoai/vendo, so installing the package is all it takes. Before anything is installed, npx vendoai@latest init runs it straight from npm.

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"
  }
}

Those hooks resolve vendo out of node_modules/.bin, so the bin has to be installed in the project — not just run once through npx. @vendoai/vendo carries it, and the files init writes import that package anyway, so a project it wired can always run its own hooks.

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 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 exits 1 too when the dev URL is not https://: Vendo Cloud registers that origin as the tenant’s forwarding address and refuses a non-https one, so the door would be written and then fail on its first request. Take --posture local — zero config, works on http — or pass an https origin. The check reads the URL the run resolved, not the flags, so it catches a broker posture picked at the prompt too.

--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

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

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/*"