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#

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 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#

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.

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#

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