CLI Reference

Global flags

Flag	Description
`--verbose`	Print stack traces and detailed errors on failure
`-V, --version`	CLI version
`-h, --help`	Help for any command

Most write-capable commands also accept --dry-run to preview the diff without touching disk.

create (default)

Scaffold a new project.

npx create-turbo-stack [project-name] [--preset <url>] [--dry-run]

Option	Description
`--preset <url>`	Use a preset URL or file path
`--dry-run`	Print the file tree; write nothing

npx create-turbo-stack my-app
npx create-turbo-stack my-app --preset https://create-turbo-stack.dev/s/saas-starter.json

init

Adopt an existing Turborepo by analyzing it and persisting .turbo-stack.json.

npx create-turbo-stack init [path] [--force]

Option	Description
`--force`	Overwrite an existing `.turbo-stack.json`

After init, the rest of the toolchain (add, remove, switch, upgrade) becomes available.

add

Add an app, package, integration, or npm dependency.

npx create-turbo-stack add <type> [name] [--dry-run]

Type	Description
`app`	New workspace app — interactive
`package`	New workspace package — interactive
`integration`	Set / change a provider in a category — interactive
`dependency <pkg>`	Catalog-aware npm dep add (use `--to=<workspace>`)

npx create-turbo-stack add app
npx create-turbo-stack add dependency lodash --to=apps/web
npx create-turbo-stack add dependency vitest --to=packages/ui --dev

remove

Remove an app, package, or integration. Stale files are deleted, empty directories are pruned, .turbo-stack.json is rewritten.

npx create-turbo-stack remove <type> [name] [--dry-run]

Type	What gets removed
`app <name>`	`apps/<name>/`, app entry, deps that other apps no longer need
`package <name>`	`packages/<name>/`, every app's `consumes` reference
`integration <category>`	Provider files for that category, env vars, catalog entries

switch

Atomic provider swap — old files deleted, new files written, in one transaction.

npx create-turbo-stack switch <category> [value] [--dry-run]

npx create-turbo-stack switch db prisma          # was drizzle, becomes prisma
npx create-turbo-stack switch email nodemailer   # was resend, becomes nodemailer

upgrade

Migrate the project's preset to the current schema version. Walks the registered migration chain, validates the result, then re-applies the resolved file tree.

npx create-turbo-stack upgrade [--dry-run]

Idempotent. On a project already at the current version, it reports "nothing to do" and exits.

info

One-screen summary of the project's stack — schema version, basics, integrations, app/package counts. Read-only; safe in CI.

npx create-turbo-stack info [--json]

list

Every app type and integration provider currently registered (built-in plus plugins loaded from create-turbo-stack.json).

npx create-turbo-stack list [--json]

Environment + project sanity checks: Node version, package manager binaries, .turbo-stack.json validity, missing workspace directories, schema version drift. Exits non-zero on any fail-level finding — wire it into CI.

npx create-turbo-stack doctor [--json]

analyze

Reverse-engineer an existing Turborepo into a preset JSON without persisting state. Use init if you want to write .turbo-stack.json instead.

npx create-turbo-stack analyze [path] [--json] [--open-builder] [--diff <file>]

Option	Description
`--json`	Emit raw preset JSON to stdout
`--open-builder`	Open the analyzed preset in the web builder
`--diff <file>`	Compare with an existing preset file

preset

Save or validate a preset JSON.

npx create-turbo-stack preset save [file]
npx create-turbo-stack preset validate <file>

mcp

Start the Model Context Protocol server over stdio. Pin the project root with TURBO_STACK_ROOT=/path/to/project when launching from a client (Claude Desktop, Cursor) — otherwise the server uses the client's cwd, which is rarely your project.

TURBO_STACK_ROOT=/path/to/project npx create-turbo-stack mcp

Tools are prefixed with turbostack_ to avoid global namespace collisions on the client side.

Generated files at a glance

Location	Notable files
Root	`package.json` (catalog), `turbo.json`, `biome.json`, `.gitignore`, `.npmrc`, `.env.example`, `README.md`, `vitest.config.ts`, `.husky/pre-commit`, `.github/workflows/ci.yml`, `docker-compose.yml` (if DB)
Per Next.js app	`package.json`, `tsconfig.json`, `next.config.ts`, `vercel.json`, `src/app/{layout,page,error,not-found,loading}.tsx`, `src/app/{robots,sitemap,manifest}.ts`, `src/app/globals.css`, `instrumentation.ts` (if Sentry), `components.json` + `src/lib/utils.ts` (if shadcn), `src/i18n/{routing,request}.ts` + `messages/en.json` + `src/middleware.ts` (if i18n)
Per package	`package.json` (exports map + `catalog:`), `tsconfig.json`, `src/index.ts`
State	`.turbo-stack.json` — preset + catalog + cssSourceMap + autoPackages + cliVersion + generatedAt

On this page