Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.bron.org/llms.txt

Use this file to discover all available pages before exploring further.

bron is built to be driven by an LLM agent (Claude Code, Codex, Cursor, custom tooling) without any wrapping layer. This page captures the contract: what an agent can rely on, what surfaces it should query first, and how to keep it from doing damage.

​
Discovery in one call

The agent doesn’t need to memorise the API. --schema emits the complete CLI surface as one OpenAPI 3.1 JSON document: 
bron --schema                          # full CLI: every command, every flag, every type
bron <resource> <verb> --schema        # single-command fragment
bron --output yaml <r> <v> --schema    # same dump in YAML
What’s in there:
  • Every command path (accounts list, tx withdrawal, tx subscribe, …)
  • Every flag, with its type, enum values, defaults, and short description
  • Every request body shape, by transactionType discriminator for tx create
  • Every response shape, indexed by HTTP status code
  • The --embed tokens each list endpoint accepts, with the resulting _embedded shape
For an agent that just spawned, bron --schema | head -200 is enough orientation to start composing valid commands. 
1. user: "approve every signing-required withdrawal under $1k"
   ↓
2. agent: bron tx --help               # → see verbs (list, get, approve, ...)
   agent: bron tx list --help          # → see filters
   ↓
3. agent: bron tx list \
            --transactionStatuses signing-required \
            --transactionTypes withdrawal \
            --output jsonl
   → JSONL: agent parses, picks the ones with params.amount < 1000
   ↓
4. agent: bron tx approve <tx>         # for each match
   → exit 0 = success, exit ≠ 0 = stop and report to user
Three loops covers most workflows: discover → query → act. --schema for static introspection, --help for human prose where helpful, --output jsonl for machine consumption.

​
Stable contracts

These won’t break across 0.x releases:
SurfaceContract
Exit codes0 success; 1 other; 3 401/403; 4 404; 5 400; 6 409; 7 429; 8 5xx
Error envelope on stderrError: <message> line + code: / trace: / details: lines
--schema document shapeStrict OpenAPI 3.1 fragment; field paths + types
Flag/verb namestx, tx list, tx withdrawal, --output, --columns, etc.
Date renderingISO 8601 UTC in every output format
Numeric stringsDecimals stay strings (no float64 coercion)
--help text wording, color, and table layout are NOT part of the stable surface. Don’t grep --help output in agent code; use --schema.

​
Idempotency

Every tx <type> and tx create call accepts --externalId <key>. Bron de-duplicates by (workspace, externalId): retrying a call with the same key returns the existing transaction, not a duplicate. For an agent, this is critical — LLMs retry on perceived failure, and without an idempotency key a retry would create a second withdrawal: 
# DON'T — agent retries this on a hiccup → double-spend
bron tx withdrawal --accountId acc --params.amount=100 ...

# DO — agent retries this on a hiccup → same tx, no double-spend
bron tx withdrawal --externalId "agent-task-7f3a" --accountId acc --params.amount=100 ...
Generate --externalId from a stable identifier of the agent’s task (task ID, request ID, hash of the prompt + timestamp) — anything that would be the same on retry.

​
Dry-runs before real submits

bron tx dry-run validates a transaction body against the API without submitting it: returns the expected fees, blockchain ETA, validation errors: 
bron tx dry-run --transactionType withdrawal --file /tmp/tx.json --output json
For an agent acting on behalf of a human, a dry-run + summary + explicit confirmation step is the standard pattern. Same body schema as the live call, so the agent can reuse the same JSON.

​
Output for agents

The default JSON is fine. JSONL is often easier to parse line-by-line in a streaming agent: 
bron tx list --output jsonl
For really long lists, project just the fields the agent needs: 
bron tx list \
  --transactionStatuses signing-required \
  --output jsonl \
  --columns transactionId,transactionType,params.amount,params.assetId,createdAt
Less to parse, less context spent.

​
Agent-friendly help topic

bron help agents
Prints a concise, machine-readable orientation guide: the commands you’ll need most, the schema entry point, the idempotency contract, the exit-code map. Reference it from agent system prompts so a fresh agent can self-orient in one call.

​
Future: dedicated skills repo

We’re publishing a separate repository (BRO-493) with packaged “skills” / plugin manifests for popular coding agents (Claude Code SKILL.md, Codex prompts, Cursor rules). It bundles:
  • A canonical agent system prompt for Bron CLI usage
  • Pre-built flow templates (treasury rebalance, payout approval, audit export)
  • Example failure modes + recovery patterns
  • Test harness for verifying agent integrations
Until then, the schema + this page + a few in-context examples are enough for a capable agent to drive the CLI safely.

​
Safety guardrails to write into your agent prompt

Suggested constraints for a Bron-driving agent — copy into your system prompt and tune:
  • Always pass --externalId on any tx <type> or tx create call. Generate it from a stable task identifier.
  • Never pipe credentials anywhere except the local profile config. Don’t log JWK contents.
  • Confirm before approve / decline / cancel / sign — these are state-changing, often irreversible. Show the human the affected transactions and wait for explicit OK.
  • Use tx dry-run before any first-time withdrawal pattern, to surface fees and validation errors.
  • Bound query windows — --createdAtFrom / --createdAtTo on list queries to avoid pulling thousands of records into context.
  • Treat exit codes as truth — bron tx approve $tx || stop_and_report instead of grepping success messages.