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

Creates a developer application and a test publishable key on the canonical quickstart deployment, then writes the customer values to a local handoff file.

npx @capxul/sandbox key create

The CLI prompts for:

• an application name,
• the allowed local origin — usually http://localhost:3000; the key only accepts requests from origins it allows,
• a handoff file path — default ~/.config/capxul/quickstart-handoffs/customer-nextjs-quickstart.md.

After a confirmation it mints the key and reports the handoff path, the application id, the key id, and the allowed origin. Two properties matter for how you script around it:

• The raw key is never printed. The terminal shows ids and metadata only; the publishable key itself lands in the handoff file. Copy it from there into your app's .env.local (see the getting started guide).
• It is not a deploy. The command calls the already-deployed canonical backend; your app and its config are untouched.

faucet send

Mints test USDX to an address 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 EVM address — the current release sends funds directly to an address,
• a USDX amount — a decimal string, default 10 (test USDX, 6 decimals).

After a confirmation it mints the funds and reports the recipient, amount, and transaction hash.

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.