Metadata-Version: 2.4
Name: allowance
Version: 0.1.6
Summary: Allowance agent purchase wallet CLI
Project-URL: Homepage, https://github.com/dasmer/allowance-cli
Project-URL: Repository, https://github.com/dasmer/allowance-cli
Project-URL: Issues, https://github.com/dasmer/allowance-cli/issues
Author: Allowance
License: MIT License
        
        Copyright (c) 2026 Allowance
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,allowance,cli,purchase
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.6.0
Requires-Dist: typer>=0.12.5
Description-Content-Type: text/markdown

# 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):

```bash
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):

```bash
pipx install allowance
```

Local source install:

```bash
pipx install .
```

Local development:

```bash
uv sync --dev
uv run allowance --help
```

## CLI Help UX

The CLI supports:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
./scripts/test_unit.sh
./scripts/test_smoke.sh
./scripts/test_all.sh
```
