# create-bsv-app

> The official CLI for scaffolding BSV blockchain web apps. One command (`npx create-bsv-app@latest`) creates a React + Express app with wallet connect, passwordless wallet login, and signed API requests already wired. Current CLI version: 1.1.2. Requires Node.js 22+.

Each link below is plain Markdown. For the full docs in one file, fetch https://createbsvapp.vercel.app/llms-full.txt.

## Get started

- [Quick start](https://createbsvapp.vercel.app/docs/index.md): Go from an empty folder to a running BSV app with a connected wallet, passwordless login and signed API calls.
- [Tutorial: a signed guestbook](https://createbsvapp.vercel.app/docs/tutorial.md): Build a real feature on top of your scaffold. Every guestbook entry is signed by a wallet and verified by your server, with no accounts or passwords.
- [Project structure](https://createbsvapp.vercel.app/docs/project-structure.md): Every file a full-stack scaffold creates, what it does, and which ones are yours to change.

## Guides

- [Starters](https://createbsvapp.vercel.app/docs/starters.md): Every project starts from a starter. Pick a clean generated scaffold you compose with capabilities, or copy a complete example app.
- [Capabilities](https://createbsvapp.vercel.app/docs/capabilities.md): The three BSV building blocks create-bsv-app wires into your app, the APIs they give you, and the one proof mechanism behind all of them.
- [Wallet recipes](https://createbsvapp.vercel.app/docs/wallet-recipes.md): Encrypt user data, message another identity, sign things anyone can verify, and derive per-app keys. Four BRC-100 calls you can use the moment a wallet connects.
- [Add to an existing project](https://createbsvapp.vercel.app/docs/add-to-existing.md): Drop wallet connect, login or signed requests into a React or Express app you already have, or add more capabilities to a create-bsv-app project later.
- [Environment variables](https://createbsvapp.vercel.app/docs/environment.md): The six variables a generated app reads, their dev defaults, what production insists on, and how to load them.
- [Testing without a wallet](https://createbsvapp.vercel.app/docs/testing.md): Unit-test wallet-authenticated routes with throwaway keys. No wallet app, no browser, no network, just node:test.
- [Deploy to production](https://createbsvapp.vercel.app/docs/deploy.md): Ship the client and server separately. Four environment variables, two hosting rules, one checklist.
- [Use it with AI agents](https://createbsvapp.vercel.app/docs/agents.md): Let Claude Code, Cursor or any coding agent scaffold and extend BSV apps. One JSON file in, an AGENTS.md out, and docs every agent can read.
- [Migrate from @bsv/app](https://createbsvapp.vercel.app/docs/migrate-from-bsv-app.md): @bsv/app is deprecated. Here's how every old template and flag maps to create-bsv-app, and what you gain by switching.
- [Troubleshooting](https://createbsvapp.vercel.app/docs/troubleshooting.md): Every error message we know of, quoted exactly, with what causes it and how to fix it. Search the page for the text you're seeing.
- [FAQ](https://createbsvapp.vercel.app/docs/faq.md): Straight answers to the questions people ask before and after they scaffold their first BSV app.

## Concepts

- [Why create-bsv-app](https://createbsvapp.vercel.app/docs/why.md): The problems with wiring BSV wallet auth by hand, and the positions create-bsv-app takes to solve them.
- [BSV for web developers](https://createbsvapp.vercel.app/docs/bsv-primer.md): Wallets, identity keys, signatures, BRCs and networks, explained by mapping each one to something you already know from web development.
- [How it works](https://createbsvapp.vercel.app/docs/how-it-works.md): 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.
- [Security model](https://createbsvapp.vercel.app/docs/security.md): What a verified proof guarantees, what it doesn't, and the four things to harden before real users show up.
- [Glossary](https://createbsvapp.vercel.app/docs/glossary.md): The BSV and create-bsv-app terms these docs use, each in one or two plain sentences.

## Reference

- [CLI reference](https://createbsvapp.vercel.app/docs/cli.md): Every command, flag and default in create-bsv-app 1.1.2, plus copy-paste recipes for the common jobs.
- [ProjectConfig reference](https://createbsvapp.vercel.app/docs/config.md): The JSON accepted by --file. Every field, its type, its default, and how it maps to the CLI flags.
- [bsv-scaffold.json](https://createbsvapp.vercel.app/docs/manifest.md): The manifest every run writes. What's in it, why later runs read it, and how it records exactly where a project came from.
- [Client API](https://createbsvapp.vercel.app/docs/api-client.md): Every function and component the scaffold writes to client/src/bsv/, with its exact signature, return value, parameters and errors.
- [Server API](https://createbsvapp.vercel.app/docs/api-server.md): The functions the scaffold writes to server/src/bsv/, the routes it mounts, and exactly what each one verifies, returns and refuses.
- [Errors](https://createbsvapp.vercel.app/docs/errors.md): Every error the CLI and the generated code can throw, grouped by where it comes from, with what it means and what to do.
- [Compatibility](https://createbsvapp.vercel.app/docs/compatibility.md): What create-bsv-app and the apps it generates run on, and what these docs have actually been tested against.
