Reset a password

seqdesk reset-password replaces the password of one account in the database an installation is configured to use. It exists for the situation the web application cannot solve on its own: the administrator password is lost, or an install attached to a database that already contained accounts and the credentials the installer printed do not open it.

This is currently the only way to change a password on an existing SeqDesk account. There is no self-service “forgot password” flow, no reset link on the login page, and no change-password screen for a signed-in user; the only route in the application that hashes a password is POST /api/register, which creates a new account. Plan for that: give the administrator account an address a person still controls, and record the password somewhere your facility already trusts.

This grants no privilege the caller did not already have. Anyone who can read settings.json in the install directory can read the database connection string and change the same row by hand. What the command adds is doing it correctly — the right bcrypt cost, the right row, and nothing written to a file afterwards.

Usage


npx -y seqdesk@latest reset-password admin@example.com --dir "$HOME/seqdesk"

If you installed the launcher globally (npm i -g seqdesk@latest) you can drop the npx prefix, and --dir may be omitted when you are already inside the install directory:


cd ~/seqdesk && seqdesk reset-password admin@example.com

Flag	Default	Description
`<address>`	—	The account to reset. May also be written `--email <address>` or `-e`.
`--dir`, `-d`	current directory	The SeqDesk installation root — the directory the installer reported, not `current/`.
`--password <value>`	generate one	Set a password you chose. Use the inline form `--password=<value>` when it starts with `-`.
`--yes`, `-y`	off	Skip the confirmation prompt. Required with `--json`.
`--json`	off	Print one JSON object instead of the readable report.
`--help`, `-h`	—	Show usage and exit.

The address is matched exactly as stored in the User table, the same way the login does. If no row matches but another differs only in capitalisation, the command names that address in the error rather than just reporting “not found”.

What it does, step by step

Reads the installed configuration

The launcher reads settings.json from the install root (falling back to the legacy seqdesk.config.json) and takes runtime.databaseUrl and, if present, runtime.directUrl from it. Connection strings are passed through verbatim, including a ?host=/path/to/socket parameter, so an installation using a SeqDesk-managed socket-only cluster works without extra flags.

Shows you what it is about to change

Before touching anything it prints the account, the install directory, and a summarised database target, then asks:


Reset this account's password? (y/N)

Answer anything other than y/yes and nothing is changed. If stdin is not a terminal — a pipe, a CI step, < /dev/null — no answer can be read and the command exits 1 without changing the password. Pass --yes for automation.

Runs the worker inside the installed release

The actual update is performed by scripts/reset-password.mjs, which ships inside the release under <dir>/current/. That file first appeared in SeqDesk 1.1.125; against an older installed release the command stops and tells you to update rather than failing with a bare file-not-found error.

Prints the new password once

The password is hashed with bcrypt at cost 12 — the same cost the installer’s seed, prisma/seed.mjs and POST /api/register use — and only the hash is stored. The plaintext appears exactly once, on your terminal, and is written to no file and to no log.

Worked example


$ npx -y seqdesk@latest reset-password admin@example.com --dir "$HOME/seqdesk"
SeqDesk reset-password
  Account                  admin@example.com
  Directory                /home/ops/seqdesk
  Database                 /home/ops/.seqdesk/postgres/socket:5432/seqdesk (Unix socket)

This replaces the password of admin@example.com in that database. Nothing else changes.
Reset this account's password? (y/N) y

SeqDesk reset-password
  Account                  admin@example.com
  Name                     Admin User
  Role                     FACILITY_ADMIN
  Directory                /home/ops/seqdesk
  Database                 /home/ops/.seqdesk/postgres/socket:5432/seqdesk (Unix socket)

New password
  qF7mXbTk39wRhnAy2vLd

  Generated for this reset and printed here once.
  It is stored nowhere: SeqDesk keeps only its bcrypt hash, and this command
  writes it to no file. Copy it now, then change it after signing in.

