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