# CLI > The voltro CLI — every command, grouped by purpose, with the flags that actually matter. --- ## Overview _The voltro CLI — every command, grouped by purpose, with the flags that actually matter._ The Voltro CLI is the single entry point for scaffolding, dev, build, and run. It also seeds the framework agent guide into every project — written under BOTH `AGENTS.md` and `CLAUDE.md` — so AI coding agents have your framework conventions on tap. ## Command quick-reference The dispatcher routes `voltro [args]` to the matching subcommand and passes the rest through. **`voltro help` is the authority** — it prints the registry itself, so it cannot drift from what your installed CLI dispatches. The table below is every command that registry exposes, grouped by purpose: | Group | Commands | |---|---| | [Scaffolding](/docs/cli/scaffolding) | [`init`](/docs/cli/scaffolding#voltro-init) (initialise the current directory as a workspace root — no apps), `create-project`, `add-app`, `list-templates`, `new` (scaffold one primitive — `query` / `mutation` / `action` / `workflow` / `page`) | | Packages | `package` (`create` / `publishable` / `private` / `status`), `create-package` | | [Dev](/docs/cli/dev) | `dev`, `codegen`, `typecheck` (`tsc --noEmit` with the app's own TypeScript), `agents-md`, [`env`](/docs/cli/env) (`check` / `sync` / `types` / `turbo`), [`generate`](/docs/cli/scaffolding) (AI app-builder), `dashboard` (serve the DevTools dashboard standalone; `--port`, `VOLTRO_DASHBOARD_APPS`) | | [Build & run](/docs/cli/build-and-start) | `build`, `start`, `serve` | | Deploy | `deploy` (`plan` — auto-detect the target tier per app + function), [`serverless`](/docs/deployment/serverless-functions) (`list` / `dev` / `serve` / `build` / `deploy`), [`static`](/docs/deployment/static-sites) (`hosts` / `deploy`), `dormancy` (single-node scale-to-zero: fronts the app, stops it when idle, wakes on the next request; `--idle-grace-ms` / `--tick-ms`) | | [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`), [`evolve`](/docs/database/migrations/rename-and-drop) (schema-evolution copilot — propose a codemod + branch-verified backfill for a rename / retype / split / drop of an existing column or table) | | [Update](/docs/cli/update) | `update` (`--to` / `--dry-run` / `--force` / `--exact`) — bump every `@voltro/*`, install, run the codemods that adapt your source to the new version | | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption | | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule` (`run ` — fire a registered schedule on demand; `--process` / `--trigger manual\|external` / `--url`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) | | AI / data | `embeddings backfill --text --vector ` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview; [`eval`](/docs/ai/agents#evaluating-recorded-runs-voltro-eval) — replay recorded agent runs against golden cases + judge, exit 1 on regression (a deploy gate; `--json` / `--branch` / `--threshold`) | | Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer--the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) | | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` | | [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) | | Harness | `test`, `e2e` | | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`); `login` is a top-level alias of `cloud login` | | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) | | Meta | `agents-md`, `telemetry` (reports that Voltro collects none — no phone-home, nothing to opt out of), `version`, `help` | **Two commands are hidden from `voltro help` on purpose** and are not in the table: `prune-runtime ` (trims a deployed web tree's `node_modules` to the reachable runtime set — the standalone Dockerfiles run it for you) and `_apply-codemods` (the re-exec target `voltro update` uses to run the target version's codemods). Both are dispatchable; neither is something you invoke directly. Each command takes an optional path argument (the app directory) — defaults to `.` when run from inside an app. `voltro init` initialises the current directory as a workspace root — `pnpm-workspace.yaml`, a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore` and `git init`, idempotently and without scaffolding any apps (`voltro create-project ` does that, and bootstraps the same root when there isn't one). `voltro secret generate [purpose]` prints a cryptographically strong secret — with a purpose (`data-transfer`, `session`, `bundle-key`, `field-encryption`, `storage`, `inspect`) it emits the correct env var + length/format as a paste-ready `NAME=value` (`voltro secret list` shows them all); with no purpose, a generic base64url secret. `voltro telemetry` reports that Voltro collects none. `voltro deploy` shows the deploy paths — self-host via a [baseline](/docs/deployment/self-hosting) + CI, managed via the control-plane client `voltro cloud` (managed cloud deploy is coming soon — see [Voltro Cloud](/docs/deployment/voltro-cloud)), individual [serverless functions](/docs/deployment/serverless-functions) (`voltro serverless` → self-hosted Node, or Cloudflare / Scaleway), or a [static site](/docs/deployment/static-sites) (`voltro static` → Cloudflare Pages / S3 / Netlify). ## Help + version `voltro help` prints the command list; `voltro version` prints the CLI version. Both are also reachable as bare flags — `voltro --help` / `-h` and `voltro --version` / `-v` — handled by the dispatcher before it looks for a subcommand. **Per-command help** is the useful one. `voltro --help` (equivalently `voltro help `) prints that command's usage line, its flags, the environment variables that change what it does, and worked examples: ```bash voltro dev --help ``` ```text voltro dev — Start the local development server (auto-discovers routes / mutations). Usage voltro dev [app] Examples voltro dev boot the app in the current directory voltro dev apps/acme/api boot a specific app Environment PORT override the port from app.config.ts WATCH=0 run the server directly, with no file-watching supervisor WATCH_POLL=1 poll instead of using native FS events (bind-mounts: k8s hostPath / Docker) … ``` `--help` never runs the command. A command with subcommands of its own (`db`, `cloud`, `workflows`, `inspect`, `update`, …) prints its own richer page instead. ## Startup The CLI loads a command's implementation only when you dispatch it, so `voltro version`, `voltro info` and `voltro new` do not pay for the dev server, the build toolchain or the runtime. The same applies to the `voltro dev` supervisor's respawned child on every save. The CLI's first line is its own — no Node warnings ahead of it. ## Common per-command flags There is no universal global-flag layer; flags are per-command. The ones that recur: | Flag | Where it applies | |---|---| | `--format pretty\|json` | `logs`, `traces`, `inspect`, `cluster`, `workflows` — machine-readable output. | | `--no-color` | `logs`, `traces` — strip ANSI codes when piping to a file. | | `--process ` | `logs`, `traces`, `inspect`, `cluster` — narrow to one running process. | | `--force` | `agents-md` — overwrite existing files. | Commands like `build` / `start` / `migrate` / `codegen` parse no flags at all — only an optional path. Check each command's page for its real surface. ## Common env vars The framework reads more than a hundred distinct `VOLTRO_*` / `DB_*` / `PG_*` variables across its packages, so this is **not** the full set and could not usefully be — it is the ones you reach for. Each subsystem's page carries its own; the complete transport-security and connection lists live in [Production hardening](/docs/deployment/production-hardening) and [Security](/docs/security/overview). | Var | Effect | |---|---| | `NODE_ENV` | `production` / `development` / `test`. Affects defaults across many commands. | | `DB_DIALECT` | `postgres` *(default)* / `mysql` / `mariadb` / `mssql` / `sqlite` / `turso` / `memory`. Picks the SQL backend. | | `STORE` | `memory` / `postgres` — alternate data-store selector (resolution order: `DB_DIALECT` → `STORE` → `app.config.ts`). | | `WATCH` | `0` / `1`. Toggle filesystem watch in `voltro dev`. | | `VOLTRO_DASHBOARD` | `off` to disable the auto-launched dashboard. | | `VOLTRO_LOG_FORMAT` | `pretty` / `json`. Force the logger's output format. | | `VOLTRO_LOG_LEVEL` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. | | `VOLTRO_INSPECT` | `off` to disable the `/_voltro/inspect/*` HTTP endpoints. | | `VOLTRO_INSPECT_TOKEN` | Bearer for the inspect surface. **Fail-closed:** unset → every request is `401`. `voltro dev` mints one per project; `voltro serve` / `voltro start` mint nothing, so a public deploy is closed by default (set it explicitly to open the surface). | | `VOLTRO_INSPECT_ALLOWED_HOSTS` | Extra `Host` names allowed to reach the **dev** inspect surface, past its DNS-rebinding guard (comma/space-separated). Loopback names + IP literals are always allowed; any other domain name is refused unless listed here — the api counterpart of vite's `allowedHosts`. | | `DB_URL` | Database connection string (falls back to `DB_PRIMARY_URL`; or the discrete `DB_*` / `PG_*` fields). | | `DB_ACQUIRE_TIMEOUT_MS` | How long a request may wait for a free pooled connection before failing (default `10000`; `0` restores the driver's own unbounded wait). Read on every command and every dialect that can bound it. `DB_ACQUIRE_QUEUE_LIMIT` is its mysql/mariadb counterpart and is deliberately **unset** by default. | | `VOLTRO_SESSION_SECRET` | Session-cookie signing secret (`@voltro/plugin-auth`). Rotate with zero downtime: move the old value to `VOLTRO_SESSION_SECRET_PREVIOUS` for one session lifetime — cookies signed with either secret keep verifying, and previous-key cookies are re-issued under the new one. | | `VOLTRO_DATA_TRANSFER_SECRET` | Gates the prod data-transfer endpoints (`POST /_voltro/admin/{export,import}`); ≥16 chars or the routes don't mount. | | `VOLTRO_BUNDLE_KEY` | Passphrase for `.vbundle` export encryption (`voltro data export --encrypt`). A DEDICATED key, not the transfer secret. | | `VOLTRO_FIELD_ENCRYPTION_KEY` | Key for `.encrypted()` columns (`governancePlugin({ fieldEncryption: true })`) — a passphrase or a raw 64-hex AES-256 key. | | `VOLTRO_STORAGE_SECRET` | Signs storage grant tokens (private files); falls back to the session secret if unset. | | `AI_PROVIDER` / `AI_MODEL` / `AI_API_KEY` | Per-provider AI config. | ### Transport security — the overrides on by default since 0.34.0 The api listener's cross-site check, proxy policy and security headers are **on by default** and configured in `app.config.ts`'s `security` block. Each has an env override, resolved identically under `dev` and `serve`, with the explicit config value always winning: | Var | Effect | |---|---| | `VOLTRO_ORIGIN_GUARD` | `off` disables the cross-site origin check. Anything else leaves the default `same-origin`. | | `VOLTRO_ALLOWED_ORIGINS` | Comma-separated origins allowed past that check — what a web app on a different origin than the api needs. | | `VOLTRO_TRUSTED_PROXIES` | Which hops may set `x-forwarded-for` / `x-forwarded-proto`: a comma-separated CIDR/IP list, `private`, `*` (trust the leftmost token), or a hop **count** (`2`). **Unset means the header is ignored entirely** and the socket address wins — set it if you run behind an ingress AND rate-limit or audit per IP. | | `VOLTRO_SECURITY_HEADERS` | `off` / `default` / `strict` — the whole header bundle's mode. | | `VOLTRO_CSP` | Content-Security-Policy for non-HTML api responses. `off` drops just this one. | | `VOLTRO_CSP_HTML` | CSP for HTML responses (under `strict` it defaults to the same policy as `VOLTRO_CSP`). `off` drops just this one. | | `VOLTRO_HSTS` | `Strict-Transport-Security` value. `off` drops just this one. | | `VOLTRO_MAX_RPC_BODY_BYTES` | Cap on the buffered `POST /rpc` JSON body (default 8 MiB) — an oversized body is refused `413` and never buffered past the cap. File uploads ride plugin routes with their own limits. | | `VOLTRO_MAX_BODY_BYTES` | Cap on every OTHER body read — plugin HTTP routes, REST routes, incoming webhooks (default 8 MiB, matching the rpc cap). The config-file spelling is `http.maxBodyBytes` in `app.config.ts`; per-route overrides (`defineRestRoute({ maxBodyBytes })`, a webhook handler's `maxBodyBytes`) win over both. Oversize is `413` for `Content-Length` and chunked alike. | Response compression for the buffered non-rpc surfaces (and `voltro start`'s HTML) is configured in the same `http:` block — `http.compression.{enabled,minBytes}` (default on, 1 KiB threshold; `POST /rpc` is never compressed). Details + the BREACH reasoning: [Security → compression](/docs/security/overview#response-compression--and-where-breach-sits). Generate any of the secret vars above with `voltro secret generate ` (see [`secret`](#command-quick-reference)) — it picks the right length and format. A lower environment's secrets must always differ from production's. ## Workflow patterns ### "I'm starting a new project" ```bash mkdir acme && cd acme pnpx voltro create-project acme --api api-backend --web frontend-landing pnpm install pnpm dev # pnpm -r --parallel dev — voltro dev in every app at once ``` ### "I want to add a docs site to my existing project" ```bash voltro add-app docs --template frontend-docs --to acme pnpm install # picks up the new app's deps pnpm dev # the new app joins the parallel boot automatically ``` ### "I changed my schema and want to apply it" ```bash voltro db plan # diff declared schema vs live, color-coded # review the plan voltro db apply # execute it (dev) # `voltro migrate` is an alias of `db apply` — same differ, shorter name (CI / ops) ``` ### "I want to encrypt a column that already has rows in it" Turning on `.encrypted()` needs two things: the cipher, and a migration of the rows that are already there. The second has a command — it is easy to miss, because nothing about a schema change suggests a data pass is owed. ```bash voltro db scan-credentials # find plaintext secrets, column by column voltro db encrypt-column users.apiToken --dry-run voltro db encrypt-column users.apiToken --yes ``` `--key-env` names the key variable if it is not the default; the key must be the SAME one the app runs with, or the rows come back undecryptable. `voltro db` with no subcommand prints the full list. ### "I want a clean rebuild" ```bash voltro codegen # rewrite the generated rpc group + .framework/* voltro build # vite build + SSG pre-render voltro start # production server ``` ### "Scaffold a new primitive the right way" `voltro new ` writes the correct file convention(s) so you don't learn the descriptor/executor split or the browser-safe boundary from a boot-time error. It refuses to overwrite an existing file unless you pass `--force`. ```bash voltro new query notes.list # notes.list.query.ts + notes.list.query.server.ts voltro new mutation notes.create # descriptor + .server executor pair voltro new action notes.touch # descriptor + .server executor pair voltro new workflow orders.fulfill # .workflow.tsx descriptor + .workflow.server.tsx executor voltro new page about # src-pages page.tsx under the name path voltro new query billing.summary --dir queries # write into a subdirectory ``` The descriptor half imports only `@voltro/protocol` (or `@voltro/workflow/define`) + `effect` — browser-safe by construction; the server graph lives in the paired `.server` file. Fill in the `TODO`s, then `voltro dev` discovers it. ### "Type-check before I commit" ```bash voltro typecheck # tsc --noEmit against ./tsconfig.json voltro typecheck apps/api # a specific app voltro typecheck --project tsconfig.build.json ``` It runs the **app's own** TypeScript (a `tsc --noEmit`), so "green" means tests AND types. Any flag it doesn't own passes straight through to `tsc`. ### "What versions am I actually running?" ```bash voltro info # CLI, node, package manager, dialect + @voltro/* versions voltro info --json # machine-readable; exits 1 on version skew ``` `@voltro/*` ship in lockstep, so a mismatch (e.g. `@voltro/database` a minor behind `@voltro/runtime`) means an untested graph. `voltro info` flags it and `voltro update` realigns everything. ### "Something's wrong — inspect what's running" ```bash voltro inspect rpc # discovered procedures + workflows voltro inspect routes # web page tree (web apps) voltro inspect metrics # request rates, p95 latencies voltro logs --tail 100 # recent structured logs voltro traces --errors # traces with an errored span voltro workflows list # recent workflow runs ``` ### "Did my edit break a binding?" `voltro check` runs blast-radius checks over your app's typed graph — dangling `source` / `target` tables, scopes no role grants, unguarded mutations, broken route bindings, orphan tables — at edit time instead of at runtime. `--json` emits LLM-shaped diagnostics so a coding agent can fix-and-repeat; `--diff` previews the blast radius of a removal BEFORE you apply it. It prefers a running api (its manifest is ground truth, including live table introspection). **With none reachable it assembles the same graph from source**, so it works as a pre-commit hook or a CI gate without a second terminal — `--offline` forces that path. ```bash voltro check # running api if there is one, else from source voltro check --offline # never contact a server — the CI form voltro check --url https://api.example.com # a DEPLOYED app voltro check --json # { ok, diagnostics: [{ rule, node, breaks, fix }] } voltro check --diff removeTable:todos # what a proposed removal would break, before applying ``` `rbac/unknown-scope` needs a declared scope vocabulary to compare against — `rbacPlugin({ roles })` publishes one automatically. It catches a guard requiring a scope no role grants, which makes that procedure permanently and silently uncallable. (With a custom `resolvePermissions` the vocabulary isn't exhaustive, so the rule stays quiet rather than flagging correct code.) `rbac/unenforced-scope` is the same registry read in the other direction: a scope a role GRANTS that no handler ever guards on. That direction has no artefact to inspect — you cannot grep for an authorization check that was never written, which is exactly why it survives review. One app modelled `api-keys:write` in its role catalogue, complete and reviewed, and no handler checked it: any member could mint a shared credential, and nothing failed. Tests pass when an authorization check is missing. It is a **warning**, because three innocent explanations exist: a plugin route enforces it internally (the graph cannot see inside a plugin), a REST route carries its own guards, or it is a UI-affordance scope that `useCan` reads to hide a button and no server check backs on purpose. All three are fine. Not knowing which is not. `rbac/unguarded-mutation` flags a mutation that declares neither a guard nor an `openAccess:` reason. It skips **`internal: true`** procedures: those are in no rpc group and on no route, so "any caller who can reach the rpc surface" names a surface that does not exist — and neither remedy applies either, since a guard would protect nothing and `openAccess` is refused outright on an internal descriptor. This is the same `isWireReachable` predicate the boot access gate and all three rpc-group assemblies use, so `check` and `voltro doctor` cannot answer the question differently. A manifest that does not carry the field at all — an api older than it — is read as *reachable*, not as internal. The rule stays loud rather than going quiet on the apps least able to notice. #### Declared vs OBSERVED — reconciled against reality A query's `source` and a mutation's `targets` are not documentation: the framework routes optimistic patches and decides which subscriptions a write invalidates from them. A wrong declaration is a live, user-visible bug that nothing type-checks — the mutation succeeds, the write lands, and the wrong list fails to update. `voltro dev` records what each procedure ACTUALLY touched, into `app.graph.observed.generated.json` (gitignored automatically). When that file is present, `check` diffs it against the declarations: ``` observed: 12/34 procedures exercised (35%) 1 declared/observed mismatch among the 12 that ran mutation(orders.place) (api/orders/place.mutation.ts) writes 'inventory' (update) but declares no target for it subscriptions on that table are not invalidated by this mutation fix: add { table: 'inventory', op: 'update' } to this procedure's targets 20 never ran — no observation exists, so nothing is claimed about them 2 ran with no table access recorded — indistinguishable from touching nothing, so nothing is claimed about them either ``` Four things about that output are deliberate: - **Coverage comes first.** Three findings at 8% coverage and three at 95% are different claims. Hiding the denominator is how a check starts overstating what it knows. - **Every result line carries the count it is a result about.** `1 mismatch among the 12 that ran` — never a bare verdict. A sentence that still reads as a conclusion once it is cut out of this block will eventually be cut out of it, and quoted as a clean bill of health for a surface nobody measured. - **The counts partition the declared set — they add up to the total, always.** There are two ways to say nothing about a procedure, and both get a line: it never ran, or it ran and no table access was recorded for it. A procedure that appeared in no line at all would be indistinguishable from a defect in `check` itself, so the two kinds of blindness are named separately and never folded into the findings. - **Observed diagnostics never fail the build.** An observation is evidence about the runs that happened, not a proof about the ones that didn't, and `check`'s exit code gates CI. They are always warnings. A fifth thing is not visible in that output and matters more than any of the four: **the recorder only knows what ran.** A boot is not a run. An idle dev instance that started, served nothing and stopped produces ``` observed: 0/34 procedures exercised (0%) nothing was compared — a declaration is only checked against a procedure that RAN 34 never ran — no observation exists, so nothing is claimed about them ``` Note what that is NOT: it is not "no mismatches found". At zero coverage there is no result to report, so the section reports the absence of the comparison instead. The honest answer is also a useless one — it says nothing about any of the surface. If you want this as a CI gate, the recording pass has to be a run that actually *calls* the procedures. `voltro e2e` is one: it spawns `voltro dev` for the api, which turns recording on, and then drives the specs. A harness of your own that boots the app in its own process needs `VOLTRO_OBSERVE_GRAPH=1` set before anything is imported. Either way, booting the app and then running `check` measures nothing, and the report will not pretend otherwise. It is still worth wiring up at low coverage, because the findings are per procedure and do not need company. One deployment had exactly one procedure observed, and that one produced a real defect: a mutation upserting `push_subscriptions` with no declared target while two queries read that table as their `source`, so a registered device never appeared in any running subscription. No file → the section is skipped silently. This is not derived by parsing your handlers: a static pass over code that reaches the store through shared helpers, behind conditionals, has a long tail of both false positives and false negatives — and a check that is *sometimes* wrong is one people stop reading. #### Declared vs LIVE — against a running server When `check` runs against a live api (a local `voltro dev`, or a deployed one via `--url`), it also diffs the tags your source declares — plugin routes included — against the server's actual rpc registry: ``` declared vs live: 2 of 214 source-declared tags are NOT registered on the server ⚠ presence.heartbeat — a generated client calls this and gets "Unknown request tag" ⚠ presence.list — a generated client calls this and gets "Unknown request tag" fix: if the server runs older code, redeploy; if it is current, plugin route registration was dropped — check the boot line "plugin routes registered" ``` Only the source→live direction is a finding — a tag the server carries that your source does not declare is normal runtime synthesis (agents, undo, approvals). This exists because exactly that gap has shipped once: every plugin-contributed procedure dead under `voltro serve`, with nothing anywhere saying so — the only evidence was a `Defect` frame in the browser console of whoever happened to look. (That registration defect is fixed; the diff is the runtime backstop for the next one, e.g. a stale deploy.) The server now also logs every `Defect` frame it sends (`rpc defect sent to client`), so an unknown tag is an operator-visible event rather than a client-only one. The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_voltro/inspect/rpc | jq` (there is no `/_voltro/inspect/queries` endpoint; it's `rpc` for procedures, `routes` for the web page tree, `subscriptions` for active subscribers). ## Where to read next - [Scaffolding](/docs/cli/scaffolding) — start + grow a project - [Dev](/docs/cli/dev) — what happens during `voltro dev` - [Build & start](/docs/cli/build-and-start) — production paths - [Migrate](/docs/cli/migrate) — schema changes end-to-end - [Update](/docs/cli/update) — upgrade the framework + run codemods - [Inspect & test](/docs/cli/inspect) — debugging + harness --- ## Scaffolding _init, create-project, add-app, list-templates — boot new code with the framework's conventions baked in._ The scaffolder generates new projects + new apps from templates. Each template is a dogfooded reference; what you scaffold is the same shape the Voltro Cloud team uses. ## `voltro init` ```bash voltro init # takes no arguments — it initialises the CURRENT directory ``` Turns the directory you are standing in into a **Voltro workspace root**, and scaffolds no apps at all. That is the whole distinction from `create-project`: `init` prepares the root, `create-project` fills it. They share one implementation (`ensureWorkspaceRoot`), so a greenfield `create-project` needs no separate `init` — it bootstraps the same root when there isn't one. What it writes, all of it **idempotent and additive**: | File | Behaviour | |---|---| | `pnpm-workspace.yaml` | Written only when the walk up finds no workspace at all. | | `package.json` (root) | Created when missing — `private`, `type: 'module'`, node/pnpm engines, the detected `packageManager`, the four scripts, `typescript` + `@types/node`. When it exists, only the **missing** keys are filled in; a script or a version range you already declared is never rewritten. | | `tsconfig.base.json` | Written when missing. Every app + package tsconfig the framework generates extends this exact path, so `tsc` fails before it reads your code without it. | | `.gitignore` | Created when missing; otherwise only the entries it does not already cover are appended. Includes `.env.local` — where `voltro dev` mints per-project secrets, and which must never be committed. | | `git init` | Only when nothing at or above the directory is already a git working tree. | The four root scripts are the workspace fan-outs: ```json { "dev": "pnpm -r --parallel dev", "build": "pnpm -r build", "test": "pnpm -r test", "typecheck": "pnpm -r typecheck" } ``` Two refusals, both deliberate: - **A positional argument is an error** (`init takes no arguments — it initialises the current directory`), with a hint pointing at `voltro create-project `. `voltro init acme` reads like "make me a project called acme", and it is not that command. - **It will not nest a second root inside an existing pnpm workspace.** If an ancestor already has a `pnpm-workspace.yaml`, it names that root and tells you to run `create-project` from there instead. A second run on an already-initialised root prints `is already a Voltro workspace root — nothing to do.` ## `create-project` ```bash voltro create-project [flags] ``` Bootstraps a new project under `apps//` with selected templates. | Flag | Default | Notes | |---|---|---| | `--api ` | prompts, then `api-backend` | API template. Use `none` for web-only projects. Also accepts `--api=`. | | `--web ` | prompts, then `frontend-blank` | Web template. Use `none` for api-only. Also accepts `--web=`. | | `--cache=redis` | off | Wire the Redis cache backend at scaffold time — sets `cache: 'redis'` in `app.config.ts` and injects the `redis` service + `CACHE_*` env into the active baseline's infra. | | `--baseline=` | prompts (or skip) | Deploy baseline to scaffold (`bare` / `compose` / `helm`). Without it, the interactive prompt lists the available ids. | | `--port-range -` | `5190-5199` | Port range for web apps in this project. Persisted in `project.json`. Also accepts `:` / `..` separators. | | `--no-input` | false | Skip prompts; suitable for CI / scripted scaffolding. | | `--no-register` | false | Do not contact the Voltro Cloud control plane. See [registration](#project-registration) below. | What it does: 1. Validates the name (camelCase or kebab-case, no `_`, no leading digits). 2. Picks the next free port from `--port-range`. 3. Renders templates into `apps//api/` + `apps//web/`, substituting `{{appName}}`, `{{projectName}}`, `{{port}}` placeholders. 4. Writes `apps//project.json` recording the project's port range + app list. 5. Updates `pnpm-workspace.yaml` to include the new project's apps. 6. Seeds the **agent guide** for each app (see below). After scaffolding: ```bash cd pnpm install pnpm dev ``` ### Project registration `create-project` and `add-app` finish by registering the project with the Voltro Cloud control plane. This is how **self-hosted** use is counted, and the Terms of Service ask for projects and apps to be registered. It is worth knowing exactly when it happens and what it involves, because it is part of your first command. **If you are not logged in, nothing is sent.** No network call is attempted at all, and the scaffolder says so: ```text → cloud registration: skipped — not logged in, so nothing was sent from this machine. Registration is how SELF-HOSTED use is counted; the Voltro Cloud Terms of Service ask for projects and apps to be registered once you have an account. Register later: voltro cloud login then voltro cloud scan Never ask again: scaffold with --no-register ``` **If you are logged in**, it prints the destination and the contents before the call: ```text → registering project 'acme' with https://cloud.voltro.dev (self-hosted usage tracking, ToS-governed) Sends: the project slug, and per app its name, kind, framework version and the NAMES of declared primitives (queries, mutations, tables, plugins, …) plus a page count. Never sends: source code, row data, environment values or secrets. Skip with --no-register. ``` Pass `--no-register` to skip it entirely — appropriate for offline work, CI, or while evaluating. You can register later with `voltro cloud login` followed by `voltro cloud scan`. This is the only network call the CLI makes on its own behalf; `voltro telemetry` reports the rest of the picture (the framework collects nothing). ### The seeded agent guide `create-project` / `add-app` (and `voltro dev` on first boot) seed a guide that teaches AI coding agents the framework's conventions. It's generated, not a monolith: - **Root `AGENTS.md` + `CLAUDE.md`** — a slim always-loaded core (mental model, the primitive rubric, file conventions, the browser/server boundary, naming, anti-patterns) plus an **index** listing the workspace's installed plugins and linking the deep, on-demand topic docs. - **Nested `AGENTS.md` + `CLAUDE.md` per app area** (`api/`, `api/database/`, `web/`) — type-specific notes an agent loads only when working there; a scaffolded app's file points at its template's doc. - **`.claude/skills/*`** — Claude Code skills for the common how-tos. Existing files are never overwritten; `voltro agents-md --force` refreshes them. Protect a hand-maintained file from `--force` with a `voltro:agents-md:keep` HTML comment at the top. ## `add-app` ```bash voltro add-app --template [--to ] ``` Adds another app to an existing project. Works for any kind — `api`, `web`, or `serverless`. A `web` app gets the next free port from the project's range; a `serverless` app has no server, so it gets no port (run it with `voltro serverless`). | Flag | Default | Notes | |---|---|---| | `--template ` | *(required)* | Template to scaffold. `voltro list-templates` for the catalogue. | | `--to ` | auto-detected | Target project. Required when >1 project exists. | What it does: 1. Reads the target project's `project.json` for the port range. 2. Picks the next free port from the range (rejects if the range is exhausted). 3. Renders the template into `apps///`. 4. Updates `project.json` to record the new app. Example: ```bash voltro add-app docs --template frontend-docs --to acme voltro add-app admin --template frontend-blank --to acme ``` ## `list-templates` ```bash voltro list-templates ``` Prints the catalogue. Templates come in three **kinds** — `api`, `web`, and `serverless` (a bundle of [`*.serverless.ts`](/docs/deployment/serverless-functions) functions deployed on their own): ``` id kind summary -------------------- ---------- -------------------------------------------- api-backend api Minimal Voltro backend (schema + query + mutation). api-backend-mail api + @voltro/plugin-mail + a React-Email template. api-backend-storage api + @voltro/plugin-storage (public + private objects). api-backend-mariadb api MariaDB binlog CDC + storage, tenant-aware. api-durable api Durable + reactive: workflow, trigger, cron, subscriber, aggregate. api-ai api RAG agent: vectorEmbedding + search tool + model loop. api-data-advanced api Advanced schema: relations, FTS, dbEnum, encrypted, caching. api-auth api Real user auth: plugin-auth sessions + cookie strategy. api-rest api Public REST API: defineRestRoute + plugin-openapi (Swagger). api-saas api SaaS bundle: billing + notifications + analytics + presence. api-observability api Metrics + errors + tracing + a @voltro/testing unit test. api-webhooks api First-class webhooks: signature-verified incoming + outgoing emit. frontend-blank web Empty React + layout shell. frontend-app web Fullstack reactive loop — wired to an api (useSubscription + useMutation). frontend-landing web Static marketing page — zero JS on the wire. frontend-static-blog web SSG blog: getStaticPaths + islands + per-post meta. frontend-spa web Pure client-rendered SPA (no backend, no SSR). frontend-ssr web Server-rendered pages: ssr + isr (revalidate, swr). frontend-contact web Static page + a serverless email form. frontend-docs web Catch-all docs site with i18n. changelog web Release-notes site (MDX + RSS). edge-functions serverless A library of *.serverless.ts functions (8 types). ``` See the [App templates catalogue](/docs/reference/templates) for what each demonstrates + a picks-for table. For programmatic use, add `--json`: ```bash voltro list-templates --json ``` ## `generate` (AI app-builder) `voltro generate ""` turns a natural-language prompt into framework artifacts — queries, mutations, tables — **constrained to what your app can actually express**. It reads the committed capability manifest (`app.manifest.generated.json`, emitted by `voltro dev`) as the grammar, asks the model for an app graph + the files that realise it, and gates every candidate through the real `voltro check` before anything is written. A structurally-invalid proposal is re-prompted with its diagnostics (the errors-as-LLM-API loop), never written. ```bash voltro generate "add a comments table with a list + create" # dry-run: prints the proposal voltro generate "add a comments table with a list + create" --write # applies the accepted artifacts ``` **Dry-run by default** — artifacts hit disk only with `--write`, and only ever a proposal that passed `voltro check`. Generation is also capped (file count + total bytes). Run `voltro dev` once first so the manifest exists. > Requires a model provider (`AI_PROVIDER` / `AI_MODEL` + the provider key, same > as [agents](/docs/ai/agents)). The cloud dashboard exposes the same builder for > proposal review (`apps.generateAppGraph`), behind the `aiBuilder` flag (off by > default → typed `FlagDisabled`). ## Template tokens Templates contain `{{token}}` placeholders that the scaffolder substitutes: | Token | Example value | |---|---| | `{{appName}}` | `dashboard` | | `{{capAppName}}` | `Dashboard` | | `{{projectName}}` | `acme` | | `{{capProjectName}}` | `Acme` | | `{{port}}` | `5191` | Apply across both file content AND file/directory names — a template file named `{{appName}}.entity.ts` or a dir `pages/{{appNameSnake}}/` renders to your project's names. When writing your own template, use these freely; the substitution is global. ## Writing a custom template Drop a directory into `voltro-templates/apps//`: ``` voltro-templates/apps/my-template/ ├── template.json ├── package.json ├── app.config.ts ├── src/ │ ├── pages/ │ │ └── index.tsx │ └── … └── tsconfig.json ``` `template.json` declares the metadata: ```json { "id": "my-template", "kind": "web", "summary": "My custom template — does X.", "tags": ["marketing", "minimal"] } ``` `kind` is one of `api` / `web` / `serverless`. A `serverless` template ships a `functions/` dir of `*.serverless.ts` files (no `app.config.ts`, no pages) and is added with `voltro add-app`. Now `voltro list-templates` shows it; `voltro create-project --web my-template` (or `--api`) uses it, and any kind is added with `voltro add-app --template my-template`. For private templates (in your own repo), set `VOLTRO_TEMPLATES_DIR=/path/to/my/templates` and the CLI resolves templates from there instead of the default location. Point it at the templates **root** — the CLI appends `apps/`, so your templates live at `/path/to/my/templates/apps//`. When the variable is set it is authoritative: the CLI does not fall back to the bundled templates. ## Idempotency The scaffolder refuses to overwrite an existing directory: ```bash voltro create-project acme # fails if apps/acme/ exists ``` To force, delete the directory first. The framework intentionally doesn't have a `--force` flag — accidental data loss is the kind of thing that happens once + ruins your day. ## Anti-patterns - **Scaffolding into a non-Voltro repo.** The scaffolder writes to `apps//` + expects a `pnpm-workspace.yaml`. Without one, `pnpm install` doesn't link workspace packages. - **Renaming the scaffolded app directory afterwards.** `project.json` records the path; rename invalidates discovery. Either re-scaffold with the right name, or update `project.json` + every cross-package import by hand. - **Editing the templates dir directly to "fix" a scaffolded app.** Templates are starting points. After scaffolding, the app is yours — edit IT, not the template (unless the template itself has a bug). ## See also - [App templates](/docs/reference/templates) — the catalogue with picks-for table - [Dev](/docs/cli/dev) — what `voltro dev` does with the scaffolded app --- ## Dev _voltro dev, codegen, agents-md — what runs during local development and the env flags that shape it._ `voltro dev` is the day-to-day command. It runs different machinery for api vs web apps but the contract is the same: edit a file, the right thing happens. ### Running `voltro dev` in a container If your dev pod runs as root with the host workspace bind-mounted, everything the framework generates would otherwise land `root:root` inside your own tree — and on the host `voltro build` then fails on its own output: ``` EACCES: permission denied, open '…/apps/display/.framework/index.html' ``` `voltro dev` and `voltro build` hand their generated output (`.framework`, `.env.local`, every `*.generated.*`) to whoever owns the app root, and warn loudly when they cannot. Only generated state — the framework never takes ownership of a file you wrote. The cleaner fix is on your side and worth doing anyway: start the container as the workspace owner, `docker run --user $(id -u):$(id -g)`. Then nothing needs handing over at all. ### What the boot tells you Three checks run at boot and print one line each when they have something to say — never fatal, and silent when the answer is fine: - **A reactive table with no change trigger** (postgres). The schema fingerprint covers columns, not triggers, so a restored dump or a hand-run `DROP TRIGGER` leaves the schema "up to date" and the subscription silently not reaching other instances. The reverse is reported too: a `.nonReactive()` table still carrying a trigger pays `REPLICA IDENTITY FULL` and a NOTIFY per write for nothing. - **A `.nonReactive()` table that a query reads.** That subscription will never fire — first snapshot, then silence forever. - **`apiKeys: true` with no `apikeys:issue:*` scope declared.** The capability is on and reachable by nobody; every issue request fails its guard. `voltro doctor` adds a fourth, over your source: its **authz scan** asks of every executor — queries included — whether it references an access check at all, and lists the ones that reference none. It learns your own `require*` / `assert*` guard names, so it does not report the call sites of guards you already wrote. See [the authz scan](./build-and-start.md). ### When the database is not reachable A refused, unresolvable or rejected database connection is reported as a condition with a fix, not as a framework crash: ```text voltro: the database is not reachable at 127.0.0.1:5432 (ECONNREFUSED). No database is configured — none of DB_URL / DB_HOST / PG_HOST is set in the environment or in a loaded `.env`, so the framework used its local dev default. Either start one: pnpm db:up (if your project ships a compose file) or point at your own: DB_URL=postgres://user:pass@host:5432/dbname — put it in `.env` next to app.config.ts, not just in one shell. Re-run with --debug for the full stack. ``` When a variable **is** set, the message names it and says the address resolved and nothing answered there — which is a different problem from "is postgres running", and points you at the container, VPN or firewall instead. A server that answers and rejects you (wrong password, missing database) is reported as its own case, because the fix is different again. Pass `--debug` (or set `VOLTRO_DEBUG=1`) to get the full Effect stack instead. ## `voltro dev ` ```bash voltro dev . # current dir voltro dev apps/acme/api # explicit path ``` ### What it does for an api app 1. Reads `app.config.ts`. Bails if not `type: 'api'`. 2. Walks `queries/`, `mutations/`, `workflows/`, etc. for the discovery patterns. 3. Generates `.framework/rpcGroup.generated.ts` exporting a typed client. 4. Starts the RPC over WebSocket server on `:4000` (override with `PORT`, or set `port:` in `app.config.ts`). 5. Watches every discovery-matching file. On save: - File added/removed → regen the discovery → restart the api process. - File modified → reload the module → fire `hmr update` to connected clients. 6. Resolves `STORE=memory` (in-memory store) or `STORE=postgres` (real DB). 7. Auto-launches the inspect dashboard on `:5179` (unless `VOLTRO_DASHBOARD=off`). ### What it does for a web app 1. Reads `app.config.ts`. Bails if not `type: 'web'`. 2. Walks `src/pages/` for queries + special files. 3. Generates `.framework/main.tsx`, `.framework/app.tsx`, `.framework/routeTable.ts`, `index.html`. 4. Starts Vite with the framework's plugin chain (React, Tailwind v4, page discovery, inspect, dashboard registry). 5. Binds to the configured port from `app.config.ts.port` (strict — fails on conflict). 6. Watches `src/`. On save, Vite HMR fires: - A page / layout **component** change → React Fast Refresh patches the live component in place; client state survives (see below). - A page-local **value export** (`const COLUMNS = [...]`) change → also a hot update, even in the same save as the JSX (see below). - A **server-read export** — `loader`, `renderMode`, `meta`, … — change → a full page reload, on purpose (see below). - CSS changes → swap stylesheets in place. - New page file → regen the entry files → reload the route tree. `renderMode: 'ssr'` pages compile on demand the first time each route is hit. To keep a burst of cold pages — several browser tabs, or a health-check sweep across many routes — from spiking memory, `voltro dev` compiles at most **4** of them at once and collapses duplicate concurrent requests for the same route into a single compile. Already-compiled (warm) pages are never throttled, so a hot app stays fully concurrent. Tune the cap with `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY` (below) — drop it on a low-memory box, raise it on a big machine. ### A failed server render fails the request If the server render throws, `voltro dev` answers **500** with the error and its stack, marks the response `x-voltro-rendered-by: ssr-dev-failed`, and logs it at `error`. It does **not** fall back to a client-rendered shell. That is deliberate, and it is the same outcome `voltro start` produces in production. A fallback would hand you a page that renders in the browser and a 500 in production from the identical code — and because an empty `
` is what a client-only app looks like, the usual conclusion is "the framework does not server-render", not "my page threw". The failure is loud so the cause is the thing you see. The practical consequence: anything that only misbehaves under `renderToPipeableStream` — a component that suspends with no `` boundary above it, a loader that throws, a hydration-unsafe value — surfaces in `voltro dev` at the moment you hit the route. **Suspending is fine here, and does not need a boundary you add.** A component that suspends during a streamed server render — a lazily-loaded translation catalog, a `React.lazy` component, `react-i18next` with `useSuspense: true` — renders normally: `renderToPipeableStream` treats the root as an implicit boundary, so a suspend delays the shell flush instead of failing. Measured, not assumed; a regression test pins it. Do **not** add a blanket `` at the root to "fix" a suspend. It makes things worse in a way that is hard to see: React downgrades an errored boundary to client rendering, so a page that THROWS starts answering 200 with `