@joinbankroll/cli

Command-line tools for Built for Bankroll apps.

npx bankroll login                 # your Bankroll account, once per computer
npx bankroll apps                  # the apps you built with Bankroll
npx bankroll apps clone 12         # one of them, as a repo with the remote named bankroll
cd br-12-abc123 && npm run dev     # tunnel + QR — scan it to open the app inside Bankroll
git push bankroll main             # Bankroll builds and deploys it

The starter carries it as a devDependency, so npm run and npx find it inside an app. To use it in any directory, npm i -g @joinbankroll/cli — the binary is bankroll either way.

Commands

bankroll login                                  log in to your Bankroll account
bankroll logout                                 forget the login on this computer
bankroll whoami                                 who this computer is logged in as
bankroll apps                                   your apps, archived ones left out
bankroll apps --published                       only the ones listed for everyone
bankroll apps --archived                        only archived; --all for everything
bankroll apps create --name <name>              a new app from the starter, no agent
bankroll apps clone <id> [dir]                  the app's repo, remote named bankroll
bankroll apps archive <id>                      off the air; code, data, wallet stay
bankroll apps unarchive <id>                    back on the air
bankroll apps publish <id>                      listed for everyone
bankroll apps unpublish <id>                    unlisted; still playable by link

bankroll dev                                    tunnel + QR, injects your key

bankroll dev

Runs your dev server behind a Cloudflare quick tunnel and prints a QR code.

A Bankroll app only runs inside the Bankroll host, and the host refuses any origin that is not public HTTPS — so localhost cannot be opened however reachable it is. The tunnel needs no Cloudflare account, and because the phone reaches the app over the internet rather than the local network, this works on Wi-Fi that isolates clients from each other.

The QR carries your app's launch path, read from the manifest it is serving — Bankroll loads exactly the URL it is given, so a scan opens your app rather than whatever sits at the root.

On a TTY the QR is drawn with explicit ANSI colors, dark-on-light, so a dark terminal cannot invert it. When stdout is not a TTY — piped or backgrounded, which is how coding agents run it — the QR is bare block glyphs instead, safe to re-print into a chat transcript, where ANSI would be stripped and the colored form would collapse into a wall of ▀. Setting NO_COLOR forces the bare form on a TTY too. The full play link is printed under the QR either way.

The signing key

Kept at ~/.config/bankroll/keypair.json, created on first use and never overwritten. It is a Solana keypair file in the same format solana-keygen writes, so the Solana CLI reads it:

solana balance --keypair ~/.config/bankroll/keypair.json

Never ~/.config/solana/id.json — that is the Solana CLI default and, on many machines, a developer's actual wallet. This tool puts the key it loads into a dev server's environment, so it gets its own: the blast radius is bounded, and deleting one file is a complete cleanup.

The secret is injected into the process bankroll dev spawns and is never written into your project, so it cannot be committed.

A deployment should use a different BANKROLL_TREASURY_KEY, set as a sensitive variable, so the key on your machine never goes near the app.

Building with an agent

The bankroll skill teaches a coding agent this workflow: create, clone, run, push, watch the build, publish, and the money rules. Install it once, for every agent on the machine:

npx skills add inplayinnovation/bankroll-cli --skill bankroll -g

apps create and apps clone print that line. The skill lives in skills/bankroll/SKILL.md in this repo.

Logging in

bankroll login prints a link and a short code. Open the link, log in to Bankroll with your phone number, and approve the code. The terminal finishes on its own. It is the same device login GitHub's CLI uses.

The session goes into your credential store: the keychain on macOS, the keyring through secret-tool on Linux. It refreshes itself and lasts 30 days from the last use. bankroll logout removes it.

Where there is no store, the CLI says why and asks before keeping the session in ~/.config/bankroll/session.json, readable by your user only but not encrypted. --allow-file-session gives that answer up front, for a shell nobody is watching.

-e <name> uses another Bankroll api, described in ~/.config/bankroll/environments.json as { "<name>": { "apiUrl": …, "privyAppId": … } }, with a session file of its own.

bankroll apps clone

Clones the app's private repo with the remote named bankroll, so git push bankroll main saves your changes to it. Git gets its credentials from this tool: a token for that one repo, good for an hour, fetched from the api each time git asks. Nothing is written to disk, and bankroll logout ends the access.

dev needs no account: it is local, and the only credential it uses is the signing key.