A generated password is 20 characters drawn from the kernel CSPRNG over letters and digits only, with the characters that are misread off a terminal removed (0/O and 1/l/I). There is no punctuation to quote when you paste it.

The command’s closing advice to “change it after signing in” means running this command again — with --password and a value the account holder chose — because the application itself has no change-password screen. Hand the generated password over on a channel you trust; it is a bearer credential for a FACILITY_ADMIN account.

What it does not do

It does not create accounts. An address that is not already in the User table is an error, not an invitation. To add the first administrator to a database that has none, see First Login & Setup.
It does not change roles, emails, or any other field. Only the password column of the one matching row is written.
It does not sign anyone out. SeqDesk uses JWT sessions, so a browser that is already signed in as that account stays signed in until its token expires. Treat a reset as “the old password no longer works”, not as “the account has been locked”.
It does not touch the database schema or any other account.
It cannot be used remotely. It needs shell access to the install directory; there is no HTTP endpoint behind it.

Scripted use

--json prints one object and requires --yes, because the confirmation prompt has no answer in JSON mode:


npx -y seqdesk@latest reset-password admin@example.com \
  --dir "$HOME/seqdesk" --yes --json


{
  "ok": true,
  "installDir": "/home/ops/seqdesk",
  "database": "/home/ops/.seqdesk/postgres/socket:5432/seqdesk (Unix socket)",
  "email": "admin@example.com",
  "role": "FACILITY_ADMIN",
  "firstName": "Admin",
  "lastName": "User",
  "generated": true,
  "password": "qF7mXbTk39wRhnAy2vLd"
}

A failure prints {"ok": false, ...} with an error and usually a remediation string. Treat the output as a secret: it contains the plaintext password, so do not let a CI job archive it.

Exit code	Meaning
`0`	The password was changed
`1`	Nothing was changed — cancelled, account not found, database unreachable, or an install problem
`2`	The command line itself was wrong; usage is printed

Troubleshooting

`Install directory does not exist` / `has no settings.json`

--dir is pointing somewhere that is not a SeqDesk installation root. Use the directory the installer reported ($HOME/seqdesk in these examples), not the current/ symlink inside it. If the directory is right but the config file is missing, recreate the runtime config with a configuration-only rerun:


npx -y seqdesk@latest -y --reconfigure --dir "$HOME/seqdesk"

`No account with the email … exists in this database`

Either the address is spelled differently than it is stored, or --dir points at an install that uses a different database than you think. The command reports a near-match that differs only in capitalisation when it finds one. Confirm which database the directory is wired to with seqdesk doctor, which prints the resolved runtime.databaseUrl.

`PostgreSQL at … did not answer`

The database is down or the URL is wrong; nothing was changed. For a SeqDesk-managed cluster, start it and re-check directly — it is socket-only and neither systemctl nor pg_isready -h 127.0.0.1 says anything about it:


PGROOT="${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}"
pg_ctl -D "$PGROOT/data" status
pg_isready -h "$PGROOT/socket"

See PostgreSQL cannot be reached or migrations fail.

`The installed release has no password-reset worker`

The installed application predates SeqDesk 1.1.125. Update the application first — from Settings → Info → Software Updates in the app, or by re-running the installer against the same directory — and then retry. Upgrading only the npm launcher does not help: the worker lives in the release, not in the launcher.

`Cancelled: no confirmation was read from stdin`

You ran it somewhere without a terminal. Add --yes if you really mean to skip the prompt.

Running the worker by hand

If the launcher itself is the problem, the worker can be run directly from the installed release with the connection string in the environment:


cd "$HOME/seqdesk/current"
DATABASE_URL="postgresql://..." \
  node scripts/reset-password.mjs --email admin@example.com

It exits 2 for a usage error, 3 when the account does not exist, 4 when the database is unreachable, and 1 for anything else.

Common installation problems — including installing against a database that already has accounts.
seqdesk doctor — read-only health check; run it first if you are not sure the install is intact.
First Login & Setup — what the installer printed, and what to do on a database with no accounts at all.