allowance

allowance is the CLI for Allowance — the agent purchase wallet. It has two roles:

1. Setup (allowance setup) — signs the user in with phone + OTP only, mints a connection token, and writes agent skill files so Claude Desktop, Codex, or OpenClaw knows how to use Allowance.
2. Runtime checkout — the full purchase flow agents use at runtime: request approval, issue a virtual card, fetch identity/address, and report the outcome.

Install

npm install -g @allowance/cli

Or run without installing:

npx @allowance/cli setup

The CLI is implemented in TypeScript/Node and ships as a pure-JS npm package — no Python runtime required.

Requirements:

• Node.js 18 or newer

CLI Help UX

allowance --help
allowance -h
allowance -help
allowance --version

Command surface

Setup

allowance setup               # interactive (humans in a real terminal)
allowance setup --for claude-code
allowance setup --for codex
allowance setup --for openclaw
allowance setup --for generic

Authenticates with phone + OTP only, mints a connection token, and writes skill files for every detected agent (Claude Desktop, Codex, OpenClaw). Setup does not ask for first name, last name, or email. If a later approval needs contact, address, or card details, the iOS app collects them when the user opens the request.

Non-interactive setup (for agents): bare allowance setup requires an interactive terminal — running it from an agent shell exits with a clear error. Agents should first ask the user for their phone number (US formats like 415-555-1234 or 4155551234 work; international numbers must include a +countrycode prefix like +442079460958), then run setup in two steps:

allowance setup --phone <phone>            # sends SMS to user's phone
# ask the user to read you the 6-digit code, then:
allowance setup --phone <phone> --code <code>

The same SMS code is valid for up to 5 attempts in 10 minutes — if the user mis-reads it, just retry --code <new-code>. If it expired, re-run allowance setup --phone <phone> for a fresh SMS. On a bad/expired code the verify step exits with code 2 so agent harnesses can branch without parsing strings; on server-side failures (5xx, network) it exits 1 so agents don't confuse infrastructure problems with a bad OTP.

The connection token secret is stored in OS credential storage:

• macOS: login Keychain via a small bundled Swift helper. The helper reads the secret on stdin and writes it on stdout — never via argv. It ships inside the npm tarball as dist/helpers/keychain-helper-<arch>, pre-built for both Apple Silicon and Intel Macs. No extra install required. On the first run, macOS shows a one-time Keychain authorization prompt; click "Always Allow" and you won't see it again. (Same UX as Python keyring and the system security CLI.)
• Linux: Secret Service via secret-tool (from libsecret-tools). Secret is passed on stdin, never argv. If secret-tool is missing the CLI prints a clear "install libsecret-tools" message.
• Windows: not yet implemented. Use ALLOWANCE_CONNECTION_TOKEN.

~/.allowance/config.json stores non-secret metadata such as token_id and api_base_url (mode 0600 where the platform supports it).

Reset

allowance reset

Deletes ~/.allowance/ and Allowance entries from your OS credential store. On macOS, every matching Keychain entry under "Allowance CLI" is removed. On Linux, secret-tool clear only removes unlocked entries — if your keyring is locked, run allowance reset again after unlocking it to be sure (the CLI prints a reminder when this can happen). Does not revoke server-side tokens — to fully sign out, run allowance reset and then revoke the connection from the Allowance iOS app. Re-run allowance setup --phone <phone> to sign in fresh.

Runtime checkout (used by agents)

| Command | What it does | |---|---| | allowance request | Request spend approval for local browser checkout; requires --local-browser-tool, blocks until approved/denied | | allowance status | Fetch current allowance status for resumable automation runs | | allowance card issue | Issue a one-time virtual card for an approved request | | allowance identity | Fetch name, email, phone for checkout forms | | allowance address shipping | Fetch shipping address for an approved request | | allowance address billing | Fetch billing address for an approved request | | allowance purchase success | Report a completed purchase | | allowance purchase failure | Report a failed purchase attempt |

All amounts are in cents — never dollars. Pass --json to any checkout command for machine-parseable output.

For long-running buy-later tasks, pass --allowance-valid-for-days 7 or --allowance-expires-at <iso8601> when creating the request. Let the command wait for approval and store the returned allowance id in the scheduler. Call allowance status --allowance-id <id> --json before each resumed checkout run. Only call allowance card issue when the merchant payment form is visible.

Global Flags

• --api-base-url — target another environment for one invocation

Configuration

• ALLOWANCE_API_BASE_URL (default https://api.useallowance.com)
• ALLOWANCE_HTTP_TIMEOUT_SECONDS (default 20)
• ALLOWANCE_CONNECTION_TOKEN overrides configured credential storage for CI/debugging
• ALLOWANCE_KEYCHAIN_HELPER_TIMEOUT_MS (default 30000) — how long to wait for the macOS Keychain helper before giving up. Bump if you keep hitting timeouts and want longer to click through the Keychain prompt.

Local development

npm install
npm run build          # compile TS
npm run build:helper   # compile the macOS Keychain helper (macOS-only)
npm run build:all      # both of the above
npm test               # all unit tests; on macOS includes the real-Keychain integration test
npm run typecheck
npm run lint
npm run test:smoke     # CLI end-to-end against a local stub HTTP server

The Swift source for the macOS Keychain helper lives at helpers/keychain-mac/. The npm build:helper script invokes swift build -c release for the current arch and drops the binary into dist/helpers/keychain-helper-<arch>.

Publish to npm

1. Bump version in package.json.
2. Commit and push main.
3. Tag and push an npm release tag:

git tag npm-v0.3.1
git push origin npm-v0.3.1

4. The publish-npm GitHub Action runs the build-helper matrix on macOS arm64 + x64, uploads both helper binaries as artifacts, then the publish job (Ubuntu) downloads them, runs lint/typecheck/tests, builds the TS, and runs npm publish. A pre-publish check fails the release if either helper binary is missing or zero-byte.

After workflow success, users install with:

npm install -g @allowance/cli