1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
# 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.
|
