Analysis Commands

Once you have a transaction JSON in hand (from build, the MCP builder tools, or hand-rolled), the next step is to inspect it. The CLI ships four analysis verbs that all accept the same input shapes (JSON file path, @file.json token, inline JSON, numeric collection id where applicable, or - for stdin):

Command	Purpose
check <input>	Validate / review / metadata coverage in one pass — the unified analysis verb
explain <input>	Plain-English summary, auto-detects tx vs collection
simulate <input>	Dry-run against the indexer's simulate endpoint, returns gas + per-address balance changes
preview <input>	Upload to the indexer and print a shareable bitbadges.io preview URL

check and doctor (covered on the Utility Commands page) replace the old sdk review / builder verify / sdk status / builder doctor quartet.

check

bb check is the unified analysis entry point. It folds the old validate, review, and verify verbs into one command with a --depth dial.

bb check tx.json                       # full check (default)
bb check tx.json --depth structural    # validateTransaction() only
bb check tx.json --depth review        # reviewCollection() only
bb check 42 --depth review --testnet   # live collection, design audit
echo '{"messages":[...]}' | bb check -

Depth levels:

--depth	What it runs	Use when
structural	validateTransaction() only — uint ranges, approval criteria, structural correctness	Fast offline check before you commit JSON to disk
review	reviewCollection() only — design audit, standards conformance, UX checks	You're reviewing someone else's work or a live collection by id
full (default)	validate + review + design + metadata coverage, all rendered together	Pre-broadcast diligence; the most useful single-shot check

Common flags:

Flag	Description
--depth <level>	structural | review | full (default: full)
--strict	Exit 1 on warnings (criticals always exit 2)
--no-validate, --no-review, --no-metadata	Skip the corresponding section in --depth full
--design	Include the design-decisions section in --depth full's envelope payload (informational ✓/✗)
--condensed	Single-line JSON envelope (smaller pipe payload)
--output-file <path>	Write the envelope to a file instead of stdout
--testnet, --local, --url	Network selection for fetching numeric collection ids

Stdout is always the universal {ok, data, warnings, error} envelope; the human-readable scorecards print to stderr (suppress with --quiet / BB_QUIET=1).

check accepts collection ids on review and full depths (fetches the collection from the indexer first). structural is offline-only and refuses numeric ids — pass tx JSON directly.

explain

bb explain produces a plain-English summary. Auto-detects whether the input is a transaction or a collection and routes to the right interpreter.

bb explain tx.json
bb explain '{"messages":[...]}'
bb explain 42 --testnet           # numeric: fetch collection from indexer
echo '{"messages":[...]}' | bb explain -

Input detection:

• Single Msg { typeUrl, value: {...} } → walks value through interpretTransaction()

• Tx wrapper { messages: [{ typeUrl, value }, ...] } → finds the first collection msg and explains it

• Raw collection (no typeUrl, no messages) → walks through interpretCollection()

• Numeric <n> → fetches /api/v0/collection/<n> then walks through interpretCollection()

Flags:

Flag	Description
--output-file <path>	Write the envelope to a file instead of stdout
--condensed	Single-line JSON (smaller pipe payload)
--testnet, --local, --url	Network selection for numeric collection-id fetches

Output shape

explain always emits the universal envelope. The prose interpretation lives at data.fullText; agents that want a per-message breakdown read data.messages[].

bb explain tx.json
# {
#   "ok": true,
#   "data": {
#     "kind": "tx" | "collection" | "msg",
#     "messages": [
#       {
#         "typeUrl": "/tokenization.MsgCreateCollection",
#         "summary": "Create a new Smart Token (IBC-backed) called \"My Vault\" ..."
#       }
#     ],
#     "fullText": "...full prose interpretation..."
#   },
#   "warnings": [],
#   "error": null
# }

kind lets agents discriminate between transactions, raw collections, and bare messages. messages[] is empty for raw collection inputs; populated for tx wrappers and bare messages. fullText is included so callers that just want the human-readable text can jq -r .data.fullText instead of branching on shape.

Replaces the old sdk interpret-tx and sdk interpret-collection commands plus builder explain — one verb, auto-detect, one less mental dimension.

simulate

bb simulate dry-runs a transaction against the indexer's /api/v0/simulate endpoint. Returns the parsed events, per-address balance changes, and any errors that would have surfaced on-chain.

bb simulate tx.json
bb simulate tx.json --creator bb1mysigner...
bb simulate tx.json --events           # dump full events array
echo '{"messages":[...]}' | bb simulate -

Flags:

Flag	Description
--creator <address>	Override the simulation context address (default: a placeholder)
--events	Dump the full raw chain events array (default: just the count)
--condensed	Single-line JSON envelope (smaller pipe payload)
--output-file <path>	Write the envelope to a file instead of stdout
--testnet, --local, --url	Network selection

Stdout is the universal envelope wrapping SimulateResult in data. The terminal-friendly per-message breakdown prints to stderr (suppress with --quiet).

Requires BITBADGES_API_KEY (or per-network override) on mainnet/testnet. Local indexers usually accept any (or no) key.

User-level approval messages (MsgUpdateUserApprovals, MsgSetIncomingApproval, etc.) are explicitly refused — their semantics are state-change-on-existing-collection with set/append/delete variability and dry-running them isn't meaningful. Use check instead for those.

preview

bb preview uploads a transaction to the indexer and prints a shareable bitbadges.io/builder/preview?code=... URL. Intended for handing a tx off to a non-CLI reviewer for visual inspection without giving them edit/submit rights. Lives 1 hour in the indexer's Redis cache.

bb preview tx.json
bb preview tx.json --frontend-url https://staging.bitbadges.io
echo '{"messages":[...]}' | bb preview -

Flags:

Flag	Description
--frontend-url <url>	Override the bitbadges.io frontend base for the printed URL (default: https://bitbadges.io)
--condensed	Single-line JSON envelope
--output-file <path>	Write the envelope to a file instead of stdout
--testnet, --local, --url	Network selection — controls which indexer hosts the preview

Stdout is the universal envelope; the URL lives at data.url, expiry at data.expiresIn.

The endpoint is intentionally open (no API key required); the unguessable code in the URL is the secret.

See also

• Build Commands — produce the JSON inputs you'd pass to these analysis verbs

• Tool Commands — fine-grained MCP tool surface for incremental construction

• Deploy Commands — the broadcast side