brama adopt
Review and adopt selected routing aliases from an existing Brama route registry. The command uses the same Brama-owned operation and owner-only route-registry write as Brama Desktop. It reads provider identities only from the acquisition routes already configured for this Brama process and subscription identities only through Brama’s existing Skarbiec/entitlements discovery path. It never reads, prints, copies, or creates a provider credential, and it never enables a paid subscription or calls a model.
Invocation
brama adopt --from <FILE> --agent-id <ID> [--into <FILE>] [--json]
brama adopt --from <FILE> --agent-id <ID> --apply (--select <ALIAS>... | --all-importable) [--replace-conflicts] [--into <FILE>] [--json]| Input | Required/default | Meaning |
|---|---|---|
--from <FILE> | required | A regular, non-symlink UTF-8 Brama inference-routes JSON document, carrying the known top-level fields schema_version, deployments, and routes; an unknown top-level field is refused and the document is rejected whole. A zero-byte or whitespace-only file means an empty registry. A document written before this shape is brought forward with brama routes migrate. |
--into <FILE> | optional | The owner-only destination. The default is BRAMA_INFERENCE_ROUTES_FILE, then ~/.config/brama/inference-routes.json. |
--agent-id <ID> | required | The exact agent whose already-tagged Skarbiec subscriptions are included in the review. There is no built-in agent; without it the command exits 2. |
--apply | off | Permit an atomic destination write. Without it the command is review-only. |
--select <ALIAS> | repeatable | Select one exact source alias. Unknown or duplicate selections reject the request before mutation. |
--all-importable | off | Select aliases whose preview disposition is importable or unchanged, so repeat imports report existing accepted state. Conflicts and rejected routes are never added implicitly. |
--replace-conflicts | off | Allow a selected alias to replace a different destination. A deployment-name conflict is never replaced because an unselected existing alias may depend on it. |
--json | off | Return the same secret-free preview or result as structured JSON. |
Review and selection
The first invocation reports every configured direct-provider acquisition, every discoverable subscription identity for the selected agent, every source alias with the one route behind it, the current destination when that alias already exists, and every deployment the source alias needs. Alias dispositions are importable, unchanged, conflicting, or rejected. An unreferenced deployment is reported and never imported without being selected.
A direct provider/model route is rejected unless Brama already has a configured acquisition route for that provider. A best route is rejected when subscription discovery failed or found no subscription for the selected agent. This is a configuration check only: it does not redeem the credential or spend provider quota.
Duplicates, conflicts, and repeat imports
An identical alias is unchanged. A different route under an existing alias is conflicting and the current route stays unless that exact alias was selected with --replace-conflicts. Repeating an import is therefore idempotent. Existing aliases and deployments not selected by the user are preserved. Duplicate JSON keys, two aliases repeating a destination, duplicate deployment names, unknown fields, unsupported model shapes, and unsafe deployment endpoints reject the complete input before a destination write.
State and results
All accepted selections are merged and validated in memory, then committed with one owner-only atomic replacement. The result reports exact counts and per-alias dispositions: imported, unchanged, conflicting, and rejected. Subsequent requests use the persisted registry because Brama reloads BRAMA_INFERENCE_ROUTES_FILE on route resolution. The source file is retained unchanged; Skarbiec remains the authority for provider and subscription identities.
Failures
- An unreadable, non-UTF-8, symlinked, non-regular, or larger-than-1-MiB source prints
Configuration adoption error: <reason>and exits 1. - Malformed or unsupported JSON, an invalid agent id, an invalid destination registry, or a selection absent from the source rejects before mutation.
--select,--all-importable, and--replace-conflictsrequire--apply.--applyrequires a selection mode.- A Skarbiec discovery failure is visible in the preview and rejects
best; it does not erase direct routes or manufacture an empty subscription result.