01 · Getting started

Running the CLI

One command. A handful of prompts. A project that only ships the features you asked for.

npx create-orb@latest

That's it. The CLI greets you, asks where to put the project, walks through a short set of feature prompts, and scaffolds a fresh copy of the kit into the directory you picked.

Note

Nothing is written to disk until you confirm the summary at the end — a ^C before that point is a clean no-op.

What the prompts ask

Say "no" to a feature and the CLI omits every file, env var, permission, route, and database model tied to it — the scaffolded project only contains what you asked for.

Prompt	Default	What it controls
Teams + per-team PBAC	on	Nested team scope inside a workspace. Off = workspace-only roles.
Billing	on	Subscriptions, webhooks, customer portal. If on, you're also asked which provider — Stripe, Polar, or Dodo.
File uploads	on	UploadThing-backed avatars + image uploads.
Waitlist / private beta	off	Gates /onboarding behind an allowlist; POST /v1/waitlist still accepts submissions either way.
Realtime (WebSocket)	on	Presence, live updates, the /v1/ws endpoint.
Resend email adapter	on	Off ships the ConsoleMailer, which logs magic links to stdout.
OAuth (Google + Apple)	on	Off keeps magic-link-only sign-in.
Background jobs + cron	on	Provider-neutral queue. If on, you're asked whether to use `graphile-worker` or Upstash `QStash`.
Web framework	TanStack	Pick TanStack Start (Vite, :4001) or Next 16 App Router (:4003). The other app folder is removed.
ORM	Prisma	Pick Prisma (free default) or Drizzle (paid). The unchosen adapter, repositories, and migration tooling are removed.

Non-interactive mode

Every prompt has a corresponding flag, and --yes accepts every default. Useful for CI, scripted spin-ups, and regenerating the same variant over and over:

npx create-orb@latest ./my-app --yes \
  --no-teams \
  --billing-provider=polar \
  --framework=next \
  --jobs-provider=qstash

Run npx create-orb@latest --help for the full list of flags.

What actually happens

Template acquisition. The CLI either clones github.com/were-orbit/orbit-starter (default) or copies a local path you passed with --from. The target directory must be empty or not yet exist.
Strip pass. The CLI removes every file, code section, and dependency tied to a feature you turned off, then writes the slimmed-down project to disk.
Script repoint. If you picked Next, the CLI rewrites the root dev:web script to target @orbit/web-next and drops the stale dev:web-tanstack shortcut. TanStack is the no-op default.
Install (optional). npm install runs for you unless you pass --no-install.

Next steps

The CLI prints these at the end. Follow them in order:

ORM

cd my-app
npm install    # if you passed --no-install
cp apps/api/.env.example apps/api/.env   # fill in secrets
npm run prisma:migrate
npm run dev

Re-running the CLI

The CLI is one-shot: it scaffolds a new project, it doesn't patch an existing one. If you wish you'd kept billing on, it's easier to diff against a second scaffold than to rerun the tool against the same directory.

PreviousPrerequisites NextEnvironment variables