# How it works

> One config, one pipeline. How your flags, prompts or JSON become a ProjectConfig, and what the CLI does with it in new and add mode.

> 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.

Under the hood, create-bsv-app is small and predictable. However you call it, it builds one `ProjectConfig` object and hands it to one function. Knowing that makes every flag, prompt and error easier to reason about.

```text [the pipeline]
 flags ─┐
prompts ─┼──▶  ProjectConfig  ──▶  applyConfig()
 --file ─┤        (validated)          │
   --ui ─┘                             ├─ mode "new" ─▶ starter ─▶ base app ─▶ capability files ─▶ wiring ─▶ manifest ─▶ install
                                       └─ mode "add" ─────────────────────────▶ capability files ─────────▶ manifest ─▶ install
```

## Four ways in

All four produce the same `ProjectConfig`, so the same config always takes the same path through the pipeline. They only differ in how you supply it.

| Way in | Command | Best for |
| --- | --- | --- |
| Prompts | `npx create-bsv-app@latest` | exploring, first run |
| Flags | `… --starter full-stack --capabilities wallet-login --yes` | scripts, docs, muscle memory |
| Config file | `… --dir my-app --file config.json` | CI, AI agents, reproducible setups |
| Browser UI | `… --ui --dir my-app` | point and click |

You can mix them. Flags fill in their answers and the prompts only ask about the rest. With `--yes` there are no prompts at all, and anything unspecified uses its default.

::: deep What `--ui` actually starts
A tiny HTTP server bound to `127.0.0.1` (never reachable from your network) serves a one-page form, generated from the same schema the terminal prompts use. Press **Generate** and it runs the same pipeline, then shuts itself down. It's single-use by design.
:::

## Modes

### `new`

Creates a project in an **empty** directory (a `.git` folder or a `bsv-scaffold.json` is allowed). In order, it:

1. **Clones or generates the base.** Complete examples are `git clone`d, and that's nearly the end: the manifest is written and dependencies installed. Generated starters run `create-vite` (React) and/or write a lean Express app.
2. **Writes capability files** into `src/bsv/` of each target.
3. **Wires the base app** (unless `--no-glue`). It wraps `<App />` in `<WalletProviders>`, adds routes to `App.tsx`, and mounts routes, CORS and the wallet relay in the server.
4. **Writes the root runner** when there's both a client and a server (`npm run dev` for both).
5. **Writes `AGENTS.md` and `bsv-scaffold.json`.**
6. **Adds dependencies** to each `package.json` and installs them (unless `--skip-install`).

### `add`

Adds capabilities to an existing project. No base generator runs, and **your own files are never edited**. It writes capability files, `AGENTS.md` (with manual wiring snippets) and the manifest, adds dependencies, and installs. Existing helper files are kept unless you pass `--force`. [Full guide](https://createbsvapp.vercel.app/docs/add-to-existing).

### How the mode is chosen

```text [mode inference]
--mode new|add given?                 → use it
bsv-scaffold.json in the target?      → add
React/Express project detected?       → add
otherwise                             → new
```

## Defaults

Everything has one, so `--yes` with nothing else is valid as long as the starter determines a stack:

| Field | Default |
| --- | --- |
| directory | `.` |
| name | the directory name |
| starter | `custom` |
| capabilities | `wallet-connect` (always included in `new`) |
| bsvDir | `src/bsv` |
| packageManager | `npm` |
| network | `test` |
| glue | on |
| install | on |

## Why generate, rather than ship a library?

A library hides the code that decides who's logged in, and that's the code you most need to read and own. Generated files are yours: readable, editable and deletable, with no version lock-in and no magic. The heavy cryptography still comes from maintained packages (`@bsv/sdk`, `@bsv/auth`, `@bsv/wallet-relay`). The scaffold is the thin, visible layer between them and your app.