Skip to main content
Version: v0.30.0

Migrating Between Servers

This guide explains how to migrate all of your data from one Karakeep server to another using the official CLI.

What the command does​

The migration copies user-owned data from a source server to a destination server in this order:

  • User settings
  • Lists (preserving hierarchy and settings)
  • RSS feeds
  • AI prompts (custom prompts and their enabled state)
  • Webhooks (URL and events)
  • Tags (ensures tags by name exist)
  • Rule engine rules (IDs remapped to destination equivalents)
  • Bookmarks (links, text, and assets)
    • After creation, attaches the correct tags and adds to the correct lists

Notes:

  • Webhook tokens cannot be read via the API, so tokens are not migrated. Re‑add them on the destination if needed.
  • Asset bookmarks are migrated by downloading the original asset and re‑uploading it to the destination. Only images and PDFs are supported for asset bookmarks.
  • Link bookmarks on the destination may be de‑duplicated if the same URL already exists.

Prerequisites​

  • Install the CLI:
    • NPM: npm install -g @karakeep/cli
    • Docker: docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help
  • Collect API keys and base URLs for both servers:
    • Source: --server-addr, --api-key
    • Destination: --dest-server, --dest-api-key

Quick start​

karakeep --server-addr https://src.example.com --api-key <SOURCE_API_KEY> migrate \
  --dest-server https://dest.example.com \
  --dest-api-key <DEST_API_KEY>

The command is long‑running and shows live progress for each phase. You will be prompted for confirmation; pass --yes to skip the prompt.

Options​

  • --server-addr <url>: Source server base URL
  • --api-key <key>: API key for the source server
  • --dest-server <url>: Destination server base URL
  • --dest-api-key <key>: API key for the destination server
  • --batch-size <n>: Page size for bookmark migration (default 50, max 100)
  • -y, --yes: Skip the confirmation prompt

What to expect​

  • Lists are recreated parent‑first and retain their hierarchy.
  • Feeds, prompts, webhooks, and tags are recreated by value.
  • Rules are recreated after IDs (tags, lists, feeds) are remapped to their corresponding destination IDs.
  • After each bookmark is created, the command attaches the correct tags and adds it to the correct lists.

Caveats and tips​

  • Webhook auth tokens must be re‑entered on the destination after migration.
  • If your destination already contains data, duplicate links may be de‑duplicated; tags and list membership are still applied to the existing bookmark.

Troubleshooting​

  • If the command exits early, you can re‑run it, but note:
    • Tags and lists that already exist are reused.
    • Link de‑duplication avoids duplicate link bookmarks. Notes and assets will get re-created.
    • Rules, webhooks, rss feeds will get re-created and you'll have to manually clean them up afterwards.
    • The progress log indicates how far it got.
  • Use a smaller --batch-size if your source or destination is under heavy load.