CLI¶

The brama binary is the gateway, its local diagnostics, and its operator repair surface. Billable commands require explicit cost acknowledgement, credential mutations require an audit reason, and no command prints credential material. This tree follows the public dispatcher in Brama 0.2.41.

Root invocation¶

brama <COMMAND>

A top-level command is required. Use brama --help or brama help [COMMAND]... to print the same tree from the installed build.

Complete command tree¶

• brama version — print secret-free product and build identity as JSON.
• brama serve — start the OpenAI-compatible HTTP server.
• brama onboard — run the first-use journey and optionally receive one real model response.
• brama adopt --from <FILE> … — review and atomically adopt selected aliases from an existing Brama route registry.
• brama test — run one acknowledged test inference through the agent subscription path.
• brama decide --state <STATE> --questions <QUESTIONS> --agent-id <ID> [--model <ALIAS>] [--json] --allow-provider-cost — ask one acknowledged typed decision through decision-model or best-decision-model and print the typed answers.
• brama review --gateway <URL> --model <ALIAS> --instructions <FILE> --request <FILE> --root <DIR> --max-turns <N> [--output <FILE>] [--json] < bearer — review one change through a gateway with read and search tools confined to one directory; the bearer comes on standard input and the model's typed verdict is the exit status (0 approve, 3 request changes, 1 no review).
• brama detect — detect local hardware and print a model recommendation.
• brama mcp — serve the read-only stdio MCP hardware-detection surface.
• brama aliases [--json] [--strict] — report every declared model alias, the route behind it, and whether this gateway can serve it; --strict exits non-zero when any cannot.
• brama models [--kind <KIND>] [--weights <WEIGHTS>] [--category <NAME>] [--provider <ID>] [--search <TEXT>] [--limit <N>] [--json] — list every model this gateway can name with what it produces, whether its weights are published, and which declared categories it carries.
• brama categories ls|set|rm — read, declare and retire the model categories this deployment groups its catalogue by, such as uncensored.
• brama image --prompt <TEXT> [--model <ALIAS|ROUTE>] [--size <SIZE>] [--n <COUNT>] [--output <FILE>] --allow-provider-cost — render one acknowledged image and write the bytes it returns.
• brama video start|status — start one acknowledged video job and read it back from the provider that issued it.
• brama speak --input <TEXT> --voice <VOICE> --output <FILE> [--json] --allow-provider-cost — speak one acknowledged text through a voice route and write the audio the provider encoded.
• brama music --model <ROUTE> --lyrics <TEXT> --output <FILE> [--json] --allow-provider-cost — compose one acknowledged song through a music route and write the audio the provider encoded.
• brama voices list|clone|remove — list the voices a voice route's account can speak with, clone one from recordings, or delete one with --confirm.
• brama probe --bearer-role <ROLE#FIELD> [--agent <AGENT> --signing-role <ROLE#FIELD>] [--alias <ALIAS>]... [--json] --allow-provider-cost — on the gateway's own host, send one real completion per declared alias through the running gateway and report each answer or refusal; exits 1 when any alias was not served.
• brama diagnose [--json] — on the gateway's own host, explain why it is or is not serving from every file the launcher reads: units, installed generations, service env, policy grants, alias routes, reachability, why the release stopped serving (the release agent's quarantine causes and their repair) and the current boot attempt. Read-only; it contacts no provider.
• brama workload <COMMAND> — this installation's workload key and the vault grants bound to it.
  • brama workload register [--json] — grant each agent the installation's registry.json names exactly the vault coordinates capability-routes.json maps, bound to the workload's public key. The launcher runs it on every start.
  • brama workload deregister [--json] — the inverse: revoke the vault grant of every agent the same registry names; a rerun is harmless.
  • brama workload check <REGISTRY> --binary <BINARY> [--json] — exit 0 when the registry pins exactly this process's uid, gid and the binary's resolved path and SHA-256; otherwise exit 1 naming the first mismatch.
