# Utility Commands Catch-all reference for the CLI's smaller utility verbs — discovery, address tooling, lookup, and connectivity. | Command | Purpose | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [`bb dev docs [section]`](#dev-docs) | Browse BitBadges documentation locally | | [`bb dev skills [id]`](#dev-skills) | Shorthand for `bb dev docs builder-skills` — list or show Builder skills | | [`bb account convert \| validate`](#account-convert-validate) | Address conversion and validation | | [`bb account alias for-ibc-backing \| for-wrapper \| for-mint-escrow`](#account-alias) | Generate protocol-derived alias addresses | | [`bb account lookup [symbol]`](#account-lookup) | Look up token info by symbol | | [`bb account gen-list-id `](#account-gen-list-id) | Generate a reserved address list ID | | [`bb doctor`](#doctor) | Environment + connectivity health check | > All six address / lookup verbs sit under `bb account` so the top-level help is the place to discover anything account-flavored. The `bb account` umbrella also covers `bb account all`, `bb account balances`, `bb account approvals`, etc. — the former `portfolio` aggregator. ## dev docs Browse BitBadges documentation. Fetched from GitHub on first use, cached locally for 24 hours. ```bash bb dev docs # show section tree bb dev docs all # dump full corpus bb dev docs learn # specific section bb dev docs learn/approval-criteria # nested with slash bb dev docs learn/approval-criteria/merkle-challenges bb dev docs --refresh # force cache refresh ``` Partial matching: `bb dev docs approvals` finds the first section containing "approvals". | Flag | Description | | ----------- | ------------------------------------ | | `--refresh` | Force refresh the cached docs corpus | Cache: `~/.bitbadges/docs-cache.json`. ## dev skills Shorthand for `bb dev docs builder-skills` — list or show one of the BitBadges Builder skills. ```bash bb dev skills # list all skills bb dev skills smart-token # specific skill ``` Equivalent to `bb dev docs builder-skills` / `bb dev docs builder-skills/`. ## account convert / validate Convert and validate BitBadges addresses. ```bash bb account convert 0x1234...abcd --to bb1 bb account convert bb1qpzm... --to 0x bb account validate bb1qpzm... # { "valid": true, "chain": "BitBadges", "address": "bb1qpzm..." } ``` | Subcommand | Flag | Description | | -------------------- | ---------------- | ------------------------------- | | `convert
` | `--to ` | Convert to the target format | | `validate
` | — | Check validity and detect chain | `bb1...` ↔ `0x...` is deterministic (same key, two encodings). The CLI handles the bech32/hex math. ## account alias Generate protocol-derived alias addresses — used wherever the chain auto-derives an account from input data (IBC denoms, collection IDs, etc.). ```bash bb account alias for-ibc-backing ibc/27394FB092D2ECCD... bb account alias for-wrapper ubadge bb account alias for-mint-escrow 42 ``` | Subcommand | Purpose | | -------------------------------- | ------------------------------------------------------------------------------ | | `for-ibc-backing ` | Backing address for an IBC-backed smart token (deposits land here) | | `for-wrapper ` | Wrapper path address for a Cosmos coin wrapper | | `for-mint-escrow ` | Mint-escrow address for a collection (where quest reward funds, etc. are sent) | 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.). ## account lookup Look up token info by symbol. Returns IBC denom, decimals, supported networks, and backing address (for IBC tokens). Omit the symbol to list every known token. ```bash bb account lookup # list every token bb account lookup BADGE # specific token ``` | Flag | Description | | ---------------------- | ------------------------------- | | `--output-file ` | Write the JSON output to a file | ## account gen-list-id Generate a reserved address list ID from a set of addresses. Used to deterministically reference an ad-hoc allow/deny list without registering it on-chain first. ```bash bb account gen-list-id bb1abc... bb1def... bb account gen-list-id bb1abc... --blacklist ``` | Flag | Description | | ------------- | ----------------------------------------- | | `--blacklist` | Treat as blacklist (default is whitelist) | ## doctor One-shot environment + connectivity health check. Replaces the old `sdk status` and `builder doctor` commands. ```bash bb doctor # six core probes bb doctor --testnet # probe against testnet bb doctor --json # machine-readable bb doctor --with-preview # add the preview-roundtrip probe ``` **Probes:** 1. Node version (must be ≥ 18) 2. SDK package + version (loaded from the bitbadges package.json) 3. CLI config file at `~/.bitbadges/config.json` 4. API key reachable for the resolved network (pings `/api/v0/simulate`) 5. MCP stdio bin presence 6. Persisted sessions parse 7. **(`--with-preview` only)** Preview upload + fetch roundtrip — builds a minimal tx, POSTs it to `/api/v0/builder/preview`, GETs it back, asserts the round trip is byte-equivalent | Flag | Description | | ------------------------------- | ----------------------------------------------------------------- | | `--json` | Output the full DoctorReport as JSON | | `--with-preview` | Add the preview-roundtrip probe | | `--testnet`, `--local`, `--url` | Network selection — controls which indexer the API-key probe hits | Each probe reports `PASS` / `FAIL` / `WARN` / `SKIP`. Exits non-zero only on hard failures; warnings and skips are informational. ## See also * [Build Commands](/for-developers/cli/build-commands.md), [Analysis Commands](/for-developers/cli/analysis-commands.md), [Deploy Commands](/for-developers/cli/deploy-commands.md), [Tool Commands](/for-developers/cli/tool-commands.md) — the rest of the CLI surface. * [Auth Commands](/for-developers/cli/auth-commands.md) — for endpoints that need a user-scoped session cookie on top of the API key. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bitbadges.io/for-developers/cli/utility-commands.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.