@getbags/cash

BAGS Cash CLI — hosted agent wallet for x402. Redeem credits, discover endpoints, check quotes, and pay from your agent.

Install

npx @getbags/cash --help
# or
npm install -g @getbags/cash
bags --help

Agent skill (prompt paste)

Hosted skill: https://www.getbags.app/wallet/skill.md

Paste into Cursor / Claude / Codex / etc.:

Set up https://www.getbags.app/wallet/skill.md

Human onboard (bonus + same prompt): https://www.getbags.app/wallet/onboard
Staging: use https://staging.getbags.app/wallet/skill.md (or set BAGS_API_URL).

Workflow

balance → discover|search → check → fetch

Commands

| Command | Description | | --------------------------- | --------------------------------------------------------------- | | redeem <code> | Redeem an invite; saves token to ~/.bags/credentials.json | | redeem --test | Mint a sandbox wallet (no invite; Base Sepolia + Solana devnet) | | balance | Show balance, daily spent/cap, status | | discover [query] | List BAGS merchant endpoints (BAGS first) | | search <query> | NL search across BAGS + ecosystem index | | check <url> | Probe schema + exact quote without paying | | fetch <url> [flags] | Pay and proxy an x402 endpoint | | transactions | Spend / ledger history | | policies get\|set | Read or update spend policies | | keys create\|list\|revoke | Per-agent wallet keys | | register <origin> | Persist an origin into the discover/search index | | init [flags] | Register MCP + skill + routing rule for detected clients | | mcp | Serve wallet tools over stdio (JSON-RPC on stdout) | | doctor | Verify token, MCP registration, skill, and routing rule |

init flags: --dry-run, --client cursor|claude|codex (force-create even without a marker directory; repeatable or comma-separated), --scope project|user (default user — ambient on this machine; use --scope project for committable repo-local config). After a successful apply, restart the agent client, then run bags doctor.

Fetch / check flags: -m/--method, -b/--body (JSON string), --max-price-cents (fetch), --format json|pretty.

Env

| Variable | Default | Notes | | -------------- | ------------------------- | -------------------------------------- | | BAGS_API_URL | https://www.getbags.app | Staging: https://staging.getbags.app |

Example

export BAGS_API_URL=https://staging.getbags.app   # optional
npx @getbags/cash redeem --test                   # sandbox (no invite burn)
# or: npx @getbags/cash redeem BAGS-XXXX-XXXX
npx @getbags/cash balance
npx @getbags/cash discover                        # includes $0.01 /api/v1 showcase
npx @getbags/cash check 'https://www.getbags.app/api/v1'
npx @getbags/cash fetch 'https://www.getbags.app/api/v1'

After npm i -g @getbags/cash, bags is an alias for npx @getbags/cash.

Payment receipt prints on stderr; the upstream body prints on stdout.

Auth

Token at ~/.bags/credentials.json. Hosted custody — no local private keys. MCP tools accept the same token via Authorization: Bearer or a wallet_token argument.

Publishing @getbags/cash

Local (preferred dry-run)

From the repo root:

bun run publish:cash --dry-run   # install + build + test; never publishes
bun run publish:cash             # same as dry-run unless NPM_TOKEN is set
bun run publish:cash --publish   # requires NPM_TOKEN; runs npm publish --access public

Or manually:

cd packages/cli
bun install && bun run build && bun run test
# npm publish --access public   # only with npm auth for @getbags

prepublishOnly runs the build. Version bumps are manual in packages/cli/package.json.

CI (tag automation)

GitHub Action: .github/workflows/publish-cash.yml

1. Bump version in packages/cli/package.json
2. Tag and push: git tag cash-v0.2.0 && git push origin cash-v0.2.0 (tag must match package version)
3. Workflow builds and tests. It publishes only when repo secret NPM_TOKEN is set; otherwise the job succeeds as a dry-run (no npm publish).

workflow_dispatch defaults to dry-run (build/test only). Set dry_run=false to attempt publish (still skips cleanly if NPM_TOKEN is missing).

Do not publish unless NPM_TOKEN is available and you intend a release. Scoped packages typically need an automation token with 2FA bypass for CI. Add the secret under GitHub → Settings → Secrets and variables → Actions (NPM_TOKEN).