• brama maintain (--gateway <URL> | --gateway-consumer <CONSUMER>) [--bearer-role <ROLE>] [--json] — ask the serving gateway for one maintenance pass: aged plan usage reads, grant renewal and a fresh readiness reading; exits 1 when any step failed.
• brama routes <COMMAND> — act on this gateway's inference-route registry.
  • brama routes set <ALIAS> <DESTINATION> [--file <FILE> | --gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — declare where one alias points, validated against the shape that alias promises and committed with the same atomic owner-only replacement PUT /v1/admin/routes performs; with a gateway named, the serving gateway takes the change through that route.
  • brama routes rm <ALIAS> [--file <FILE> | --gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — remove one alias from the registry through the same write, here or on the gateway named.
  • brama routes migrate [--file <FILE>] [--json] — rewrite the route registry into the current document shape: keep the known top-level fields, validate, and commit with the same atomic owner-only replacement every other registry write uses. Idempotent.
• brama subscription <COMMAND> — read the subscription pool or act on one provider's subscription credentials.
  • brama subscription list [--json] [--refresh-usage] — report the subscription pool this gateway routes over: every subscription, its state, its usage window and its failure, optionally reading current free provider reports.
  • brama subscription refresh <PROVIDER> --reason <REASON> [--json] — refresh one provider's OAuth grants now.
  • brama subscription login <PROVIDER> --by weles|hand --reason <REASON> [--subscription-id <ID>] [--login-item <LOGIN_ITEM>] [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — sign one account in and prove it: --by weles drives one exact Weles row and proves it with a refresh; --by hand signs it in through your own browser and a code pasted on stdin and proves it with one completion, here or on the serving gateway.
  • brama subscription disown --subscription-id <ID> --reason <REASON> [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] — give one pool member back; the gateway retires it and forgets its credential.
  • brama subscription reinstate --subscription-id <ID> --reason <REASON> [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — the inverse of disown: put one retired member back in the rotation.
  • brama subscription forget --subscription-id <ID> --reason <REASON> [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — drop one member the pool only remembers (the usage history lists it, the vault does not); the reason is journaled and the member leaves the pool report (Brama Desktop: Forget this member in a member's Membership section).
  • brama subscription attribute <PROVIDER> [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — record which account each pool member of one provider belongs to, read from the member's own grant, in the vault of the gateway named (Brama Desktop: Record accounts on the Subscription Pool screen).
  • brama subscription acquire <PROVIDER> --reason <REASON> [--gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json] — buy one new account of a provider providers.json declares when no pool account can serve (each has spent its plan or cannot be used) or every usable one carries the operator's limit of sessions, and the pool holds fewer accounts than the operator allows; every brama maintain pass does the same by itself (Brama Desktop: Buy a <provider> account now).
  • brama subscription handover <PROVIDER> --harness omp [--json] — sign every pool account omp on this machine lacks into omp through its own login for the provider name the declaration gives it, completed by Weles (Brama Desktop: Sign <provider> accounts into omp).
  • brama subscription lease take <PROVIDER> --session-id <ID> --holder <PROGRAM> (--gateway <ORIGIN> | --gateway-consumer <NAME>) [--bearer-role <ROLE>] [--json] — record which subscription one session runs on, choosing the usable member carrying the fewest sessions up to the operator's limit; a full pool is refused and an acquisition started for it.
  • brama subscription lease release (--lease-id <ID> | --session-id <ID>) (--gateway <ORIGIN> | --gateway-consumer <NAME>) [--bearer-role <ROLE>] [--json] — end one lease, or every live lease of one session.
  • brama subscription lease list (--gateway <ORIGIN> | --gateway-consumer <NAME>) [--bearer-role <ROLE>] [--json] — every live lease and how many sessions each subscription carries.
  • brama subscription authenticator list [--provider <PROVIDER>] [--json] — list which accounts need a second factor and which hold the secret that answers one.
  • brama subscription authenticator enrol <PROVIDER> --subscription-id <ID> --reason <REASON> [--login-item <LOGIN_ITEM>] [--json] — enrol an authenticator for the login behind one subscription, so later sign-ins answer the second factor by themselves.
• brama tasks measure <KEY> --agent-id <ID> --prompt <TEXT> --max-models <N> [--expected-exact <TEXT>] [--expected-contains <TEXT>] [--persist] --allow-provider-cost, brama tasks show <KEY> --agent-id <ID>, brama tasks list --agent-id <ID> — measure a named task and read back the checks task:<KEY> selection uses.
• brama help [COMMAND]... — print root or command-specific help.

Safety boundaries¶

version, detect, subscription list without --refresh-usage or --apply, and help are read-only. --refresh-usage reads the plan-usage capability, which reads provider reports and persists their outcome through Brama's normal credential handling; it starts neither a sign-in nor model inference. mcp exposes local detection only. adopt is review-only unless --apply is combined with an exact selection; it never reads credential material or calls a provider. routes migrate reads and rewrites one registry file and contacts no provider. test, probe, the provider-requesting part of onboard, and tasks measure require --allow-provider-cost. subscription refresh and subscription login require --reason and journal their verdicts. Each linked command page states its exact inputs, output and state effect, and relevant refusal text.