Backup and restore (Markdown)

# Backup and restore

Neotoma stores everything in a single SQLite database, a sources directory for raw file artifacts, and log files. All three live under the data directory (`~/.local/share/neotoma` by default). Backing up Neotoma means copying these files to a safe location; restoring means putting them back.

The CLI provides `neotoma backup create` and `neotoma backup restore` to automate both directions with checksums and a manifest.

## Create a backup

```
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/`.

* * *

## Restore from a backup

```
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.

* * *

## Storage layout

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).

* * *

## Encryption

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.

* * *

## Recovery

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.

See [CLI reference](/cli) for all backup and storage commands, [troubleshooting](/troubleshooting) for common failure modes, and [what to store](/what-to-store) for guidance on what to put in Neotoma in the first place.