allowance

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

1. Setup (allowance setup) — signs the user in via OTP, 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

Primary (npm):

npm install -g @allowance/cli

This npm package exposes the allowance command and bootstraps the Python runtime automatically. Prerequisite: Python 3.12+ on PATH (python3 or python).

Secondary (pipx):

pipx install allowance

Local source install:

pipx install .

Local development:

uv sync --dev
uv run allowance --help

CLI Help UX

The CLI supports:

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

Publish to npm

This repo supports npm publishing through GitHub Actions.

One-time setup

1. Create the npm scope/org @allowance and grant maintainer access.
2. Create an npm automation token with publish permission.
3. Add it as a GitHub repository secret:
   • name: NPM_TOKEN
   • value: npm token string
4. Current npm automation token expires on June 23, 2026. Rotate both the GitHub NPM_TOKEN secret and your local ~/.npmrc entry before that date.

Release flow

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

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

4. GitHub Action .github/workflows/publish-npm.yml runs and publishes @allowance/cli.

After workflow success, users can install with:

npm install -g @allowance/cli

Publish to PyPI

This repo also supports PyPI publishing for pipx users.

One-time setup

1. Create a PyPI account for the maintainer/org.
2. Create a project-scoped API token in PyPI.
3. Add the token as a GitHub repository secret:
   • name: PYPI_API_TOKEN
   • value: pypi-...

Release flow

1. Bump version in pyproject.toml.
2. Commit and push main.
3. Tag and push a version tag:

git tag v0.1.1
git push origin v0.1.1

4. GitHub Action .github/workflows/publish-pypi.yml runs:
   • lint/type/test
   • build wheels/sdist
   • publish to PyPI

Command surface

Setup

allowance setup               # auto-detect agent
allowance setup --for claude-code
allowance setup --for codex
allowance setup --for openclaw
allowance setup --for generic

Authenticates via phone OTP, mints a connection token, and writes skill files for every detected agent (Claude Desktop, Codex, OpenClaw).

The connection token secret is stored in OS credential storage via keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service where available). ~/.allowance/config.json stores non-secret metadata such as token_id and api_base_url.

Runtime checkout (used by agents)

Command	What It Does
allowance request	Request spend approval for local browser checkout; requires --local-browser-tool and blocks until approved/denied
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

Runtime checkout commands output human-readable text by default. Pass --json to any checkout command for machine-parseable output (useful for scripting or agent use).

Global Flags

• --api-base-url to 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.

Tests

./scripts/test_unit.sh
./scripts/test_smoke.sh
./scripts/test_all.sh