Table of contents
CLI Password Reset
Operator-facing recovery tool: reset any user's password directly against the database when email self-service reset is unavailable (email delivery is out of scope for v1 — see specs/001-v1-baseline/open-questions.md, "Auth And Session UX").
ADR: docs/adr/0056-cli-password-reset-slim-context.json
Usage
echo -n "$PW" | docker compose exec -T memories-api java -jar /app/memories-api.jar --reset-password [email protected] --password-stdin
Generate a strong password first (12 characters minimum, enforced by the same policy as login):
PW=$(openssl rand -base64 18)
Environment-variable fallback (prefer stdin; env vars leak into /proc/<pid>/environ
and CI logs more easily than stdin pipes):
MEMORIES_RESET_PASSWORD="$PW" docker compose exec memories-api java -jar /app/memories-api.jar --reset-password [email protected]
The CLI runs inside the existing API container. It starts a slim Spring context (same image as the web API) with web/schedulers/security disabled — safe to run while the web API is up; only run one reset at a time.
Behavior
- Normalizes the email exactly like login (lowercase, trim).
- Looks the user up in
user_accounts:- unknown email → exit code 2, no changes
- disabled user → exit code 3, no changes
- Validates password policy (≥ 12 chars) → exit code 4 on violation, no changes.
- In one transaction:
- updates
user_accounts.password_hash - writes an
audit_eventsrow (event_type='password_reset',actor_user_id=NULL,subject_type='user_account',subject_id=<user>,details={"actor":"cli","target_email":<normalized email>}) - deletes all indexed sessions of the user
(
DELETE FROM spring_session WHERE principal_name = :userId; attribute rows go through the FK cascade)
- updates
The password is read from stdin or the environment variable — never from a command-line argument (shell-history leak). Neither the password nor its hash is printed anywhere.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Password reset |
| 1 | Internal error (CLI/context startup failure) |
| 2 | Unknown email |
| 3 | Disabled user |
| 4 | Password policy violation (< 12 chars) |
| 5 | Usage error or stdin/IO failure |
Limitations
- Legacy sessions are not invalidated. Sessions created before the
principal-name indexing shipped have
principal_name IS NULLand survive a password reset. New sessions (post-deploy logins) are invalidated. See ISSUE-015 (SessionAuthenticationFilter trusts the session attribute without DB revalidation) — an attacker holding a legacy session cookie retains access up to the session TTL even after a reset. Remediation path: backfillprincipal_namefromspring_session_attributes, or hard-logout on disable. - Any operator with container/DB access can reset any user. The CLI is a
server-side operator tool, not a UI capability: super-admin gating from the
old (never-wired)
resetPasswordAsSuperAdminservice method is replaced by physical container access as the trust boundary. Audit rows make every reset attributable. - No email self-service reset — still deferred (see spec 001 open questions).
- The CLI accepts exactly
--reset-password <email>plus--password-stdin; any other argument is a usage error (exit 5). The web server never starts in CLI mode.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference