Metadata-Version: 2.4
Name: allowance
Version: 0.1.2
Summary: CLI for Allowance OpenClaw MCP installation and diagnostics
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: allowance,cli,mcp,openclaw
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: typer>=0.12.5
Description-Content-Type: text/markdown

# allowance

`allowance` is a small CLI for OpenClaw setup only.

It signs the user in with OTP, mints an Allowance connection token, and installs hosted Allowance MCP into OpenClaw. It is intentionally not a second runtime surface for requests, cards, or allowance operations, and OpenClaw config is the only long-term secret store.

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

## OpenClaw

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

| Command | What It Does | Use When |
|---|---|---|
| `allowance openclaw install` | Prompts for email or phone, completes OTP bootstrap, mints an OpenClaw-attributed token, and installs hosted Allowance MCP config | First-time setup or reinstall |
| `allowance openclaw doctor` | Verifies OpenClaw availability, installed config, bearer wiring, and hosted MCP reachability | Troubleshooting |
| `allowance openclaw uninstall` | Removes the Allowance MCP entry from OpenClaw and best-effort revokes the configured token | Cleanup |

`allowance openclaw install` writes an OpenClaw MCP entry named `allowance` using:

- hosted MCP URL from the Allowance API config when available
- `transport: "streamable-http"`
- `Authorization: Bearer ak_...`

Install accepts either:

```bash
allowance openclaw install --email you@example.com
allowance openclaw install --phone +14155551234
```

If no identifier flag is provided, the CLI prompts for an email address or E.164 phone number.

The CLI uses `openclaw mcp set/show/unset` instead of editing OpenClaw config files directly.

## Global Flags

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

Example:

```bash
allowance --api-base-url http://127.0.0.1:8000 --pretty openclaw doctor
```

## Configuration

- `ALLOWANCE_API_BASE_URL` (default: `https://api.useallowance.com`)
- `ALLOWANCE_MCP_URL` (default: `https://mcp.useallowance.com`)
- `ALLOWANCE_HTTP_TIMEOUT_SECONDS` (default: `20`)

## Tests

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