# CLI Automation for Agents

Use the CLI to discover, build, inspect, and hand transactions to a signer. A language model should not reconstruct approval JSON from memory when a standard builder already expresses the requested terms.

## Discover the Installed Surface

```bash
bb --help-json > commands.json
bb build payment-request-v2 --help
bb pay-requests pay --help
bb dev tools list --names
bb dev skills payment-obligations
```

The npm SDK CLI is also available as `bitbadges-cli`. If an older chain binary does not forward a verb, invoke `bitbadges-cli` directly. Record the installed package version alongside automation runs; new example/schema commands and the versioned browser handoff require matching SDK and frontend releases.

Use [Choose a Standard](https://docs.bitbadges.io/standards) for intent selection. Use command help for flags, tool schemas for input structure, and standard documentation for lifecycle semantics. The MCP structural schema does not encode every runtime refinement; successful schema inspection is not successful validation.

## Generate Editable Payment Terms

```bash
bb build payment-request-v2 --list-examples
bb build payment-request-v2 --schema
bb build payment-request-v2 --example threshold | jq '.data' > terms.json
```

Available examples are `specific`, `anyone`, `one`, `all`, `threshold`, `installments`, `partial`, `target`, and `link`. Finite examples use dates relative to generation time. They contain sample addresses and amounts; replace them with the user's actual terms and verify the resulting dates before publishing.

```bash
bb build payment-request-v2 --json terms.json --output-file proposal.json
bb pay-requests build-v2 --json terms.json --output-file proposal-alias.json
```

Both commands use the same builder. Arbitrary valid custom obligations remain supported through `--json`. Discovery commands emit parameters or schemas and cannot be combined with signing, simulation, or build inputs. They do not publish collections.

## Metadata Precedence

JSON metadata is used by default. Explicit `--uri` selects URI metadata and replaces inline JSON metadata. Any explicit `--name`, `--image`, or `--description` selects inline metadata, clears a JSON URI, and keeps compatible unspecified inline JSON fields. The completed inline triple is required. Combining a URI flag with inline metadata flags is rejected.

This V2 behavior is explicit; do not assume every legacy builder uses the same flag precedence. Read the installed help and validate the generated proposal.

## Separate Input and Output Shapes

| File or response | Meaning |
| --- | --- |
| Example envelope `.data` | Editable builder parameters |
| `terms.json` | Parameters supplied to `--json` |
| Build envelope `.data` | Generated message or message wrapper |
| Build envelope `.meta` | Validation/review/simulation reports when present |
| Browser result | A signing/submission report; not independent chain confirmation |
| Chain transaction result | Execution success/failure on the selected network |
| Indexed standard status | A projection that may lag confirmed execution |

Check both the process exit status and envelope `ok`. Preserve stderr diagnostics. Do not feed an error envelope into the next command, parse human prose as JSON, or strip the message wrapper from a multi-message transaction. `bb deploy` accepts the documented build envelope; `jq '.data'` is specifically useful when turning an example envelope into parameter input.

Use `--output-file` for artifacts you need to review. A quiet flag changes commentary, not economic behavior. Read flags such as `--browser`, `--burner`, and keyring `--exec` as side-effect switches.

## Exact Amounts, Addresses, and Times

V2 terms use positive base-unit integer strings. CLI amount flags on other commands may resolve symbols into display units; raw denominations can use different rules. Never infer the conversion from a ticker alone. Record the network and canonical denomination, then review both the base amount and human display amount.

Partial-payment `--units` counts quanta and scales all payout legs. It is not the number of people or the amount of a coin. Keep different denominations separate. Convert EVM addresses to the required canonical form through the existing address helpers; never create a new address mapping in a shell script.

V2 payment windows use inclusive Unix millisecond endpoints. Subscription intervals are fixed durations with separate renewal consent. Local time labels are display only; chain execution uses chain time.

## Human Review and Retry

Use [Main-Wallet Payment Requests](https://docs.bitbadges.io/agents/main-wallet-payments) to ask for exact human approval. After a hash is returned, query `bb tx status` or wait with `bb tx wait` on the same network. Treat a timeout, closed browser, or lost callback as uncertain until reconciled.

Retry read-only queries with bounded backoff. Retry a payment only after establishing what happened to the prior attempt and obtaining authorization for any changed terms. A reusable link can accept duplicate valid payments. Subscription renewal consent can authorize future charges; an invoice payment does not.

## Fetch Only the Documentation You Need

The docs provide [llms.txt and Markdown pages](https://docs.bitbadges.io/agents/reading-the-docs). Start with the standards index and this CLI page, then load the specific standard, action reference, and underlying approval criterion involved. Use the complete corpus when an offline snapshot is needed; avoid repeatedly downloading generated SDK references for ordinary CLI actions.