Migrate from Grimoire v0.5

Grimoire 1.1.0 includes an experimental migration tool for importing one owner's library from the legacy Grimoire v0.5 SQLite application into a local Grimoire 1.x library.

The migrator supports v0.5 SQLite data only. PocketBase-era backups from the older 0.3.x line are not supported.

Before you start

1. Stop the old Grimoire v0.5 process.

2. Keep the original v0.5 data directory and make a separate backup of it.

3. Install and start Grimoire 1.x, then check the local daemon:

   curl http://127.0.0.1:3210/health

The migrator reads a temporary snapshot of the v0.5 database and does not modify the source database or its WAL sidecars. Keep the source until you have reviewed the imported library and warnings.

Supported source formats

CLI option	Source	Media behavior
--data-dir DIR	v0.5 data/ directory containing db.sqlite	Finds user-uploads/ beside the database
--db FILE	A v0.5 db.sqlite file	Add --uploads-dir DIR for separately stored media
--archive FILE	.zip, .tar, .tar.gz/.tgz, .tar.bz2, or .tar.xz	Include user-uploads/ for local media

Migration workflow

1. Inspect the source

littleimp migrate inspect --data-dir /path/to/grimoire/data

This is read-only. It lists the v0.5 owners and counts for bookmarks, categories, tags, and referenced media. For an archive:

littleimp migrate inspect --archive /path/to/grimoire-data.tar.gz

If more than one user is listed, choose one with --owner using the username, email, or numeric v0.5 user ID.

2. Preview with a dry run

littleimp migrate apply \
  --data-dir /path/to/grimoire/data \
  --owner YOUR_USERNAME \
  --dry-run

The dry run does not change the Grimoire 1.x database or media cache. Review its counts and warnings before applying.

3. Apply explicitly

littleimp migrate apply \
  --data-dir /path/to/grimoire/data \
  --owner YOUR_USERNAME \
  --yes

--yes is required because apply writes into the local library. The archive form is equivalent:

littleimp migrate apply \
  --archive /path/to/grimoire-data.tar.gz \
  --owner YOUR_USERNAME \
  --yes

By default, existing bookmarks with the same canonical URL are skipped. Add --merge when re-running a migration and you want existing URLs reconciled. Apply is additive; it does not wipe the existing 1.x library.

Optional password verification

Password verification proves ownership of the selected v0.5 account. It does not create a Grimoire 1.x account or restore multi-user login behavior.

Prefer a password file or environment variable over shell history:

littleimp migrate apply \
  --data-dir /path/to/grimoire/data \
  --owner YOUR_USERNAME \
  --password-file /path/to/v05-password.txt \
  --yes

LITTLEIMP_MIGRATE_PASSWORD='your-v05-password' \
  littleimp migrate apply \
    --data-dir /path/to/grimoire/data \
    --owner YOUR_USERNAME \
    --yes

The CLI also accepts --db FILE with --uploads-dir DIR, --json for machine-readable output, and --daemon-url URL for a daemon on another local port.

What is imported

The selected owner's bookmarks, content fields, notes, read/archive/pin state, open counts, categories, tags, and available local favicon/image/screenshot files are imported where the source data is valid. Existing categories and tags are reused when they match the local library.

Grimoire preserves safe private or LAN bookmark URLs as library data but does not fetch them after migration. Remote-only media is not downloaded. Invalid URLs, missing references, unsafe media paths, and invalid media files appear as skipped items or warnings.

Grimoire 1.x remains local-first and single-user. The migration does not import v0.5 users, password hashes, sessions, or account administration.

Safety and recovery

• Apply changes are additive and committed in a database transaction.
• Individual bookmark or media problems can be reported while the rest of the migration continues.
• The CLI exits non-zero when bookmarks fail, even if the successful part was committed; review the warnings in the summary.
• Archive paths, links, extraction depth, and expanded size are checked before archive data is used.

Create a Grimoire backup before applying if the 1.x library already contains important bookmarks. See the full migration guide in the repository for detailed troubleshooting and recovery notes.

API reference

The same workflow is available through the daemon's POST /migrate/legacy/inspect and POST /migrate/legacy/apply routes.