From 785367fba8d49b18f488fff7ce0ff96e70d9c17a Mon Sep 17 00:00:00 2001 From: Trevor Miller Date: Thu, 14 May 2026 12:50:28 -0400 Subject: [PATCH] docs(plugin): flip CLI examples to v2 short form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the `bb cli` infix from every plugin page, skill, agent, and slash command per the CLI v2 redesign locked on 2026-05-14 (autopilot ticket #0399, outputs/flagship-plans/cli-v2-design.md). Applied renames inside both prose and code blocks: - `bb cli ` → `bb ` - `bb cli portfolio` → `bb account` (absorbs `address convert/validate`, `lookup`, `alias`, `gen-list-id` as subcommands) - `bb cli config` → `bb settings` - `bb cli tool[s]` / `resources` / `docs` / `skills` / `gen-pub-key` → `bb dev ` - `bb cli swap pools` / `bb cli swap asset-pairs` → `bb pools` / `bb pairs` - `sign-with-browser` and `gen-tx-payload` folded into `bb deploy --browser` / `bb deploy --gen-payload` - `bb cli build` (per-standard builders) → `bb build ` - Underlying `bitbadges-cli ` invocations in skill examples flipped to `bb ` (binary names retained only where the reader must know them to install or troubleshoot — README intro + `/bitbadges:setup` PATH check) Signing stays as `bb deploy --` flags (no `bb sign ` subcommands per the locked decisions). The deprecated `bb cli` form keeps working for one release with a stderr deprecation banner; README now calls that out, and `BB_QUIET=1` suppresses the banner. No semantic / behavioral changes — invocation form only. Backs the implementation that lands in the bitbadgesjs SDK + bitbadgeschain PRs for ticket #0399. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 9 ++--- README.md | 20 +++++------ agents/bitbadges-builder.md | 14 ++++---- commands/setup.md | 2 +- commands/status.md | 8 ++--- skills/address/SKILL.md | 10 +++--- skills/broadcast/SKILL.md | 70 ++++++++++++++++++------------------- skills/build/SKILL.md | 12 +++---- skills/claim/SKILL.md | 4 +-- skills/explain/SKILL.md | 4 +-- skills/query/SKILL.md | 40 ++++++++++----------- skills/review/SKILL.md | 6 ++-- skills/simulate/SKILL.md | 4 +-- 13 files changed, 102 insertions(+), 101 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c32ae1..0ad4a3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,13 +5,14 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th ## [Unreleased] ### Changed -- `query/SKILL.md` — description now lists the standards surface (auctions, crowdfunds, payment-requests, intents, smart-tokens, etc) alongside the raw API routes. Added a "Standards shortcuts" section pointing Claude at `bitbadges-cli list / show / status` as the preferred route over `bitbadges-cli api ...` when the user asks about a standard by name. API route count bumped from 104 → 106 (SDK #223 + #228 added 27+ indexer routes including consolidated `/swap/*` and gamm queries). -- `broadcast/SKILL.md` — added a fifth signing path (`deploy --with-keyring --from `) for headless CLI-only flows that already have a key in the chain binary's keyring; the CLI prints + runs the equivalent `bitbadgeschaind tx ...` so users see what's being signed. Added a top-level note about `--wait-for-indexer [timeout-ms]` for agent scripts that immediately need to query the newly-created entity. +- CLI v2 short-form sweep — every plugin page, skill, and slash command now uses the flat `bb ` invocation instead of the deprecated `bb cli ` form. Renames applied: `portfolio` → `account` (absorbs `address convert/validate`, `lookup`, `alias`, `gen-list-id`), `config` → `settings`, `tools/tool` + `resources/docs/skills/gen-pub-key` moved under `dev`, `swap pools`/`swap asset-pairs` promoted to top-level `pools`/`pairs`, and `sign-with-browser` + `gen-tx-payload` folded into `bb deploy --browser` / `bb deploy --gen-payload`. The old `bb cli ` form still works for one release with a stderr deprecation banner (set `BB_QUIET=1` to suppress). Tracked under autopilot ticket #0399 and design doc `outputs/flagship-plans/cli-v2-design.md`. +- `query/SKILL.md` — description now lists the standards surface (auctions, crowdfunds, payment-requests, intents, smart-tokens, etc) alongside the raw API routes. Added a "Standards shortcuts" section pointing Claude at `bb list / show / status` as the preferred route over `bb api ...` when the user asks about a standard by name. API route count bumped from 104 → 106 (SDK #223 + #228 added 27+ indexer routes including consolidated `/swap/*` and gamm queries). +- `broadcast/SKILL.md` — added a fifth signing path (`bb deploy --with-keyring --from `) for headless CLI-only flows that already have a key in the chain binary's keyring; the CLI prints + runs the equivalent `bb tx ...` so users see what's being signed. Added a top-level note about `--wait-for-indexer [timeout-ms]` for agent scripts that immediately need to query the newly-created entity. ### Added - Initial scaffolding: plugin manifest, MCP server registration, README, LICENSE. - 8 skills, all hand-written as routing guides on top of the CLI / MCP / docs (no duplicated SDK content): - - `build` — meta-guide for constructing any token type. Routes Claude to `bitbadges-cli skills ` for canonical instructions and the per-field MCP tools for construction. + - `build` — meta-guide for constructing any token type. Routes Claude to `bb dev skills ` for canonical instructions and the per-field MCP tools for construction. - `review`, `simulate`, `explain` — pre-broadcast safety net. - `query`, `address`, `claim` — runtime ops. - `broadcast` — hard-railed live broadcast. @@ -22,4 +23,4 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th ### Design -The plugin is intentionally **a thin harness, not a knowledge base**. Token-type-specific instructions live in the SDK at `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts` and are surfaced to Claude on demand via `bitbadges-cli skills `, the `get_skill_instructions` MCP tool, and the Gitbook pages at https://docs.bitbadges.io/x-tokenization/examples/skills/. The plugin's job is to teach Claude where to find them and how to compose them — not to ship 22 routing wrappers that just point at the same content. +The plugin is intentionally **a thin harness, not a knowledge base**. Token-type-specific instructions live in the SDK at `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts` and are surfaced to Claude on demand via `bb dev skills `, the `get_skill_instructions` MCP tool, and the Gitbook pages at https://docs.bitbadges.io/x-tokenization/examples/skills/. The plugin's job is to teach Claude where to find them and how to compose them — not to ship 22 routing wrappers that just point at the same content. diff --git a/README.md b/README.md index 7632f77..3571ff9 100644 --- a/README.md +++ b/README.md @@ -14,22 +14,22 @@ curl -fsSL https://install.bitbadges.io | sh This installs `bitbadgeschaind` (the chain binary), `bitbadges-cli` (the JS SDK CLI that exposes 106+ API routes plus the `bitbadges-builder` MCP server), and a friendly `bb` alias that wraps `bitbadgeschaind`. This plugin is a Claude Code convenience layer on top of those — it does not replace them. -## Two entrypoints — when to use which +## One binary, one flat surface -There are two binaries on PATH after install, and the skills route to each one accordingly: +After install, `bb` is the single user-facing name. Every SDK command lives at the top level — no `cli` infix needed. The plugin skills standardize on this short form: | Form | What it covers | When skills use it | |---|---|---| -| **`bb cli `** (preferred) | The full Node SDK CLI surface — `build`, `deploy`, `api`, `auctions`, `crowdfunds`, `intents`, `auth`, etc. `bb cli` is `bitbadgeschaind cli` is `bitbadges-cli` — same code, friendlier alias. | Almost all skills (`build`, `query`, `simulate`, `explain`, `review`, `claim`, `address`, most of `broadcast`). | -| **`bitbadgeschaind tx \| query \| keys`** (no `cli` forwarder) | Native Cosmos chain-binary surface — keyring management, signing, on-chain queries. NOT forwarded through `bitbadges-cli`. | `broadcast` skill's "chain binary" path (`bitbadgeschaind tx `). Address skill's keyring lookups. | -| **`bitbadges-cli `** (direct) | Same as `bb cli ` — the underlying JS binary, no chain-binary wrapper. Use when the chain binary isn't on PATH or scripts pin the JS-only entry. | Fallback only — examples in the skills standardize on `bb cli` for terseness. | +| **`bb `** (preferred) | Everything. The full SDK surface — `build`, `deploy`, `api`, `auctions`, `crowdfunds`, `intents`, `auth`, `account`, `pools`, `pairs`, `dev`, `settings`, etc. — plus every Cosmos-native surface (`tx`, `query`, `keys`) on the same binary. | Every skill. | +| **`bitbadges-cli `** (direct) | Same SDK surface as `bb `, just the underlying JS binary. Use only when the chain binary isn't on PATH or a script pins the JS-only entry. | Fallback only. | +| **`bb cli `** (deprecated alias) | Same as `bb `. Kept for one release so existing scripts and demos keep working — emits a one-line deprecation banner to stderr. Set `BB_QUIET=1` to suppress. | Never — examples have all moved to `bb `. | -**Rule of thumb**: when in doubt, use `bb cli `. The only time you must use `bitbadgeschaind` directly is for the Cosmos-native surface (`tx`, `query`, `keys`) — those don't have a `bb cli` equivalent because they're not part of the JS SDK. +**Rule of thumb**: when in doubt, use `bb `. Chain-native surfaces (`tx`, `query`, `keys`) live there too — `bb --help` groups them as "Chain operations" so you can tell at a glance which side of the binary owns each command. Get an API key at [bitbadges.io/developer](https://bitbadges.io/developer) and configure it once: ```sh -bb cli config set apiKey YOUR_KEY +bb settings set apiKey YOUR_KEY ``` ## Install the plugin @@ -47,10 +47,10 @@ Then run `/bitbadges:setup` once to verify everything is wired and `/bitbadges:s - **MCP tools** — `bitbadges-builder` registered automatically (no separate `claude mcp add` step). Exposes 50+ session-based per-field token construction tools, queries, validation, review, and simulation. - **8 skills** — guides that route Claude to the right CLI command, MCP tool, or docs page for each common BitBadges workflow: - - `build` — meta-guide for building any token type. Discovers via `bitbadges-cli skills`, loads canonical instructions from the SDK, constructs via per-field MCP tools. - - `review`, `simulate`, `explain` — pre-broadcast safety net. Wraps `bitbadges-cli check`, MCP `simulate_transaction`, and `bitbadges-cli explain`. + - `build` — meta-guide for building any token type. Discovers via `bb dev skills`, loads canonical instructions from the SDK, constructs via per-field MCP tools. + - `review`, `simulate`, `explain` — pre-broadcast safety net. Wraps `bb check`, MCP `simulate_transaction`, and `bb explain`. - `query`, `address`, `claim` — runtime ops. Wraps the API routes, address derivations, and claim builder respectively. - - `broadcast` — hard-railed signer. Picks one of four signing paths based on what wallet the user has (chain binary, browser bridge via `/sign`, throwaway burner, or programmatic `gen-tx-payload`). Dry-run by default, explicit confirmation for live. + - `broadcast` — hard-railed signer. Picks one of four signing paths based on what wallet the user has (chain binary, browser bridge via `/sign`, throwaway burner, or programmatic `bb deploy --gen-payload`). Dry-run by default, explicit confirmation for live. - **2 slash commands** — `/bitbadges:setup` (one-time prereq check + API key wiring) and `/bitbadges:status` (health check). - **`bitbadges-builder` subagent** for focused builder loops. - **SessionStart pre-warm** so the first MCP-tool call doesn't pay npx download latency. diff --git a/agents/bitbadges-builder.md b/agents/bitbadges-builder.md index f801b69..ff4cc97 100644 --- a/agents/bitbadges-builder.md +++ b/agents/bitbadges-builder.md @@ -9,9 +9,9 @@ You are a BitBadges builder subagent. Your job is to take a token-creation or tr ## Tool preference 1. **MCP tools first.** The `bitbadges-builder` MCP server exposes 50+ tools for session management, token construction, review, simulation, and queries. Use `set_standards`, `set_invariants`, `add_approval`, `validate_transaction`, `review_collection`, `simulate_transaction`, `get_skill_instructions`, etc. directly — don't shell out unless MCP is unavailable. -2. **CLI fallback.** If an MCP tool isn't available or the user is doing something off the happy path (custom queries, address derivations not exposed via MCP), fall back to `bitbadges-cli` subcommands: `sdk`, `api`, `builder`, `config`. -3. **Chain binary** (`bitbadgeschaind`) for key management and live broadcasts when the user has a bb1 key in the keyring. Default to dry-run; require explicit user confirmation for live broadcasts. -4. **Browser bridge / programmatic helpers** (`bitbadges-cli deploy --browser`, `gen-tx-payload`, `gen-pub-key`) when the user has a browser wallet, no wallet at all, or a custom signer. See the `broadcast` skill for the four-path decision matrix. +2. **CLI fallback.** If an MCP tool isn't available or the user is doing something off the happy path (custom queries, address derivations not exposed via MCP), fall back to `bb` subcommands: `sdk`, `api`, `builder`, `settings`. +3. **Chain binary** (`bb tx`, `bb keys`) for key management and live broadcasts when the user has a bb1 key in the keyring. Default to dry-run; require explicit user confirmation for live broadcasts. +4. **Browser bridge / programmatic helpers** (`bb deploy --browser`, `bb deploy --gen-payload`, `bb dev gen-pub-key`) when the user has a browser wallet, no wallet at all, or a custom signer. See the `broadcast` skill for the four-path decision matrix. ## Workflow on a creation task @@ -22,10 +22,10 @@ You are a BitBadges builder subagent. Your job is to take a token-creation or tr 5. `simulate_transaction` to dry-run. 6. Show the user the simulator output and ask explicitly before broadcasting. 7. Route the broadcast based on what the user actually has. Pick one — don't guess if you don't know: - - **Chain binary** (`bitbadgeschaind tx ...`): bb1 key in keyring, hardware wallet via ADR-36. - - **Browser bridge** (`bitbadges-cli deploy --browser`): user has only a browser wallet (Keplr / MetaMask / Phantom). CLI opens `/sign` on bitbadges.io, user reviews + signs, hash comes back to terminal. Add `--sign-only` to skip broadcast and return signed bytes for caller-controlled submission. - - **Burner** (`bitbadges-cli deploy --burner --manager bb1...`): zero-wallet one-shot create-collection. Throwaway signer, faucet-funded, discarded. CREATE-only. - - **Programmatic** (`bitbadges-cli gen-tx-payload --from bb1...` or `0x...`): for custom signers — cosmjs, ethers/viem, hardware that takes raw bytes, custodial. Returns the full SignDoc envelope (signDirect + legacyAmino + evmTx) plus pre-resolved account state. Pair with `bitbadges-cli gen-pub-key` if the account is fresh and the indexer has no pubkey on file. See the `broadcast` skill for path-by-path failure modes. + - **Chain binary** (`bb tx ...`): bb1 key in keyring, hardware wallet via ADR-36. + - **Browser bridge** (`bb deploy --browser`): user has only a browser wallet (Keplr / MetaMask / Phantom). CLI opens `/sign` on bitbadges.io, user reviews + signs, hash comes back to terminal. Add `--sign-only` to skip broadcast and return signed bytes for caller-controlled submission. + - **Burner** (`bb deploy --burner --manager bb1...`): zero-wallet one-shot create-collection. Throwaway signer, faucet-funded, discarded. CREATE-only. + - **Programmatic** (`bb deploy --gen-payload --from bb1...` or `0x...`): for custom signers — cosmjs, ethers/viem, hardware that takes raw bytes, custodial. Returns the full SignDoc envelope (signDirect + legacyAmino + evmTx) plus pre-resolved account state. Pair with `bb dev gen-pub-key` if the account is fresh and the indexer has no pubkey on file. See the `broadcast` skill for path-by-path failure modes. ## Always diff --git a/commands/setup.md b/commands/setup.md index 0f6d583..ca2c806 100644 --- a/commands/setup.md +++ b/commands/setup.md @@ -13,7 +13,7 @@ The chain + CLI install is **the** entrypoint. The plugin's `npx`-based MCP fall 1. **Chain binary check (required).** If `bitbadgeschaind` is on PATH, print the version. If not, print the install one-liner (`curl -fsSL https://install.bitbadges.io | sh`) and ask for explicit consent before running it. Never auto-pipe `curl ... | sh` — show the command, wait for "yes". 2. **CLI check (required).** Same flow — if `bitbadges-cli` is on PATH, OK; otherwise the same one-liner installs both binaries together. The presence of `bitbadges-cli` globally also means the `bitbadges-builder` MCP bin is on PATH, which is faster and more reliable than the plugin's npx fallback. -3. **API key (required).** If `~/.bitbadges/config.json` already has an `apiKey`, use it — no prompt. The CLI config is canonical; both the CLI and the plugin read from there. Otherwise prompt for the key and write via `bitbadges-cli config set apiKey `. Source: https://bitbadges.io/developer. +3. **API key (required).** If `~/.bitbadges/config.json` already has an `apiKey`, use it — no prompt. The CLI config is canonical; both the CLI and the plugin read from there. Otherwise prompt for the key and write via `bb settings set apiKey `. Source: https://bitbadges.io/developer. 4. **Migration check (optional).** If the user previously ran `claude mcp add bitbadges-builder ...` manually (user scope), that registration coexists with the plugin's `.mcp.json` entry and produces duplicate MCP servers. Detect it (`claude mcp list | grep bitbadges-builder`) and offer to run `claude mcp remove bitbadges-builder` to clean up. ## Behavior summary for Claude diff --git a/commands/status.md b/commands/status.md index a697097..8b6703e 100644 --- a/commands/status.md +++ b/commands/status.md @@ -7,14 +7,14 @@ argument-hint: (no arguments) A one-shot diagnostic. Runs `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh` and reports: -- `bitbadgeschaind` version (or "not installed"). -- `bitbadges-cli` version (resolved via `npx bitbadges --version`). +- `bb` chain binary version (or "not installed"). +- `bb` SDK version (resolved via `bb --version`). - Active network (mainnet / testnet / local). -- API connectivity (`bitbadges-cli doctor`). +- API connectivity (`bb doctor`). - API key configured (yes/no, masked). - MCP server `bitbadges-builder` is reachable. -Output is human-readable by default; the underlying `bitbadges-cli doctor` always emits the universal `{ok, data, warnings, error}` envelope to stdout with the colored scorecard on stderr. Slash commands surface the human form. +Output is human-readable by default; the underlying `bb doctor` always emits the universal `{ok, data, warnings, error}` envelope to stdout with the colored scorecard on stderr. Slash commands surface the human form. ## When to use diff --git a/skills/address/SKILL.md b/skills/address/SKILL.md index 8c84e52..2b2c780 100644 --- a/skills/address/SKILL.md +++ b/skills/address/SKILL.md @@ -9,8 +9,8 @@ BitBadges runs on a Cosmos chain with EVM compatibility, so addresses come in tw ## Conversion ```bash -bitbadges-cli address convert
--to -bitbadges-cli address validate
+bb account convert
--to +bb account validate
``` `bb1...` ↔ `0x...` is deterministic — same key, two encodings. The CLI handles the bech32/hex math. @@ -19,9 +19,9 @@ bitbadges-cli address validate
| Need | Command | |---|---| -| Backing address for an IBC denom (smart-token deposits) | `bitbadges-cli alias for-ibc-backing ` | -| Wrapper address for a collection | `bitbadges-cli alias for-wrapper ` | -| Mint-escrow address for a collection | `bitbadges-cli alias for-mint-escrow ` | +| Backing address for an IBC denom (smart-token deposits) | `bb account alias for-ibc-backing ` | +| Wrapper address for a collection | `bb account alias for-wrapper ` | +| Mint-escrow address for a collection | `bb account alias for-mint-escrow ` | These are protocol-controlled addresses with auto-set approvals. Don't try to write to them directly — use the corresponding flow (IBC backing, mint, etc.). diff --git a/skills/broadcast/SKILL.md b/skills/broadcast/SKILL.md index 5691c58..f3cfbed 100644 --- a/skills/broadcast/SKILL.md +++ b/skills/broadcast/SKILL.md @@ -12,11 +12,11 @@ There are five signing paths. Choose based on what the user actually has — not | What the user has | Use | |---|---| -| A bb1 key in `bitbadgeschaind keys` and a CLI workflow | **`deploy --with-keyring --from `** — the CLI prints the equivalent `bitbadgeschaind tx ...` command, runs it, returns the response. Best for headless scripts. | -| Same but driving the chain binary directly | **Chain binary** — `bitbadgeschaind tx ...` | -| Just a browser wallet (Keplr, MetaMask, Phantom) | **Browser bridge** — `bitbadges-cli deploy --browser` | -| Want zero wallet setup for a one-shot create-collection | **Burner** — `bitbadges-cli deploy --burner` | -| A programmatic signer (cosmjs / ethers / viem / hardware that takes raw bytes) | **gen-tx-payload** — produces SignDoc bytes, user signs in their own code | +| A bb1 key in `bb keys` and a CLI workflow | **`bb deploy --with-keyring --from `** — the CLI prints the equivalent `bb tx ...` command, runs it, returns the response. Best for headless scripts. | +| Same but driving the chain binary directly | **Chain binary** — `bb tx ...` | +| Just a browser wallet (Keplr, MetaMask, Phantom) | **Browser bridge** — `bb deploy --browser` | +| Want zero wallet setup for a one-shot create-collection | **Burner** — `bb deploy --burner` | +| A programmatic signer (cosmjs / ethers / viem / hardware that takes raw bytes) | **`bb deploy --gen-payload`** — produces SignDoc bytes, user signs in their own code | If the user can't tell you which they have, ask. Don't guess. The simulator and review steps are identical regardless of path. @@ -25,7 +25,7 @@ If the user can't tell you which they have, ask. Don't guess. The simulator and After broadcast succeeds, the indexer is eventually-consistent — querying the new collection / dynamic store immediately can 404 for a few seconds. Add `--wait-for-indexer [timeout-ms]` (default 30000) to any `deploy` invocation to poll until the entity appears, so the next step in an agent script can rely on it. The CLI returns a `waited: { entity, id, attempts, elapsedMs, ok }` field on the response envelope. ```bash -bitbadges-cli deploy --burner --msg-stdin --manager bb1... \ +bb deploy --burner --msg-stdin --manager bb1... \ --wait-for-indexer ``` @@ -39,47 +39,47 @@ Skip the flag when you don't need to query the entity immediately afterwards. If any are missing, stop. -## Path 1 — Chain binary (`bitbadgeschaind`) +## Path 1 — Chain binary (`bb tx`) For headless agents with a bb1 key in the keyring, or hardware-wallet flows. ```bash # Default: dry-run -bitbadgeschaind tx --from --dry-run +bb tx --from --dry-run # Live broadcast — only after explicit user confirmation -bitbadgeschaind tx --from -y +bb tx --from -y ``` Network flags: - Mainnet (default): no flag - Testnet: `--node https://rpc-testnet.bitbadges.io --chain-id bitbadges-1-testnet` -## Path 1b — CLI keyring shortcut (`deploy --with-keyring --from `) +## Path 1b — CLI keyring shortcut (`bb deploy --with-keyring --from `) -Same outcome as Path 1, but you stay inside `bitbadges-cli`. The CLI inspects the msg JSON, prints the equivalent `bitbadgeschaind tx ...` command (so users see exactly what's being signed), executes it, and returns the chain response. Best when you've already piped a `build` output and don't want to context-switch: +Same outcome as Path 1, but you stay inside the build pipeline. The CLI inspects the msg JSON, prints the equivalent `bb tx ...` command (so users see exactly what's being signed), executes it, and returns the chain response. Best when you've already piped a `build` output and don't want to context-switch: ```bash -bitbadges-cli build vault --name … \ - | bitbadges-cli deploy --with-keyring --from mykey --msg-stdin \ +bb build vault --name … \ + | bb deploy --with-keyring --from mykey --msg-stdin \ --keyring-backend test --manager bb1… ``` The msg is unrestricted — works for any tokenization msg, not just create-collection. -## Path 2 — Browser bridge (`deploy --browser`) +## Path 2 — Browser bridge (`bb deploy --browser`) For users whose wallet only lives in a browser extension (Keplr, MetaMask, Phantom, WalletConnect). The CLI opens `/sign` on bitbadges.io, the user reviews + signs in their wallet, the tx hash comes back to the terminal. ```bash # Standard sign + broadcast -bitbadges-cli deploy --browser --msg-file tx.json --manager bb1... +bb deploy --browser --msg-file tx.json --manager bb1... # Sign-only (return signed tx bytes, caller broadcasts on its own schedule) -bitbadges-cli deploy --browser --sign-only --msg-file tx.json --manager bb1... +bb deploy --browser --sign-only --msg-file tx.json --manager bb1... # Compose with build in one step -bitbadges-cli build vault --name X --image Y --description Z --manager bb1... \ +bb build vault --name X --image Y --description Z --manager bb1... \ --backing-coin BADGE --deploy-with-browser ``` @@ -90,35 +90,35 @@ For SSH-tunneled dev (laptop browser, server-side CLI): pin a port with `--port Auth (Full Access session) flow with the same bridge: ```bash -bitbadges-cli auth login --browser --address bb1... +bb auth login --browser --address bb1... ``` Pubkey is captured from the wallet's signature response — no `--public-key` to manage. -## Path 3 — Burner (`deploy --burner`) +## Path 3 — Burner (`bb deploy --burner`) For agents and one-shot scripts that just want to ship a create-collection without bringing any wallet at all. CLI generates a throwaway signer, funds it from the faucet (or manually), broadcasts once, discards. CREATE-only. ```bash -bitbadges-cli deploy --burner --msg-file tx.json --manager bb1... +bb deploy --burner --msg-file tx.json --manager bb1... ``` `--manager` (the bb1 the user actually controls) captures lasting collection ownership. The burner's only job is paying for one broadcast. -## Path 4 — `gen-tx-payload` for programmatic signers +## Path 4 — `bb deploy --gen-payload` for programmatic signers For custom EVM wallets, ethers/viem scripts, hardware wallets that take raw SignDoc bytes, custodial signers — anything that isn't the chain binary or a browser wallet. ```bash # Cosmos signer (cosmjs / hardware wallet) -bitbadges-cli build vault ... --quiet \ - | bitbadges-cli gen-tx-payload --from bb1... --gas 600000 +bb build vault ... --quiet \ + | bb deploy --gen-payload --from bb1... --gas 600000 # EVM-only signer (ethers / viem on the BitBadges EVM chain) -bitbadges-cli gen-tx-payload --msg-file tx.json --from 0x... --gas 600000 +bb deploy --gen-payload --msg-file tx.json --from 0x... --gas 600000 # Both, in one envelope -bitbadges-cli gen-tx-payload --msg-file tx.json --from bb1... --with-evm-tx --gas 600000 +bb deploy --gen-payload --msg-file tx.json --from bb1... --with-evm-tx --gas 600000 ``` Output is a self-contained JSON envelope: `signDirect.{bodyBytes, authInfoBytes, signBytes}`, `legacyAmino.{...}`, `evmTx.{to, data, value, chainId, gasLimit}`, plus pre-resolved chain id, account number, sequence, public key, fee, memo, and the broadcast endpoint URL. The caller signs the bytes locally and assembles a TxRaw to POST. @@ -127,19 +127,19 @@ For fresh accounts where the indexer doesn't have a public key yet, derive one w ```bash # Lookup-only path: indexer + chain LCD -bitbadges-cli gen-pub-key --address bb1... +bb dev gen-pub-key --address bb1... # Recovery path: user signs a fixed canonical message, no mnemonic needed -bitbadges-cli gen-pub-key --print-message # prints what to sign -bitbadges-cli gen-pub-key --address bb1... --signature +bb dev gen-pub-key --print-message # prints what to sign +bb dev gen-pub-key --address bb1... --signature ``` -`gen-pub-key` never asks for a mnemonic or signing material — the user signs the canonical message in their own wallet (Keplr signArbitrary, hardware wallet, air-gapped script), and the CLI iterates the secp256k1 recovery candidates to find the one matching the address. +`bb dev gen-pub-key` never asks for a mnemonic or signing material — the user signs the canonical message in their own wallet (Keplr signArbitrary, hardware wallet, air-gapped script), and the CLI iterates the secp256k1 recovery candidates to find the one matching the address. ## Failure modes (path-specific) **Chain binary:** -- "bitbadgeschaind: command not found" — route to `/bitbadges:setup`. +- "bb: command not found" — route to `/bitbadges:setup`. - "key not found" — list available keys, ask which to use. - "insufficient fees" / "out of gas" — let the binary auto-estimate (`--gas auto`) and retry, or have the user bump the cap. @@ -151,19 +151,19 @@ bitbadges-cli gen-pub-key --address bb1... --signature **Burner:** - "faucet refused" — non-local network without faucet enabled. Use `--fund manual` and prefund the burner address. -- "insufficient balance" — sweep dust out via `bitbadges-cli burner sweep --to `. +- "insufficient balance" — sweep dust out via `bb burner sweep --to `. -**gen-tx-payload:** -- "Missing public key" — fresh account; run `gen-pub-key` first or pass `--public-key` explicitly. +**`bb deploy --gen-payload`:** +- "Missing public key" — fresh account; run `bb dev gen-pub-key` first or pass `--public-key` explicitly. - "Indexer fetch failed" — pass `--no-fetch` with explicit `--account-number`, `--sequence`, `--public-key`. -- "Unsupported message type" — `gen-tx-payload` covers every `tokenization.Msg*` type (the output of `bitbadges-cli build`). Other modules (IBC, gov, custom) need to be proto-encoded by the caller. +- "Unsupported message type" — `bb deploy --gen-payload` covers every `tokenization.Msg*` type (the output of `bb build`). Other modules (IBC, gov, custom) need to be proto-encoded by the caller. ## Hard don'ts - Don't broadcast to mainnet without explicit user confirmation in the same turn. - Don't broadcast a transaction that hasn't been simulated. - Don't loop a failing broadcast more than twice — stop and report rather than chewing through fees. -- Don't ask the user for a mnemonic or signing material. The browser bridge captures pubkeys from the wallet's response. `gen-pub-key` recovers them from a signed canonical message. Neither path needs the user to expose anything. +- Don't ask the user for a mnemonic or signing material. The browser bridge captures pubkeys from the wallet's response. `bb dev gen-pub-key` recovers them from a signed canonical message. Neither path needs the user to expose anything. - Don't conflate the four paths. Picking the wrong one wastes time at best and wastes funds at worst. ## Reference diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md index a9bf930..e12c2d3 100644 --- a/skills/build/SKILL.md +++ b/skills/build/SKILL.md @@ -11,8 +11,8 @@ The plugin does not redefine token types here. They live in the SDK and are surf ## Step 1 — Discover the available token type ```sh -bitbadges-cli skills # list every available skill (id, name, category, description) -bitbadges-cli skills # load the canonical instructions for one skill +bb dev skills # list every available skill (id, name, category, description) +bb dev skills # load the canonical instructions for one skill ``` If the user describes their goal but doesn't name a token type, list the catalog first and pick by category. Categories: `token-type`, `standard`, `approval`, `feature`, `advanced`. @@ -24,7 +24,7 @@ Web reference: every skill is also rendered at `https://docs.bitbadges.io/x-toke The instructions are the source of truth — required fields, approval ordering, foot-guns, reference collection IDs. Load them, don't reconstruct them: - **MCP (preferred in Claude Code):** call `get_skill_instructions` with `id: ""`. -- **CLI:** `bitbadges-cli skills ` +- **CLI:** `bb dev skills ` - **Web docs:** `https://docs.bitbadges.io/x-tokenization/examples/skills/` ## Step 3 — Construct the transaction @@ -47,11 +47,11 @@ Only then route to the `broadcast` skill, which has its own hard rails. ## Going deeper -The CLI's `docs` command surfaces the full Gitbook docs from your terminal. Use it when a skill instruction references a concept you need to look up: +The CLI's `dev docs` command surfaces the full Gitbook docs from your terminal. Use it when a skill instruction references a concept you need to look up: ```sh -bitbadges-cli docs all # dump the entire docs corpus -bitbadges-cli docs # specific page, e.g. learn/approvals +bb dev docs all # dump the entire docs corpus +bb dev docs # specific page, e.g. learn/approvals ``` You also have full access to the public docs at `https://docs.bitbadges.io` if you need to fetch a page directly. Fetch only what you need; don't dump entire sections into the context for fun. diff --git a/skills/claim/SKILL.md b/skills/claim/SKILL.md index cfc8415..29940a9 100644 --- a/skills/claim/SKILL.md +++ b/skills/claim/SKILL.md @@ -23,14 +23,14 @@ Use the `build_claim` MCP tool with the desired plugins (gating modes) and appro ## Audit existing ```bash -bitbadges-cli api claims get-claim +bb api claims get-claim ``` Then review for: overlapping plugins (e.g. password + open), expired time windows, max-uses set or unset, and whether the underlying approval still has supply. ## Failure modes -- Mismatched plugin ids — the CLI / MCP will reject; confirm against `bitbadges-cli api --help-json` if unsure. +- Mismatched plugin ids — the CLI / MCP will reject; confirm against `bb api --help-json` if unsure. - Gating mode that doesn't compose with the chosen approval (e.g. open claim against a 1-use approval). ## Don't diff --git a/skills/explain/SKILL.md b/skills/explain/SKILL.md index 4f7f960..16b4f88 100644 --- a/skills/explain/SKILL.md +++ b/skills/explain/SKILL.md @@ -19,13 +19,13 @@ Use when the user wants natural-language understanding rather than raw JSON. Call the `explain_collection` MCP tool with `collectionId: ""` and an `audience` of `user`, `developer`, or `auditor`. CLI fallback: ```bash -bitbadges-cli explain +bb explain ``` **Transaction file:** ```bash -bitbadges-cli explain @.json +bb explain @.json ``` The CLI auto-detects whether the input is a transaction or a collection. The `--audience` selector currently only exists on the MCP tool path. diff --git a/skills/query/SKILL.md b/skills/query/SKILL.md index ae561e0..fbc64bc 100644 --- a/skills/query/SKILL.md +++ b/skills/query/SKILL.md @@ -11,8 +11,8 @@ Use this skill any time the user wants on-chain or off-chain BitBadges data — LLMs frequently hallucinate route paths. The CLI exposes the full API tree as JSON — always discover, then query. ```bash -bitbadges-cli api --help-json -bitbadges-cli api --help-json # e.g. tokens, accounts, claims, addresses +bb api --help-json +bb api --help-json # e.g. tokens, accounts, claims, addresses ``` The `--help-json` output is the source of truth for routes and parameters. Read it before calling a route you're not 100% sure exists. @@ -21,11 +21,11 @@ The `--help-json` output is the source of truth for routes and parameters. Read | Need | Command | |---|---| -| Collection details | `bitbadges-cli api tokens get-collection ` | -| Balances for an address | `bitbadges-cli api tokens get-balance
` | -| Account profile | `bitbadges-cli api accounts get-account
` | -| Claim status | `bitbadges-cli api claims get-claim ` | -| Address list contents | `bitbadges-cli api address-lists get-list ` | +| Collection details | `bb api tokens get-collection ` | +| Balances for an address | `bb api tokens get-balance
` | +| Account profile | `bb api accounts get-account
` | +| Claim status | `bb api claims get-claim ` | +| Address list contents | `bb api address-lists get-list ` | Or use the MCP fast-paths: `query_collection`, `query_balance`, `verify_ownership`. @@ -34,19 +34,19 @@ Or use the MCP fast-paths: `query_collection`, `query_balance`, `verify_ownershi For every BitBadges standard the CLI exposes a typed list / show / status surface that's friendlier than the raw indexer routes. Reach for these BEFORE `api ...` when the user asks about a standard by name: ```bash -bitbadges-cli auctions list # browse active auctions -bitbadges-cli auctions show 42 # one auction -bitbadges-cli auctions status 42 # bidding | accepting | sold | expired - -bitbadges-cli crowdfunds list # crowdfund campaigns -bitbadges-cli pay-requests list --mine bb1... # payment requests TO me -bitbadges-cli intents list --pay-denom uusdc # intent-exchange offers -bitbadges-cli prediction-markets list --open # active prediction markets -bitbadges-cli credit-tokens show # one credit-token collection -bitbadges-cli smart-tokens status # one smart token -bitbadges-cli subscriptions status # subscription tier status -bitbadges-cli swap assets / chains / balances # cross-chain swap surface -bitbadges-cli dynamic-stores list-values # on-chain key→bool map +bb auctions list # browse active auctions +bb auctions show 42 # one auction +bb auctions status 42 # bidding | accepting | sold | expired + +bb crowdfunds list # crowdfund campaigns +bb pay-requests list --mine bb1... # payment requests TO me +bb intents list --pay-denom uusdc # intent-exchange offers +bb prediction-markets list --open # active prediction markets +bb credit-tokens show # one credit-token collection +bb smart-tokens status # one smart token +bb subscriptions status # subscription tier status +bb swap assets / chains / balances # cross-chain swap surface +bb dynamic-stores list-values # on-chain key→bool map ``` Every standard supports `--mine ` (or equivalent) to scope to a specific user. Add `--testnet` / `--local` for non-mainnet. Output is structured JSON. The full surface lives at the docs Standards Commands reference. diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md index 5374b92..8d5f5b4 100644 --- a/skills/review/SKILL.md +++ b/skills/review/SKILL.md @@ -17,20 +17,20 @@ Use this skill any time the user has built a BitBadges transaction or wants a se **Transaction file review (input is a path):** ```bash -bitbadges-cli check @ --depth review +bb check @ --depth review ``` Or run the full pass (validate + review + metadata, the default depth): ```bash -bitbadges-cli check @ +bb check @ ``` The CLI accepts `@file.json` syntax for path inputs. JSON output includes parsed warnings, errors, and suggestions. **Live collection review (input is a numeric ID or a collection ID string):** -Call the `review_collection` MCP tool with `collectionId: ""`. Falls back to `bitbadges-cli api tokens get-collection ` + manual inspection if MCP isn't available. +Call the `review_collection` MCP tool with `collectionId: ""`. Falls back to `bb api tokens get-collection ` + manual inspection if MCP isn't available. ## What good output looks like diff --git a/skills/simulate/SKILL.md b/skills/simulate/SKILL.md index fe6949e..10742e0 100644 --- a/skills/simulate/SKILL.md +++ b/skills/simulate/SKILL.md @@ -21,13 +21,13 @@ Call the `simulate_transaction` MCP tool with the transaction object. **Via CLI:** ```bash -bitbadges-cli simulate @ +bb simulate @ ``` Or pipe a transaction via stdin: ```bash -cat tx.json | bitbadges-cli simulate - +cat tx.json | bb simulate - ``` ## What good output looks like