# CLI reference

> Every command, flag and default in create-bsv-app 1.1.2, plus copy-paste recipes for the common jobs.

> Agents: search these docs with the `search_docs` tool on the MCP server at https://createbsvapp.vercel.app/mcp, or read everything at https://createbsvapp.vercel.app/llms-full.txt.

## Usage

```text
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](https://createbsvapp.vercel.app/docs/starters). 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](https://createbsvapp.vercel.app/docs/capabilities) 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](https://createbsvapp.vercel.app/docs/config) 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

::: code-group
```bash [full-stack, everything]
npx create-bsv-app@latest my-app --starter full-stack \
  --capabilities wallet-login,signed-requests --yes
```
```bash [frontend only]
npx create-bsv-app@latest my-app --starter react --capabilities wallet-login --yes
```
```bash [API only]
npx create-bsv-app@latest my-api --starter express --capabilities signed-requests --yes
```
```bash [mainnet, pnpm]
npx create-bsv-app@latest my-app --starter full-stack \
  --network main --package-manager pnpm --yes
```
```bash [CI, no install]
npx create-bsv-app@latest my-app --starter full-stack --skip-install --yes
```
```bash [wire it yourself]
npx create-bsv-app@latest my-app --starter full-stack --no-glue --yes
# then follow "Wiring (manual)" in AGENTS.md
```
:::

::: code-group
```bash [add to existing]
cd existing-app
npx create-bsv-app@latest add --capabilities wallet-connect,wallet-login --yes
```
```bash [add more later]
npx create-bsv-app@latest add --capabilities signed-requests --yes
```
```bash [refresh helper files]
npx create-bsv-app@latest add --capabilities wallet-connect --force --yes
```
```bash [from a file]
npx create-bsv-app@latest --dir my-app --file config.json
```
```bash [browser UI]
npx create-bsv-app@latest --ui --dir my-app
```
```bash [complete example]
npx create-bsv-app@latest my-app --starter pollr --yes
```
:::

## Output

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

```console
$ 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](https://createbsvapp.vercel.app/docs/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`.