@allowance/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,8 @@
 # allowance
 
-`allowance` is a human-first CLI for Allowance purchase workflows.
+`allowance` is a small CLI for OpenClaw setup only.
 
-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.
+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
 
@@ -35,6 +34,17 @@ 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.
@@ -46,6 +56,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
 
@@ -94,96 +105,32 @@ git push origin v0.1.1
    - build wheels/sdist
    - publish to PyPI
 
-## 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:
-
-```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
-```
-
-## Auth
-
-Login bootstraps via OTP, then mints and stores a connection token:
+## OpenClaw
 
-```bash
-allowance auth login --email you@example.com
-```
+All commands output JSON by default. Use `--pretty` for formatted JSON.
 
-If already logged in, login exits with:
+| 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 |
 
-`Already logged in as <email>. Run allowance auth logout to switch accounts.`
+`allowance openclaw install` writes an OpenClaw MCP entry named `allowance` using:
 
-Status command:
+- hosted MCP URL from the Allowance API config when available
+- `transport: "streamable-http"`
+- `Authorization: Bearer ak_...`
 
-```bash
-allowance auth status
-```
-
-Logout command (revokes remote token and clears keychain):
+Install accepts either:
 
 ```bash
-allowance auth logout
+allowance openclaw install --email you@example.com
+allowance openclaw install --phone +14155551234
 ```
 
-## Command Reference
-
-All commands output JSON by default. Use `--pretty` for formatted JSON.
+If no identifier flag is provided, the CLI prompts for an email address or E.164 phone number.
 
-| 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 |
+The CLI uses `openclaw mcp set/show/unset` instead of editing OpenClaw config files directly.
 
 ## Global Flags
 
@@ -193,15 +140,14 @@ All commands output JSON by default. Use `--pretty` for formatted JSON.
 Example:
 
 ```bash
-allowance --api-base-url http://127.0.0.1:8000 --pretty allowances list
+allowance --api-base-url http://127.0.0.1:8000 --pretty openclaw doctor
 ```
 
 ## Configuration
 
-- `ALLOWANCE_API_BASE_URL` (default: `https://allowance-api.fly.dev`)
+- `ALLOWANCE_API_BASE_URL` (default: `https://api.useallowance.com`)
+- `ALLOWANCE_MCP_URL` (default: `https://mcp.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/lib/runtime.js

@@ -145,7 +145,10 @@ function installPinnedPackage(targetSpec) {
 }
 
 function ensureRuntime(options) {
-  const targetSpec = `${options.pypiPackage}==${options.version}`;
+  const envTargetSpec = process.env.ALLOWANCE_PYPI_TARGET;
+  const targetSpec = envTargetSpec && envTargetSpec.trim()
+    ? envTargetSpec.trim()
+    : `${options.pypiPackage}==${options.version}`;
   const currentState = readState();
 
   if (fs.existsSync(allowanceExecutablePath()) && currentState && currentState.targetSpec === targetSpec) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allowance/cli",
-  "version": "0.1.0",
-  "description": "Allowance CLI wrapper package for npm global installs",
+  "version": "0.1.2",
+  "description": "Allowance OpenClaw MCP installation and diagnostics CLI",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,8 +14,8 @@
   "keywords": [
     "allowance",
     "cli",
-    "payments",
-    "agents"
+    "openclaw",
+    "mcp"
   ],
   "bin": {
     "allowance": "bin/allowance.js"