brama onboard¶
Run Brama’s first-use journey, optionally adopt reviewed routes the user already has, and, only with explicit cost acknowledgement, request one real model response.
Invocation¶
brama onboard (-m <ROUTE>|--model <ROUTE>) --agent-id <ID> [--allow-provider-cost] [--reset]
[--adopt-from <FILE> [--adopt-into <FILE>]
[--adopt-apply (--adopt-select <ALIAS>... | --adopt-all-importable)
[--adopt-replace-conflicts]]]| Input | Required/default | Meaning |
|---|---|---|
-m, --model <ROUTE> | required | Canonical provider/model route for the first real response. There is no built-in route; without it the command exits 2. |
--agent-id <ID> | required | Workload whose separately provisioned provider credentials and tagged Skarbiec subscriptions are reviewed or used. There is no built-in workload; without it the command exits 2. |
--allow-provider-cost | optional; off | Acknowledge one billable provider request. Adoption never uses this acknowledgement and never makes an inference. |
--reset | optional; off | Discard recorded walkthrough progress and replay first use. |
--adopt-from <FILE> | optional | Review a regular, non-symlink, at-most-1-MiB schema-1 Brama inference-routes JSON file before continuing the journey. Without --adopt-apply, the command prints the review and stops. |
--adopt-into <FILE> | optional | Owner-only destination; defaults to BRAMA_INFERENCE_ROUTES_FILE, then ~/.config/brama/inference-routes.json. |
--adopt-select <ALIAS> | repeatable | Select exact aliases from the reviewed source. |
--adopt-all-importable | optional; off | Select aliases classified as importable or already unchanged. Conflicts and rejected aliases are excluded. |
--adopt-apply | optional; off | Atomically persist the selected aliases through the same operation as brama adopt and Brama Desktop. |
--adopt-replace-conflicts | optional; off | Replace a reviewed alias conflict. Deployment-name conflicts remain non-replaceable. |
Output and state¶
An adoption review reports configured acquisition identities, discoverable subscription identities, every reviewed alias with the one route behind it, and importable, unchanged, conflicting, or rejected disposition. Applying reports exact imported, unchanged, conflicting, and rejected counts, preserves unselected state, and writes once only after whole-document validation. It never copies credential material; Skarbiec and the existing standalone provider store retain ownership. A source registry written before the current document shape is brought forward with brama routes migrate.
The walkthrough then prints its remaining journey steps. Without cost acknowledgement it sends no provider request, exits 0, and persists in-progress state at ~/.local/state/brama/onboarding.json. With acknowledgement it prints the selected model, response, and token counts; neither a review nor a persisted route marks onboarding complete. Only a successful real response records completion.
Refusals¶
A missing --model or --agent-id is refused by the argument parser with exit 2. Adoption options without --adopt-from print Configuration adoption error: --adopt-from is required for every adoption option and exit 2. A write option without --adopt-apply, an apply without a selection mode, invalid source data, unknown or duplicate selections, and invalid destination state print Configuration adoption error: <reason> and exit 1 before the onboarding journey advances.
Without cost acknowledgement the terminal guidance explains that no provider request was sent and onboarding remains in progress. A failed model call prints Model request failed: <reason> and Onboarding remains in progress because no model response was received.; with cost acknowledged the command exits 1. Journey failures print Onboarding error: <error> and exit 1.