BBramaDocs
Browse documentation

Brama CLI command reference

brama subscription authenticator enrol

Ask Weles to add an authenticator to the Google login behind one subscription, without replacing an existing authenticator. Confirm both the worker's completed setup and Skarbiec's usable seed.

Why it exists

A sign-in cannot invent a missing authenticator seed: Google reveals a setup key only inside an authenticated account session. Enrolment signs in with the resolved login, uses an offered phone approval when needed, opens authenticator setup, confirms its first code and writes the seed to that login item only after setup is observed as complete. A stored seed answers later authenticator challenges; Google can still require another method or phone approval. Normal sign-in can use an offered phone approval without enrolling an authenticator.

Invocation

brama subscription authenticator enrol <PROVIDER> --subscription-id <ID> --reason <REASON> [--login-item <LOGIN_ITEM>] [--json]
InputRequired/defaultMeaning
<PROVIDER>requiredOne of codex, claude-code, or kimi.
--subscription-id <ID>requiredThe Brama subscription whose login gains the authenticator. Weles resolves which vault row that is, exactly as it does for a sign-in.
--reason <REASON>requiredWhy this enrolment is being run; recorded beside the verdict.
--login-item <LOGIN_ITEM>optionalAn exact Skarbiec login reference, for a subscription whose identity names more than one.
--jsonoptional; offPrint the verdict as JSON instead of labeled lines.

Output and state

Brama resolves the account through POST /reauth/resolve, then sends its account_revision to POST /reauth/enrol-authenticator using the scoped brama-weles-reauth bearer. A changed revision is refused before a browser opens. Concurrent requests for the same account and login join the same live enrolment; a conflicting login is refused. Brama accepts the result only when the subscription, login, account revision, worker revision and run id match, and totp seed independently reports a usable seed. This read exposes metadata, never the seed.

The JSON verdict includes confirmed and seed_present. Both must be true for enrolled; an old seed or an unconfirmed worker response alone cannot prove a successful enrolment. not_enrolled exits 1. A failed seed inspection names the operation and its error rather than claiming that the field is absent.

brama subscription authenticator enrol codex --subscription-id <TEST_SUBSCRIPTION> --login-item <TEST_LOGIN> --reason "Enable authenticator sign-in for the isolated test account" --json

Exact refusals

  • A provider with no Weles sign-in: provider `<provider>` has no Weles sign-in, so it has no authenticator to enrol.
  • A login that signs in with a password: authenticator_enrolment_unsupported_login_method, naming the login and its method — there is no authenticator on it to enrol.
  • Missing admission credential: when BRAMA_WELES_REAUTH_TOKEN is unset, Brama reads the item playing role brama-weles-reauth; no such item is refused with no vault item carries stado:role:brama-weles-reauth, and two with the number of items that carry it.
  • A worker that does not serve the route answers HTTP 404, which is what a deployment older than this release reports.
  • Trajectory refusals retain their names, including google_push_not_approved, setup_key_not_shown, setup_code_rejected and seed_persist_unconfirmed. Weles does not write a seed when Google setup confirmation is unobserved (setup_confirmation_unobserved).
  • An existing authenticator is not rotated automatically: authenticator_replacement_requires_consent. A conflicting live enrolment reports authenticator_enrolment_in_progress. The Google phone approval appears as the waiting run in Weles Desktop's Running screen and in weles runs show <run>; there is no local-browser fallback.

What each account needs and holds is authenticator list. See subscription login, the command group, or the CLI tree.