brama aliases¶

Report every model alias this gateway declares, the route behind it, and whether the gateway can serve it right now — and, when it cannot, why not.

Invocation¶

brama aliases [--json] [--strict]

What it reads¶

The same two sources the gateway reads at startup: the launcher's alias table in BRAMA_MODEL_ALIASES, when this process was started with it, and the route registry file named by BRAMA_INFERENCE_ROUTES_FILE. When that variable is unset the command reads the launcher's default path, ~/.config/brama/inference-routes.json, so an operator shell sees the file the gateway on this host serves from. The first two lines of text output name both sources, because a shell that has neither is looking at the compiled-in contract alone and must say so. It also reads $BRAMA_STATE_DIR/alias-answers.json (default ~/.brama), where the gateway keeps the newest answer each alias got from what it routes to, rewritten only when that answer changes: a route that is declared and credentialed can still be refused by its provider (an account without credits), and the declaration alone cannot show it. An unreadable record is refused by name. The command contacts no provider and writes nothing; to ask each route now, at one provider request per alias, use brama probe.

Output and state¶

Under an alias the gateway has answered, a third line gives its newest answer and since when: last answer since <time>: answered, or last answer since <time>: refused <code>: <provider sentence>. An alias whose newest answer was a refusal counts as one that cannot be served, in the total and for --strict. JSON output carries the same record as last_answers, keyed by alias, each {"answered","refusal","message","at"}.

One row per alias — the compiled-in contract plus every operator-declared route — with the state word the gateway itself uses, the one route behind the alias, and the reason on a second line when the alias cannot serve. A captured listing:

route registry: ~/.config/brama/inference-routes.json
launcher alias table: absent; only the compiled-in contract and the route registry are visible here
best                             serving              best
ox-alpha                         capability_absent    openrouter/stealth/ox-alpha
                                 alias `ox-alpha` routes to openrouter/stealth/ox-alpha but this gateway holds no provider credential for openrouter; issue the provider capability on this host or point the alias at a route it can reach, such as `best`
weles                            no_route             -
                                 alias `weles` is required by this gateway but no route is declared for it; declare one with `PUT /v1/admin/routes` or in the launcher's model_aliases policy
wisent-backend      serving              local-openai/chat-primary
9 alias(es), 4 cannot be served
subscription pool: 0 of 15 credential(s) are live, which is what the 1 selector alias(es) above resolve through
every request for a selector alias is refused with subscription_reauthorization_required until one account is signed in. The gateway's renewal sweep signs accounts in through Weles on its own; `brama subscription list` names what blocks each member under sign_in_blocked, and a Google prompt the sign-in raises is approved on the account owner's phone.

States are serving, no_route, capability_absent, capability_check_failed and routes_file_invalid; their meaning and repair are in the alias concept. capability_check_failed retains the credential authority's operation and cause, including a failed route resolve; it does not mean no credential was configured. best is a subscription selector, not a route, so it is reported serving with no route table entry and carries subscription_resolved in JSON. serving for a selector means the selector is declared, which is not the same as a credential existing, so the pool's own live count is printed after the table and, when nothing is live, the sentence every request for that selector is refused with: without those two lines, best serving best reads as a healthy gateway while every request answers 503 subscription_reauthorization_required. JSON output carries source, aliases, unserviceable and subscription_pool with live, members and selectors; the same table for a running gateway is GET /v1/aliases, whose rows are alias, state, route, reason, required and authorized.

Refusals¶

aliases could not be read: <reason>, exit 1, when the alias table or the route registry file cannot be parsed; the reason is the parser's own sentence. With --strict the command exits 1 after printing when unserviceable is above zero or when a declared selector's pool holds no live credential. Clap refuses unsupported options before anything is read.

See aliases or the CLI tree.