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

`check` and `doctor` (covered on the [Utility Commands](/for-developers/cli/utility-commands.md) 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.

```bash
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.

```bash
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[]`.

```bash
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.

```bash
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.

```bash
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](/for-developers/cli/build-commands.md) — produce the JSON inputs you'd pass to these analysis verbs
* [Tool Commands](/for-developers/cli/tool-commands.md) — fine-grained MCP tool surface for incremental construction
* [Deploy Commands](/for-developers/cli/deploy-commands.md) — the broadcast side


---

# 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/analysis-commands.md?ask=<question>
```

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.