CLI reference · create-bsv-app

Usage#

create-bsv-app [new|add] [directory] [options]

Run it with npx create-bsv-app@latest, pnpm create bsv-app, yarn create bsv-app or bun create bsv-app. Every argument is optional. Anything you don't pass is asked interactively, or with --yes, takes its default.

Flags#

Flag	Default	Mode	Description
`new \| add`	inferred	both	Mode as a positional subcommand. Omit it and the CLI infers: a valid `bsv-scaffold.json` or a detected React/Express project means `add`, anything else means `new`.
`[directory]`	`.`	both	Target directory as a positional argument. Same as `--dir`.
`--dir <path>`	`.`	both	Target directory. In `new` mode it must be empty (a lone `.git` or `bsv-scaffold.json` is allowed).
`--starter <id>`	`custom`	new	Starter from the catalogue. Repository starters ignore stack and capability flags.
`--name <name>`	directory name	new	Project name passed to the generators and recorded in the manifest.
`--frontend <react\|none>`	`none`	new	Frontend for the `custom` starter. `react` runs create-vite under the hood.
`--backend <express\|none>`	`none`	new	Backend for the `custom` starter. `express` writes a lean TypeScript Express app.
`--variant <name>`	`react-ts`	new	create-vite template variant for the frontend.
`--capabilities <a,b,c>`	`wallet-connect`	both	Comma-separated capability ids. `new` mode always adds `wallet-connect`; dependencies are expanded for you.
`--bsv-dir <path>`	`src/bsv`	both	Where capability helper files go, relative to each target (`client/`, `server/`).
`--package-manager <npm\|pnpm\|yarn\|bun>`	`npm`	new	Used for the generators, the install, and the root runner. Not auto-detected: pass it if you don't use npm.
`--network <main\|test\|ttn>`	`test`	new	Default BSV network baked into the generated config. `ttn` is Teratestnet.
`--yes`	off	both	Non-interactive. Resolves everything from flags (plus an existing manifest) and never prompts.
`--file <path>`	none	both	Read a complete ProjectConfig from JSON and skip prompts. `--mode` overrides the file's `mode`.
`--mode <new\|add>`	inferred	both	Force the mode instead of inferring it.
`--ui`	off	both	Open the browser configurator on `127.0.0.1`. Single use: it shuts down after you press Generate.
`--glue / --no-glue`	glue on	new	Auto-wire providers into `main.tsx`, routes into `App.tsx`, and routes into the server. With `--no-glue`, files are still written and `AGENTS.md` prints the snippets to paste.
`--install / --skip-install`	install on	both	Install dependencies before exiting. Skip when CI or another tool installs.
`--force`	off	add	Overwrite existing capability helper files with fresh copies. `AGENTS.md` and the manifest are always rewritten.
`-h, --help`	none	both	Print usage and exit.

Notation: <value> is required after the flag, and a|b means one of. Flags can appear in any order, before or after the directory.

Recipes#

npx create-bsv-app@latest my-app --starter full-stack \
  --capabilities wallet-login,signed-requests --yes

npx create-bsv-app@latest my-app --starter react --capabilities wallet-login --yes

npx create-bsv-app@latest my-api --starter express --capabilities signed-requests --yes

npx create-bsv-app@latest my-app --starter full-stack \
  --network main --package-manager pnpm --yes

npx create-bsv-app@latest my-app --starter full-stack --skip-install --yes

npx create-bsv-app@latest my-app --starter full-stack --no-glue --yes
# then follow "Wiring (manual)" in AGENTS.md

cd existing-app
npx create-bsv-app@latest add --capabilities wallet-connect,wallet-login --yes

npx create-bsv-app@latest add --capabilities signed-requests --yes

npx create-bsv-app@latest add --capabilities wallet-connect --force --yes

npx create-bsv-app@latest --dir my-app --file config.json

npx create-bsv-app@latest --ui --dir my-app

npx create-bsv-app@latest my-app --starter pollr --yes

Output#

On success it prints a summary and the next commands, then exits 0:

Terminal

npx create-bsv-app@latest my-app --starter full-stack --capabilities wallet-login,signed-requests --yes
Scaffolded my-app (28 file(s) written).

Dependencies installed.

Next:
  cd my-app
  npm run dev

See the generated README/AGENTS.md when present and bsv-scaffold.json for exact provenance.

When some existing files were kept (typical in add mode), the first line reads Updated … (n file(s) written). instead. With --skip-install you'll see Dependencies were not installed. Run your package manager install command before starting.

Errors and exit codes#

Exit code	Meaning
`0`	done
`1`	something failed. The message is on stderr

Config problems are prefixed with Invalid config: and name the field. Every message is listed with its fix in Troubleshooting.

Versions#

These docs describe create-bsv-app 1.1.2. npx create-bsv-app@latest always runs the newest release. To pin one, for reproducible CI, use npx create-bsv-app@1.1.2. Check what's current with npm view create-bsv-app version.