`brama decide`¶

Ask one typed decision from a shell: a state and a set of typed questions in, one typed answer each out. It resolves the alias through the same route registry the gateway reads and dispatches through the same engines POST /v1/decisions uses, so what it prints is what a caller would have received.

Invocation¶

brama decide --state <STATE> --questions <QUESTIONS> --agent-id <ID> [--model <ALIAS>] [--json] --allow-provider-cost

Input	Required/default	Meaning
`--state <STATE>`	required	The state to decide on. A literal string, `@FILE` to read a file, or `-` to read standard input.
`--questions <QUESTIONS>`	required	The questions object, exactly as the endpoint takes it. A literal JSON string, `@FILE`, or `-`.
`--model <ALIAS>`	optional; `decision-model`	Which decision alias answers. Only `decision-model` and `best-decision-model` are accepted.
`--agent-id <ID>`	required	Whose subscription pays when the alias resolves to `best`. There is no built-in agent; without it the command exits 2.
`--json`	optional; off	Print the answer document instead of human-readable lines.
`--allow-provider-cost`	required to send anything	Acknowledge that this performs a billable provider request.

Why it exists¶

Two moments the HTTP surface cannot cover. Before a gateway runs, an operator has to know whether the route behind a decision alias answers at all; and while diagnosing one that stopped, the question is which of the alias, the route or the model broke. This command answers both against the real route, and its refusals are the endpoint's own sentences.

What it reads and writes¶

It reads the route registry — BRAMA_INFERENCE_ROUTES_FILE, else ~/.config/brama/inference-routes.json — and the launcher's alias table when the shell carries one, exactly as brama aliases does. It writes nothing. The provider credential is redeemed at final use through Skarbiec, the same cascade the gateway uses.

Output and state¶

One real run, against decision-model routed to openrouter/openai/gpt-4o-mini:

$ brama decide --model decision-model --agent-id <ID> --allow-provider-cost \
    --state "Help! My payouts have been failing for 3 days." \
    --questions @questions.json
Model: decision-model
Route: openrouter/openai/gpt-4o-mini (chat-distribution)
department               choice billing  confidence 0.70  [billing=0.70 sales=0.10 technical=0.20]
is_urgent                noul 1.0000  confidence 1.00
severity                 score 2.1000  confidence 0.50  [0=0.00 1=0.20 2=0.50 3=0.30]
Tokens: 247 in / 106 out
Latency: 2514ms

With --json the answer is the endpoint's own document: model, route, engine, answers and usage. Exit code is 0 when every question was answered inside the schema the caller declared.

Refusals¶

Sentence	Meaning
`refusing a billable decision without explicit --allow-provider-cost`	Nothing was sent. Nothing is spent by running this command by accident.
--model must be `decision-model` or `best-decision-model`	Only the two decision aliases reach this shape.
`--questions is not JSON: <reason>`	The questions argument, file or standard input did not parse.
the question's own refusal, such as question `mood` declares unsupported type `vibe`: a question is a noul, a choice or a score	The same validation the endpoint performs, before any provider is contacted.
alias `decision-model` is a decision alias this gateway knows but no route is declared for it; declare one with `brama routes set decision-model <provider/model>` or `PUT /v1/admin/routes`	The alias has no route here.
`provider refused: <the provider's own sentence>`	The route was reached and refused — no credits, a rate limit, an unavailable credential.
`decision_contract_violated: <route> answered outside the declared schema: <what was wrong>`, then `reply from <route>: <the reply as written>`	The model answered outside the declared schema. `<route>` is the route that answered — for `best-decision-model`, the subscription model it selected — and the second line is its reply, so the fault can be read without reproducing it. The repair is the route, not the request.

Every refusal prints on standard error. A missing --allow-provider-cost or --agent-id, a --model outside the two decision aliases, and --questions that do not parse are usage errors and exit 2; every other refusal exits 1.