> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinbankroll.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> bankroll dev — the tunnel, the QR code, the dev signing key, and the rest of the CLI.

Your app runs inside Bankroll on a phone, and the host opens only public HTTPS
origins — so the development loop is not `localhost:3000` in a browser tab.
It is one command:

```bash theme={null}
npm run dev
```

`npm run dev` is `bankroll dev`, from
[`@joinbankroll/cli`](https://www.npmjs.com/package/@joinbankroll/cli) — a
devDependency the [starter](https://github.com/inplayinnovation/bankroll-starter)
already carries. It starts your dev server on a free port, raises a public
tunnel in front of it, reads your live manifest, and prints a QR code that
opens the app inside Bankroll at its `launch` path. Scan it and you are
developing against the real host — session, payments, and hot reload included.

## The tunnel

The tunnel is a Cloudflare quick tunnel, and it gets a **new URL on every
restart** — the host cannot reopen a previous one. "Can't open this app"
almost always means a dead tunnel: restart `npm run dev` and scan the new QR.

The dev server's port doesn't matter — the tunnel hides it — so `bankroll dev`
picks any free one. Pass `-p, --port <port>` to pin it.

## The QR, when an agent runs this

On a TTY, the QR is drawn with ANSI colors. When stdout is **not** a TTY — a
piped or backgrounded run, which is how a coding agent runs it — `bankroll dev`
(0.3.0+) prints plain block glyphs instead, with the full play link under it:
both safe to re-print verbatim into a chat. Setting `NO_COLOR` forces the same
rendering on a TTY.

If you are an agent: your task output is not shown to the user, and the colored
QR cannot be relayed as text (the contrast is in the color codes, not the
glyphs). Put the glyph QR in your chat reply inside a fenced code block, play
link under it — the exact recipe, including the fallback for older CLIs, is in
[Build with an agent](/build/agents).

## The dev signing key

The first `bankroll dev` creates a signing key at
**`~/.config/bankroll/keypair.json`** and injects it into the dev server's
environment as the treasury. It is never written into your project, so it
cannot be committed. Pass `-k, --keypair <path>` to use a different one.

That key is your app's wallet while you develop: it receives every `charge()`
and signs every payout, and it moves **real mainnet HSUSD**.

<Warning>
  Fund the dev key with only what you are willing to risk, and give a deployment
  its own key — see [Deploy](/build/deploy). To exercise the whole money loop
  without spending real money, mint an [app token](/build/app-tokens) and charge
  in that instead.
</Warning>

## Plain localhost

`npx next dev` still works, for layout and UI work in a browser. It is the
exception rather than the loop: a browser has no host bridge, so
[`status()`](/build/quickstart#step-1--install-the-sdk-and-detect-the-host)
reads `'unavailable'`, `session()` and `charge()` are off the table, and your
token-guarded routes answer 401. That is the app working as designed, not a
bug.

## The rest of the CLI

`npx bankroll --help` is the authority; the commands today:

| Command                           | What it does                                                                                                                                                           |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bankroll dev`                    | The loop above — dev server, tunnel, QR.                                                                                                                               |
| `bankroll treasury show`          | The signing key's address, and everything it holds.                                                                                                                    |
| `bankroll treasury send <wallet>` | Send HSUSD — or one of your tokens, with `--token <mint>` — from the treasury.                                                                                         |
| `bankroll token create`           | Create a token: 9 decimals, whole supply on your signing key, written into `app-tokens.json`. `--name` is what Bankroll calls it. See [App tokens](/build/app-tokens). |
| `bankroll token list`             | List the tokens this app declares.                                                                                                                                     |
| `bankroll token mint <mint>`      | Issue more supply of a token you control.                                                                                                                              |

Commands that touch the chain take `-k, --keypair <path>` (defaulting to the
dev key) and `--rpc <url>` (defaulting to `SOLANA_RPC_URL`, else the public
endpoint).

## Where local state lives

Scaffolding writes `.env.local` — `STORE=fs`, your app's name, and an RPC —
and it is gitignored, so none of it reaches a deployment. With `STORE=fs` the
[store](/build/store) keeps its documents in plain files under
`bankroll/development/` in your project: open them and read what your app
recorded. Tests write to `bankroll/test/` instead, so a test run can never
touch the store you develop against.