Utility Commands

Catch-all reference for the CLI's smaller utility verbs β€” discovery, address tooling, lookup, and connectivity.

Command
Purpose

Browse BitBadges documentation locally

Shorthand for bb dev docs builder-skills β€” list or show Builder skills

Address conversion and validation

Look up token info by symbol

Generate a reserved address list ID

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.

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.

Equivalent to bb dev docs builder-skills / bb dev docs builder-skills/<id>.

account convert / validate

Convert and validate BitBadges addresses.

Subcommand
Flag
Description

convert <address>

--to <bb1|0x>

Convert to the target format

validate <address>

β€”

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.).

Subcommand
Purpose

for-ibc-backing <ibcDenom>

Backing address for an IBC-backed smart token (deposits land here)

for-wrapper <denom>

Wrapper path address for a Cosmos coin wrapper

for-mint-escrow <collectionId>

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.

Flag
Description

--output-file <path>

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.

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.

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

Last updated