Reset & wipe

Two CLI subcommands cover lifecycle reset:

• vaultbase doctor — pre-flight inspection (read-only; reports issues)
• vaultbase wipe — hard reset (deletes data; production guardrails)

Both are part of the main vaultbase binary; nothing extra to install.

vaultbase doctor

Read-only inspection of the data directory. Reports anything that would block or silently lose data on the next migration / boot:

• Custom field name collisions with auth columns (email, password_hash, totp_secret, …)
• Stranded rows in vb_<auth-col> lacking email/password (typically hand-INSERTed via run_sql or CSV import — the auth flow can’t see them)
• Duplicate emails within an auth collection (would break the unique index after migration)
• JSON data keys on legacy vaultbase_users rows that don’t map to any custom field on the collection (data lost on migration)

Exits 0 on clean / 1 on blockers / 2 when the database is missing or can’t be read. Safe to run in CI:

$ vaultbase doctor
✓ vaultbase doctor — clean. v0.11 migration is safe.

$ vaultbase doctor

✖ 1 blocker(s):
  [members] duplicate email '[email protected]' x2 in vaultbase_users — UNIQUE
  index on the per-collection table will reject this.

⚠ 2 warning(s):
  [members] JSON key 'legacy_blob' present in vaultbase_users.data but
  no matching custom field on the collection. Will be dropped on
  migration unless you add a field.

Fix the blockers, then re-run `vaultbase doctor`.

Doctor never mutates state — diagnostic only. It doesn’t create the data directory or key files, even when pointed at an empty path.

On Postgres

With VAULTBASE_DATABASE_URL set, doctor opens the database as the server does (it refuses another install’s database) and checks:

• the server version (16 or later; older is a blocker) and the schema the server works in (none existing is a blocker);
• whether the connection to a database on another machine is encrypted (sslmode in the URL);
• other schemas on the search path, where a missing table would be read from instead;
• whether the schema is behind this version (the next start adds what is missing);
• pg_dump, pg_restore and psql: missing, older than the server, or too old for restore (a client from August 2025 or later), and whether the server’s role can create the schema a restore stages into;
• enabled hooks, routes, jobs and workers that use helpers.db, which fails on Postgres;
• schemas kept by restores.

$ vaultbase doctor
vaultbase doctor — Postgres 16.4, database app, schema public

⚠ 1 warning(s):
  hook 'audit' uses helpers.db, which fails on Postgres when it runs: change it to helpers.sql.

Since v0.29.0. Exit codes are the same as on SQLite.

vaultbase wipe

Hard-reset the install: delete the database, uploads, logs and keys from the data directory. Next boot triggers the setup-admin wizard.

Wipes:

Path	Contains
<dataDir>/data.db (+ -wal, -shm)	SQLite database
<dataDir>/uploads/	Uploaded files
<dataDir>/logs/	Structured JSONL logs
<dataDir>/sandboxes/	SQL-runner snapshots
<dataDir>/.secret	JWT signing secret
<dataDir>/.encryption-key	Encrypted-at-rest field key
<dataDir>/database.json	Which database the install runs on

Kept: <dataDir>/backups/ (stored snapshots, which hold the whole database including password hashes) and any data.db.bak.<ms> left by a restore. Delete them yourself for a full reset.

Dry run by default

$ vaultbase wipe
vaultbase wipe — target dataDir: ./vaultbase_data

Will delete 6 target(s):
  📄 ./vaultbase_data/data.db  (4.2 MB)
  📄 ./vaultbase_data/data.db-wal  (87 KB)
  📁 ./vaultbase_data/uploads  (2.1 MB)
  📁 ./vaultbase_data/logs  (340 KB)
  📄 ./vaultbase_data/.secret  (64 B)
  📄 ./vaultbase_data/.encryption-key  (32 B)

Database content (will be lost):
  1 admin(s)
  4 collection(s)
  127 auth user(s)
  2840 record(s)

Dry run — no changes made. Re-run with `--yes` to actually delete.

On Postgres

With VAULTBASE_DATABASE_URL set, wipe opens the database as the server does (it refuses another install’s database) and drops from the server’s schema what is Vaultbase’s:

• tables, views and sequences named vaultbase_* or vb_*, and its vb_* functions;
• the schemas restores kept (previous data);
• the install’s read-only login (vb_ro_…).

Anything else in the schema stays, and the dry run lists it, so an install sharing public with other tables leaves them alone. The schema itself stays. Then it deletes the files above, except data.db, which isn’t this install’s. It drops nothing, and deletes nothing, when:

• a Vaultbase server is running on the schema (stop it first, or pass --force);
• the data directory has no database.json while the schema has an admin: nothing says the URL names this install’s database (check it, or pass --force);
• another server holds the migration lock (a restore or a start);
• the server’s role doesn’t own one of the objects;
• something outside Vaultbase depends on one of them, in any schema (a view of your own over a Vaultbase table, a foreign key to one): drop or move it first;
• something that isn’t Vaultbase’s would go with one of them (a partition attached to a Vaultbase table, a sequence owned by one of its columns): detach or drop it first.

Since v0.29.0.

Production guardrails

vaultbase wipe refuses to run when any of the following signals are present, even with --yes:

Signal	Detected
NODE_ENV=production	env var
VAULTBASE_ENV=production or prod	env var
dataDir under /var/lib, /opt, /srv, /etc	path heuristic
Inside Kubernetes pod	KUBERNETES_SERVICE_HOST env var
Fly.io deployment	FLY_APP_NAME env var
Render deployment	RENDER env var
Railway deployment	RAILWAY_ENVIRONMENT env var

Override by passing --force alongside --yes. The flag is two keystrokes saying “yes, I really do mean to nuke production”:

$ NODE_ENV=production vaultbase wipe --yes
...
⚠ PRODUCTION SIGNALS DETECTED:
  - NODE_ENV=production

✖ Refusing to wipe — production signals present. Pass `--force` to override.
$ echo $?
2

$ vaultbase wipe --yes --force
... (deletes everything) ...
✓ Wipe complete — 6/6 target(s) removed. Restart vaultbase to enter the setup wizard.

Custom dataDir

vaultbase wipe honours VAULTBASE_DATA_DIR:

VAULTBASE_DATA_DIR=/var/lib/vaultbase vaultbase wipe --yes  # refused (under /var/lib)
VAULTBASE_DATA_DIR=/var/lib/vaultbase vaultbase wipe --yes --force  # wipes

Manual reset

If you’d rather skip the CLI:

# Hard reset
rm -rf ./vaultbase_data && ./vaultbase

# Soft reset — keep secrets
cd vaultbase_data
rm data.db data.db-wal data.db-shm
rm -rf uploads logs sandboxes

The CLI just wraps these operations with reporting + guardrails.

See also

• Backups & migrations — preserve data instead of wiping
• Deployment — production setup