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.

The CLI signs every request with a per-key ES256 JWT (P-256 ECDSA). You generate a keypair locally, register the public half with Bron through the UI (or via bron auth register-key if you already have an authenticated profile), and keep the private half on disk. The CLI never sees your password and never round-trips the private key over the network.

​
Generate a keypair

bron auth keygen --file ~/.config/bron/keys/me.jwk
What this does:
  • Generates a fresh P-256 ECDSA keypair locally using crypto/ecdh.
  • Writes the private JWK to the file at mode 0600 (only your user can read it). The file contains kty, crv, x, y, d, kid — the kid is the random key identifier used to look up the matching public key on the server.
  • Prints the public JWK (no d field) to stdout. This is what you register in the Bron UI.
{
  "kty": "EC",
  "crv": "P-256",
  "kid": "f3c2…",
  "x": "qO0e…",
  "y": "8j8x…"
}
Paste that public JWK into Settings → API keys in the Bron UI. Bron stores the public key indexed by kid; when the CLI signs a request the server looks up the matching public key and verifies the signature. The private key never leaves your machine. If you lose it, generate a new keypair and revoke the old kid in the UI.

​
Profiles

A profile binds a key file, workspace, and base URL together so you don’t repeat them on every call. Configs live in ~/.config/bron/config.yaml (override with BRON_CONFIG). 
# Set up the default profile.
bron config init --name default \
  --workspace <workspaceId> \
  --key-file ~/.config/bron/keys/me.jwk

# Add a second profile (e.g. for a different workspace).
bron config init --name staging \
  --workspace <stagingWorkspaceId> \
  --key-file ~/.config/bron/keys/staging.jwk \
  --base-url https://api.qa.bron.org   # optional; default is production

# Switch the active profile.
bron config use-profile staging

# Modify keys without re-running init.
bron config set workspace=<otherWorkspaceId> proxy=http://proxy:8080

# Inspect.
bron config           # human format, current profile annotated
bron config --output json

​
Per-call overrides

Every flag a profile sets has a CLI override: 
bron --profile staging tx list
bron --workspace <workspaceId> tx list
bron --key-file ~/.config/bron/keys/other.jwk tx list
bron --proxy http://proxy:8080 tx list

​
Env-var overrides

Useful for CI / containers / one-off scripts: 
BRON_PROFILE=staging                            bron tx list
BRON_WORKSPACE_ID=<workspaceId>                 bron tx list
BRON_API_KEY_FILE=~/.config/bron/keys/other.jwk bron tx list
BRON_PROXY=http://user:pass@proxy:8080          bron tx list
HTTPS_PROXY=http://proxy:8080                   bron tx list  # standard env vars are honored too
BRON_CONFIG=/tmp/cli.yaml                       bron config show
Precedence (highest first): explicit flag → env var → active profile → built-in default.

​
Proxy

Outbound from the CLI honors:
  • BRON_PROXY env var
  • standard HTTPS_PROXY / HTTP_PROXY env vars
  • proxy field set on the active profile (bron config set proxy=...)
If you sit behind a proxy that requires auth, embed the credentials: http://user:pass@host:8080. The same proxy is used for both REST and WebSocket transports (the bron tx subscribe socket goes through it too).

​
Key rotation

  1. Generate a new keypair: bron auth keygen --file ~/.config/bron/keys/me-new.jwk
  2. Register the new public JWK in Settings → API keys.
  3. Update the active profile to use the new key: bron config set key_file=~/.config/bron/keys/me-new.jwk
  4. Verify with a no-op call: bron workspace info
  5. Revoke the old kid in the UI.
You can have multiple active keys at once — the server matches by kid, so old and new keys coexist during a rotation window.

​
Permissions

API keys inherit the permissions of the workspace member they belong to. If the user can approve transactions in the UI, the CLI can too — there’s no separate “API mode” with reduced privileges. Reduce scope by creating a member with limited permissions and registering the key under that member’s account.

​
Troubleshooting

SymptomLikely cause
403 Forbidden on every callPublic key not registered, or the kid was revoked
401 Unauthorized immediately after rotationOld kid still in active profile — bron config show to inspect
dial: x509: certificate signed by unknown authorityCorporate proxy MITM — set HTTPS_PROXY or import the CA
403 on some endpoints, 200 on othersMember’s role doesn’t grant the action — check workspace permissions
If a request fails with a 4xx / 5xx, the CLI prints the API error envelope plus a trace: line containing the correlation ID. Quote that ID when reporting issues — it lets us pull the exact ES log line for your call.