`brama routes set`¶

Declare where one alias points. The destination is validated against what that alias promises and committed to the route registry through the same staging file, validation and rename PUT /v1/admin/routes performs, so the running gateway serves it on the next request without a restart.

Invocation¶

brama routes set <ALIAS> <DESTINATION> [--file <FILE> | --gateway <ORIGIN> | --gateway-consumer <NAME>] [--bearer-role <ROLE>] [--json]

Input	Required/default	Meaning
`<ALIAS>`	required	The name a caller asks for, such as `decision-model`. Lowercase letters, digits, `-`, `_`, `.` and `/`.
`<DESTINATION>`	required	A canonical `provider/model` route, a deployment name from the registry, or `best` to delegate to subscription dispatch.
`--file <FILE>`	optional; `BRAMA_INFERENCE_ROUTES_FILE`, then `~/.config/brama/inference-routes.json`	The registry to write. The same destination the service, `brama adopt` and `PUT /v1/admin/routes` use.
`--gateway-consumer <NAME>`	optional; not with `--file`	Send the change to the gateway that serves the aliases, found through Stado’s service directory as this consumer. It goes through `PUT /v1/admin/routes`, so the serving process validates the route against what it can serve and writes its own registry. Use it from any machine other than the gateway’s host: a local write there lands in a file no serving process reads.
`--gateway <ORIGIN>`	optional; not with `--file` or `--gateway-consumer`	The same, with the gateway’s origin named directly.
`--bearer-role <ROLE>`	optional with a gateway	The vault role whose item’s `token` field is the console’s bearer; without it the bearer is read from stdin.
`--json`	optional; off	Print one object instead of human-readable lines.

Why it exists¶

A route change used to require a running gateway and a console bearer, which is exactly what an operator does not have when the gateway will not serve — an alias with no route, a destination that has to move, a host being provisioned. Editing the JSON by hand is the alternative this replaces: the file is owner-only, validated whole, and replaced atomically, and none of that is true of a text editor.

What it validates¶

The alias name, and the shape the alias promises: wisent-backend/embeddings takes an embedding route and nothing else, wisent-backend/moderation a moderation route, a decision alias a route that can answer typed questions, and every other name a chat route. decision-model refuses best, because delegation is what best-decision-model is for.

What it does not check is whether this host holds the provider credential. An operator shell holds none, and refusing the write for a credential this process cannot see would make the registry unwritable from the one place a gateway that is not running can be repaired. Whether the route can be served is what brama aliases reports afterwards.

Output and state¶

$ brama routes set decision-model openrouter/openai/gpt-4o-mini
registry: ~/.config/brama/inference-routes.json
change: decision-model -> openrouter/openai/gpt-4o-mini
best-decision-model              best
decision-model                   openrouter/openai/gpt-4o-mini

The report names the registry, the change it committed, how many routes the document now holds, and one line per alias with the single destination behind it. With --json the answer is {"registry", "change", "document"}, whose document is the registry as it now stands on disk. With a gateway named the report starts with gateway: <origin> and lists the routes the gateway answered; --json gives {"gateway", "change", "routes"}. Exit code is 0 on success.

Refusals¶

Sentence	Meaning
route alias `<alias>` is invalid: an alias is lowercase letters, digits, `-`, `_`, `.` and `/`	The name is not one a caller could present.
alias `decision-model` cannot carry `best`: it is not a shape this alias promises	The destination cannot keep the promise the alias name makes.
`route update error: <reason>`	The registry could not be read or replaced: the file's own sentence about ownership, mode, a symlink, a repeated destination, or a deployment with no safe endpoint. The file is left as it was.
`the gateway refused to point <alias> at <destination>: <status>: <its whole answer>`	The serving gateway refused the change: `invalid route alias`, `route is unsupported or unavailable` (it cannot serve that destination), `runtime route registry is not configured`, or a bearer that is not the console’s.
`the gateway at <url> did not answer: <cause>` / `…is not JSON…`	The gateway could not be reached or answered something else.
`--bearer-role is for a gateway; name one`	A bearer role was given without `--gateway` or `--gateway-consumer`.

Every refusal exits 1 and prints on standard error.