@allowance/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,9 @@
 # allowance
 
-`allowance` is a human-first CLI for Allowance purchase workflows.
+`allowance` is the CLI for Allowance — the agent purchase wallet. It has two roles:
 
-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.
+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
 
@@ -37,14 +37,13 @@ uv run allowance --help
 
 ## CLI Help UX
 
-The CLI now supports all of these help forms:
+The CLI supports:
 
 ```bash
 allowance --help
 allowance -h
 allowance -help
 allowance --version
-allowance quickstart
 ```
 
 ## Publish to npm
@@ -58,6 +57,7 @@ This repo supports npm publishing through GitHub Actions.
 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
 
@@ -106,115 +106,42 @@ git push origin v0.1.1
    - build wheels/sdist
    - publish to PyPI
 
-## Fast Purchase Path (Recommended)
+## Command surface
 
-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:
+### Setup
 
 ```bash
-allowance auth login --email you@example.com
-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
+allowance setup               # auto-detect agent
+allowance setup --for claude-code
+allowance setup --for codex
+allowance setup --for openclaw
+allowance setup --for generic
 ```
 
-## Auth
-
-Login bootstraps via OTP, then mints and stores a connection token:
-
-```bash
-allowance auth login --email you@example.com
-```
-
-If already logged in, login exits with:
-
-`Already logged in as <email>. Run allowance auth logout to switch accounts.`
-
-Status command:
+Authenticates via phone OTP, mints a connection token, and writes skill files for every detected agent (Claude Desktop, Codex, OpenClaw).
 
-```bash
-allowance auth status
-```
-
-Logout command (revokes remote token and clears keychain):
+### Runtime checkout (used by agents)
 
-```bash
-allowance auth logout
-```
+| Command | What It Does |
+|---|---|
+| `allowance request` | Request spend approval from the user; 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 |
 
-## Command Reference
-
-All commands output JSON by default. Use `--pretty` for formatted JSON.
-
-| Command | What It Does | Use When |
-|---|---|---|
-| `allowance quickstart` | Prints copy-paste end-to-end purchase flow | You want the fastest correct flow immediately |
-| `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 |
+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
-- `--pretty` for formatted JSON output
-
-Example:
-
-```bash
-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_API_BASE_URL` (default: `https://api.useallowance.com`)
 - `ALLOWANCE_HTTP_TIMEOUT_SECONDS` (default: `20`)
-- `ALLOWANCE_CLI_KEYCHAIN_SERVICE` (optional keychain namespace override)
-- `ALLOWANCE_CLI_KEYCHAIN_ACCOUNT` (optional keychain account override)
 
 ## Tests
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allowance/cli",
-  "version": "0.1.1",
-  "description": "Allowance CLI wrapper package for npm global installs",
+  "version": "0.1.3",
+  "description": "Allowance agent purchase wallet CLI",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,8 +14,8 @@
   "keywords": [
     "allowance",
     "cli",
-    "payments",
-    "agents"
+    "agent",
+    "purchase"
   ],
   "bin": {
     "allowance": "bin/allowance.js"