Backup and restore

neotoma backup create

Creates a timestamped backup directory containing the SQLite database, the sources directory, and log files. A manifest.json is written with SHA-256 checksums for each file so you can verify integrity later.

Pass --output <dir> to specify a custom backup location. Without it, backups are written to <data-dir>/backups/.

neotoma backup restore --from <backup-dir>

Restores the database, sources, and logs from a backup directory into the active data directory. Stop the API server before restoring.

Pass --target <dir> to restore into a different data directory. The CLI verifies manifest checksums before overwriting.

Use neotoma storage info to see the current layout:

neotoma storage info
# Data directory:   ~/.local/share/neotoma
# Database:         ~/.local/share/neotoma/neotoma.db
# Sources:          ~/.local/share/neotoma/sources/
# Logs:             ~/.local/share/neotoma/logs/

Use neotoma storage set-data-dir <path> to relocate the data directory. The command optionally migrates the existing database to the new location.

Use neotoma storage merge-db to merge two SQLite databases (safe mode by default: the target database is not modified until checksums pass).

If encryption is enabled, backed-up data stays encrypted. When restoring, you need the same encryption key file or mnemonic that was active when the backup was created. Without it the database will be unreadable.

Store your key file or mnemonic separately from the backup, ideally in a password manager or offline vault.

If the SQLite database becomes corrupted (e.g. database disk image is malformed), run:

neotoma storage recover-db          # check integrity
neotoma storage recover-db --recover  # rebuild (stop API first)

The recovery command uses SQLite’s .recover to rebuild the database from surviving pages. Never swap the recovered database in place while the API server is running.