Recover access from the command line

When nobody can fix an account in the app, reset admin password, two-factor and lockouts from the server with the reputecast user commands. They talk to the database directly, so they work before any sending provider is connected and while every admin is locked out.

Before you begin

• Shell access to the server that runs ReputeCast.
• The commands need the same configuration as the server, at least the database URL:
  • Docker Compose: run them inside the running app container, which already has its environment: docker compose exec app /usr/local/bin/reputecast user …
  • Binary: load the environment the service uses first, for example set -a; . /etc/reputecast/env; set +a, then run reputecast user ….
• The person’s account email. Every command takes --email.

Each command writes an audit log entry with the actor CLI (server). The commands exit with 0 on success, 2 for a usage error (a missing --reason, a password that is too short) and 1 for other errors, such as Error: no account for <email>.

Situation	Command
Forgotten password	reputecast user reset-password --email <address>
Forgotten password, and no way to pass a link	reputecast user reset-password --email <address> --password …
Lost authenticator app	reputecast user reset-2fa --email <address> --reason "…"
Locked out after failed sign-ins	See clear a sign-in lockout
No instance admin left	reputecast user make-admin --email <address>

Reset a forgotten password

1. Print a one-time reset link:

   docker compose exec app /usr/local/bin/reputecast user reset-password --email aisha@acme.io

   Output

   One-time password reset link for aisha@acme.io (works once, until 12:39 UTC):
   
     https://reputecast.acme.io/reset-password/<token>
   
   Send it to them privately. Their current password keeps working until they use it.

   The link uses the public URL saved in Instance admin › , then Instance & updates, or http.public_url before one is saved. A deactivated account is refused: <email> is deactivated; reactivate the account first.

2. Send the link to the person over a private channel. It works once, for 15 minutes.

3. They open it and choose a new password. The instance’s password policy applies (length, re-use, breach check). Setting it signs out every session and clears a sign-in lockout; the next sign-in still asks for their second factor.

When no sending provider can send on the System stream yet, the sign-in page’s Forgot password? link shows this same command instead of sending an email.

Set a password directly

With --password, the command sets the password at once instead of printing a link:

docker compose exec app /usr/local/bin/reputecast user reset-password --email aisha@acme.io --password 'a long passphrase here'

It answers Password set for aisha@acme.io. Every session was signed out. and cancels open reset links. The password must meet auth.password_min_length from the configuration (default 12 characters), not the policy in Instance admin; a shorter one stops with Error: Use at least 12 characters. Passphrases are fine.

Caution

A password on the command line lands in your shell history. Prefer the reset link, or have the person change the password right after they sign in.

Remove a lost authenticator

1. Confirm the request comes from the person, for example on a call, not from an email asking for it.

2. Remove their authenticator app with a reason, which goes into the audit log:

   docker compose exec app /usr/local/bin/reputecast user reset-2fa --email aisha@acme.io --reason "lost phone, verified by video call"

   It answers Two-factor reset for aisha@acme.io. They have 72 hours to set it up again. Without --reason it stops with Error: --reason is required; it's written to the audit log.

3. The person signs in with their password. The command removed their authenticator and recovery codes and signed out their sessions; their passkeys stay. They are asked to add a passkey or an authenticator again, and must do so within 72 hours.

A person who still has a recovery code doesn’t need this: they choose the recovery code option at the second sign-in step. In the app, an instance admin can do the same reset with Instance admin › , then Users, then ⋯ › Reset two-factor. That version asks for the admin’s password, notifies the person and uses the policy’s grace period instead of 72 hours.

Clear a sign-in lockout

After too many failed passwords (10 by default), sign-in for that email answers Sign-in is locked after too many attempts. Try again after <time>, reset your password, or use a passkey.

• In the app: Instance admin › , then Users, then ⋯ › Unlock sign-in lifts the lock at once.
• With a reset link: setting a new password through a reputecast user reset-password link lifts the lock.
• By waiting: the lock ends by itself after the lock period (15 minutes by default).

reputecast user unlock --email <address> answers <email> can sign in again. and clears the account’s failed-attempt count. In this version it does not lift the lock that password sign-in checks first, so password sign-in stays locked until the lock period ends. Use one of the three ways above.

Make someone an instance admin

docker compose exec app /usr/local/bin/reputecast user make-admin --email linh@acme.io

It answers linh@acme.io is now an instance admin. The command only grants the flag. To take it away, use Instance admin › , then Users, then ⋯ › Remove instance admin.

When single sign-on is down

On a domain where SSO is enforced, password sign-in is off, so a password reset doesn’t help. Owners at that domain marked as break-glass, including the first Owner created by reputecast install, keep password and two-factor sign-in. If none can sign in, make an account at another domain an instance admin and turn enforcement off in Instance admin › , then SSO providers.

Check that it worked

• The person signs in, or opens their reset link before it expires.
• Instance admin › , then Audit log lists the command with the actor CLI (server).

Troubleshooting

• Error: no account for <email>: the email doesn’t match an account. The commands match the address case-insensitively; check for typos or an old address.
• The reset link points at http://localhost:8080: no public URL is saved yet, and http.public_url is the default. Set the public URL, or replace the host in the link with the address people use.
• The command can’t connect to the database with the binary: it doesn’t have the server’s database URL and falls back to the default localhost:5432. Load the service’s environment first.
• Still locked after reputecast user unlock: expected in this version. Use Unlock sign-in in the app, a reset link, or wait for the lock to end.

Defaults and limits

Setting	Default	How to change
Session lifetime	14 days	Instance admin › Authentication; 1 day, 7 days, 14 days or 30 days (API 1–2,160 hours); applies to new sessions
Idle timeout	12 hours	Instance admin › Authentication; 1, 4, 12 or 24 hours (API 5–4,320 minutes), never longer than the session lifetime
Lockout after failed sign-ins	10 failed attempts for one email lock it for 15 minutes	Instance admin › Authentication; 3–100 attempts, 5 minutes, 15 minutes or 1 hour (API 1–1,440 minutes)
Two-factor authentication required for	Members with a sensitive permission	Instance admin › Authentication; everyone, members with a sensitive permission, or off
Grace period to set up two-factor authentication	7 days	Instance admin › Authentication; none, 1, 3, 7 or 14 days (API 0–90)
Minimum password length	12 characters	Instance admin › Authentication, 8–128; passwords can be up to 256 characters
Password re-use	The last 5 passwords are blocked	Instance admin › Authentication; block the last 5, block the last 10, or allow re-use
Check new passwords against known breaches	Off	Instance admin › Authentication
Email domains allowed for new SSO accounts	Up to 50 (none means any domain the identity provider allows)	Instance admin › Authentication
Password reset link	Works once, for 15 minutes	Fixed
Time to set up two-factor authentication again after reputecast user reset-2fa	72 hours	Fixed; a reset in Instance admin › Users uses the policy's grace period
Recovery codes	10, each works once	Account & security › regenerate (replaces all)
Email change verification link	24 hours	Fixed
Time to finish the second sign-in step	10 minutes; 5 wrong codes restart the sign-in	Fixed

Related

• Instance admin: the same actions in the app.
• Secure your account: passwords, passkeys, authenticator apps and recovery codes.
• CLI reference: every reputecast command and flag.