allowance 0.1.0

CLI for Allowance approval and purchase workflows

allowance

allowance is a human-first CLI for Allowance purchase workflows.

It uses an ak_... connection token at runtime and stores credentials in the OS keychain. Runtime actions are token-scoped, so requests/allowances are visible to the token session that created them.

Install

pipx install .

After publishing to PyPI:

pipx install allowance

Local development:

uv sync --dev
uv run allowance --help

Publish to PyPI

This repo supports release publishing through GitHub Actions.

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

After workflow success, users can install with:

pipx install allowance

Fast Purchase Path (Recommended)

Use this flow for fastest agent and customer experience:

1. Authenticate once for the session.
2. Create a request with clear merchant + reason + cap amount.
3. Ask customer to approve immediately in app.
4. Poll until approved.
5. Issue card only when checkout is ready.
6. Complete checkout.
7. Report purchase outcome immediately (success or failed).
8. If failed and still active, re-issue and retry within policy limits.

Example:

allowance auth login --email [e-mail]
allowance requests create --cents 5000 --merchant "Ticketmaster" --reason "2 tickets under $50"
allowance requests poll <request_id>
allowance cards issue <allowance_id> --expected-cents 4500
allowance cards report <allowance_id> <attempt_id> --status success --charged-cents 4380

Auth

Login bootstraps via OTP, then mints and stores a connection token:

allowance auth login --email [e-mail]

If already logged in, login exits with:

Already logged in as <email>. Run allowance auth logout to switch accounts.

Status command:

allowance auth status

Logout command (revokes remote token and clears keychain):

allowance auth logout

Command Reference

All commands output JSON by default. Use --pretty for formatted JSON.

Command	What It Does	Use When
allowance auth login --email <email>	Signs in via OTP bootstrap and stores token in keychain	Starting a session
allowance auth status	Shows whether CLI is logged in and which account/token prefix	Preflight checks
allowance auth logout	Revokes token and clears local credentials	End of session/security cleanup
allowance requests create --cents ... --merchant ... --reason ... [--currency] [--expires-at]	Creates a pending allowance request	You need user approval before spending
allowance requests list	Lists requests created by this token session	Find recent request IDs
allowance requests get <request_id>	Fetches full request detail	Inspect request state/details
allowance requests poll <request_id>	Returns current request status and allowance_id when approved	Waiting on user approval
allowance requests cancel <request_id>	Cancels a still-pending request	User changed mind / no longer needed
allowance cards issue <allowance_id> --expected-cents <int>	Issues checkout card for one purchase attempt	Approval exists and checkout is ready
allowance cards attempts <allowance_id>	Lists purchase attempts for that allowance	Audit/retry decisions
allowance cards report <allowance_id> <attempt_id> --status success\|failed ...	Finalizes attempt result and updates allowance state	Immediately after checkout attempt
allowance allowances list	Lists allowances visible to current token	Find/manage active allowances
allowance allowances get <allowance_id>	Gets one allowance snapshot	Verify state/retry budget
allowance allowances pause <allowance_id>	Pauses spending on allowance	Temporary stop needed
allowance allowances revoke <allowance_id>	Permanently revokes allowance	Final stop / cleanup

allowance allowances unpause is intentionally not exposed in this CLI.

Agent + Customer Experience Guidelines

1. Request only when purchase intent and budget are clear.
2. Use merchant/reason text the customer can quickly recognize in approval UI.
3. After requests create, immediately provide request summary and ask customer to approve.
4. Poll with short intervals, but keep customer informed instead of silently looping.
5. Issue card only at the final checkout step to reduce stale credential windows.
6. Always call cards report right after checkout outcome.
7. Never echo PAN/CVV unless customer explicitly asks.

Error Handling

Status	Meaning	Typical Action
401	Auth invalid/expired	Re-login
403	Not allowed for this actor	Use correct actor/flow
404	Not found or out-of-scope token access	Verify IDs and token session
409	State conflict (not active, retry exhausted, etc.)	Inspect current resource state and adjust
503	Upstream issuer/provider unavailable	Retry later or fail gracefully

Global Flags

• --api-base-url to target another environment for one invocation
• --pretty for formatted JSON output

Example:

allowance --api-base-url http://127.0.0.1:8000 --pretty allowances list

Configuration

• ALLOWANCE_API_BASE_URL (default: https://allowance-api.fly.dev)
• ALLOWANCE_HTTP_TIMEOUT_SECONDS (default: 20)
• ALLOWANCE_CLI_KEYCHAIN_SERVICE (optional keychain namespace override)
• ALLOWANCE_CLI_KEYCHAIN_ACCOUNT (optional keychain account override)

Tests

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