opschain admin users reset-password

Included from Basic tier

Resets a local user's password and invalidates their refresh tokens. The password conventions match create: supply it via --password-env or --password-prompt, or supply nothing and the server generates one, returned exactly once. Directory users refuse — their credentials live in the directory.

Two lanes:

• Online (default) — calls the admin API (the v2 UserService.ResetUserPassword verb) with the usual --server/--auth-token connection.
• Offline (--offline) — the recovery of last resort for a lost break-glass password. It needs no running server and no API credential: it reads the store DSN from the server's own config.yaml under the OpsChain home (host access, not API access, is the trust boundary) and, in a single database transaction, replaces the password hash, revokes the user's refresh tokens, and records the api:users:reset_password audit event — even last-resort recovery appears in the trail. Only the PostgreSQL store qualifies. Run it on the server host; --home points it at a non-default home.

opschain admin users reset-password emergency.admin --offline
Reset password for emergency.admin (offline, refresh tokens revoked, audit event recorded)
Password: <generated>
Store it now — it is shown exactly once and cannot be retrieved again.

Flags

Flag	Meaning
--password-env <NAME>	Name of an environment variable holding the replacement password (never pass the value itself on the command line).
--password-prompt	Prompt for the replacement password without echo (reads a line from stdin when piped). Mutually exclusive with the flag above.
--offline	Reset directly against the database from the server host's config.yaml (no running server or API credential needed).
--server <url>	Online lane only: server base URL (default: the active context / OPSCHAIN_SERVER).
--auth-token <token>	Online lane only: admin bearer token (default: $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login).

With -o json|yaml a generated password appears in the document; a caller-supplied one is deliberately omitted (the caller already has it).

Exit codes

• 0 — reset.
• 1 — the user does not exist or is a directory identity, the server refused (online), or the database connection failed (offline).
• 2 — usage: the password-flag errors below, the connection errors on opschain docs cli/admin-users, or an unusable offline configuration.

Named errors

• --password-env and --password-prompt are mutually exclusive — exits 2.
• --password-env <NAME>: the environment variable is not set (or empty) — exits 2.
• the offline reset reads the store from <home>/…/config.yaml — run it on the server host (or pass --home) — no server config found; exits 2.
• the offline reset requires the PostgreSQL store (config.yaml names "<store>") — exits 2.
• no local user named "<username>" exists (directory identities are managed in the directory) — offline lane; exits 1.

See also

• opschain docs cli/admin-users-create — the same password conventions at account birth.
• opschain docs cli/admin-users-disable — cutting access instead of rotating it.