Sandbox CLI

@capxul/sandbox is the CLI for standing up a Capxul test environment. It has exactly two commands: key create mints a test publishable key, and faucet send mints test money. Both run against Capxul's already-deployed canonical quickstart backend — the CLI deploys nothing and pushes no code.

npx @capxul/sandbox            # interactive picker
npx @capxul/sandbox key create
npx @capxul/sandbox faucet send
npx @capxul/sandbox --help

Run with no arguments to pick a command interactively. A global install exposes the capxul-sandbox (and sandbox) executables.

key create

Mints a test publishable key from Capxul's public quickstart endpoint and writes it straight into your app's .env.local. It needs nothing but npx — no operator secrets, no login, no local convex CLI.

npx @capxul/sandbox key create

The CLI prompts for one thing:

• the allowed local origin — usually http://localhost:3000; the key only accepts requests from origins it allows.

It then POSTs that origin to the public mint endpoint and, from the directory you ran it in, upserts two variables into .env.local (creating the file if absent, preserving any lines already there):

NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY=<test publishable key>
CAPXUL_SITE_URL=https://api.staging.capxul.com

Finally it prints the next.config.ts rewrite snippet the quickstart needs. Two properties matter for how you script around it:

• It never clobbers your .env.local. Only those two keys are replaced; every other line is left untouched.
• It is not a deploy. The mint runs entirely on Capxul's already-deployed canonical backend; your app and its config are otherwise untouched. The endpoint is rate-limited to a handful of mints per IP per hour.

faucet send

Mints test USDX to a Capxul identity on Base Sepolia, via the canonical backend's dev faucet. It cannot select a live or mainnet target.

npx @capxul/sandbox faucet send

The CLI prompts for:

• a recipient identity — a Capxul email or an @org-handle. The backend resolves it through the same recipient-resolution path product payments use and funds the resolved Safe; an email works even before that person has ever signed in (the faucet funds their derived Safe address),
• a USDX amount — a decimal string, default 10 (test USDX, 6 decimals).

After a confirmation it mints the funds and reports the identity, the resolved Safe address, the amount, and the transaction hash. Personal payee handles are owner-scoped and cannot be funded by the faucet — use an email or an org handle.

If your agent is already signed in through the MCP server, prefer its faucet.fundTestnet tool instead — it funds the session's account directly, no address required.

When you need it

• Proving email OTP login needs only key create — no test money at all.
• Account and money flows (balances, payments) additionally need the faucet, and only in test environments.

For the full local setup walkthrough, start at Getting started.