Karakeep 命令行工具CLI完全指南书签、列表与标签的高效批量管理【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarderKarakeep自托管书签应用内置了一套基于 Node.js 的命令行工具karakeep/cli让习惯终端操作的高级用户能够绕过 Web 界面直接以脚本化的方式操纵书签bookmarks、列表lists与标签tags并支持批量导入、全量导出乃至服务器间数据迁移。本文以仓库文档 docs/versioned_docs/version-v0.31.0/05-integrations/02-command-line.md 为主线结合 apps/cli 的源码实现完整讲解 CLI 的安装、认证、全局参数、全部子命令的用法与底层原理读完即可用karakeep命令接管日常的书签运维工作。一、CLI 能做什么面向高级用户的终端入口CLI 的设计定位是给想要进行更高级操作的用户提供简单入口核心能力可归纳为两类见 官方文档操纵书签、列表和标签创建、查询、更新、删除以及给书签批量打标签、批量加入列表书签的批量导入/导出既支持一次命令批量添加多条链接/笔记/资产也支持将整个账号的数据导出为归档文件dump或在两个服务器之间迁移migrate。从 apps/cli/src/index.ts 可以看到当前仓库中的 CLI 实际注册了 12 个顶层命令bookmarks、lists、tags、whoami、auth、assets、highlights、admin、skill、migrate、wipe、dump比 v0.31.0 文档列出的命令更丰富。本文以文档记载的bookmarks、lists、tags、whoami为核心展开并补充其余命令。二、安装方式NPM 全局安装或 Docker 即用2.1 通过 NPM 安装官方文档给出的标准安装方式为全局安装 npm 包npm install -g karakeep/cli安装完成后终端中即出现karakeep命令。该包的二进制入口定义在 apps/cli/package.json 的bin字段karakeep: dist/index.mjs包名为karakeep/cli当前仓库内版本为0.33.2。2.2 通过 Docker 运行不想在宿主机装 Node 环境时可以直接用官方镜像临时运行容器退出后自动清理--rmdocker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help该命令直接输出帮助信息适合快速查看命令用法。实际使用时需要把--api-key、--server-addr等参数一并传入容器。2.3 从仓库源码本地运行在开发环境中也可以不安装、直接用源码运行 CLIcd apps/cli pnpm run run -- --help # 内部等价于 tsx src/index.ts --help对应脚本定义在 apps/cli/package.jsonrun脚本调用tsx src/index.ts构建发布则使用pnpm run buildvite 打包并产出可执行文件dist/index.mjs。三、获取 API Key 并验证连接CLI 通过调用 Karakeep 服务器的 HTTP API 工作因此必须先持有 API Key。登录你的 Karakeep 实例自托管地址或云端服务进入用户设置页面找到 API Key 相关设置并复制生成用whoami命令验证 Key 是否有效——它返回该 Key 所属账号的信息实现见 apps/cli/src/commands/whoami.tskarakeep --api-key key --server-addr addr whoami官方文档给出的实际运行示例karakeep --api-key mysupersecretkey --server-addr https://try.karakeep.app whoami { id: j29gnbzxxd01q74j2lu88tnb, name: Test User, email: testgmail.com }看到返回的账号信息即表示 Key 与服务器地址配置正确。注意whoami命中的是users.whoami这个 tRPC 查询见 apps/cli/src/commands/whoami.ts它与 Web 端当前用户接口共用同一路由。四、全局参数、环境变量与认证配置4.1 全局选项karakeep的全局选项定义在 apps/cli/src/index.ts参数说明对应环境变量--api-key key与 API 交互使用的 API KeyKARAKEEP_API_KEY--server-addr addr要连接的服务器地址KARAKEEP_SERVER_ADDR--json以 JSON 格式输出结果—-V, --version输出版本号—-h, --help显示帮助—两个环境变量通过 commander 的.env()注册apps/cli/src/index.ts因此可以免去每次手动传参export KARAKEEP_API_KEYmysupersecretkey export KARAKEEP_SERVER_ADDRhttps://try.karakeep.app karakeep whoami4.2 认证配置文件的加载优先级从 apps/cli/src/index.ts 的resolveGlobalOptions可以看出CLI 解析认证信息遵循明确的优先级命令行显式传入的--api-key与--server-addr否则读取本地配置文件见下服务器地址缺省时使用默认值https://cloud.karakeep.app定义于 apps/cli/src/lib/config.ts若最终仍未拿到 API KeyCLI 会直接报错并提示缺失。配置文件的位置由 apps/cli/src/lib/config.ts 决定优先取XDG_CONFIG_HOME否则取~/.config最终路径为$XDG_CONFIG_HOME/karakeep/config.jsonLinux 下通常是~/.config/karakeep/config.json。文件内容是一个简单的 JSON最多包含apiKey与serverAddr两个字段且经过 zod 校验apps/cli/src/lib/config.ts。4.3 用auth init交互式写入配置与其手写 JSON更推荐使用auth子命令交互式生成配置apps/cli/src/commands/auth.tskarakeep auth init # 交互式输入 server address 与 API key该命令支持--server-addr、--api-key参数跳过提问-f/--force用于无确认覆盖已存在的配置写入的配置文件权限被设置为0o600仅属主可读写apps/cli/src/commands/auth.ts避免 API Key 泄露给同机其他用户。写完配置后karakeep whoami即可免参数直接使用。五、命令总览与帮助系统直接运行karakeep或karakeep --help会看到官方文档记载的完整帮助输出Usage: karakeep [options] [command] A CLI interface to interact with the karakeep api Options: --api-key key the API key to interact with the API (env: KARAKEEP_API_KEY) --server-addr addr the address of the server to connect to (env: KARAKEEP_SERVER_ADDR) -V, --version output the version number -h, --help display help for command Commands: bookmarks manipulating bookmarks lists manipulating lists tags manipulating tags whoami returns info about the owner of this API key help [command] display help for command在 v0.31.0 文档中顶层命令只列了bookmarks、lists、tags、whoami而当前仓库源码apps/cli/src/index.ts已扩展为 12 个命令除上述 4 个外还包括auth认证配置、assets资产管理、highlights高亮管理、dump全量导出、migrate服务器间迁移、wipe清空数据、admin管理操作与skill打印官方 Agent Skill 内容。每个子命令都可继续追加--help查看自己的详细用法例如karakeep bookmarks --help karakeep lists --help六、bookmarks 子命令书签的增删改查与批量导入karakeep bookmarks是使用频率最高的命令组。官方文档展示的基础帮助为Usage: karakeep bookmarks [options] [command] Manipulating bookmarks Options: -h, --help display help for command Commands: add [options] creates a new bookmark get id fetch information about a bookmark update [options] id updates bookmark list [options] list all bookmarks delete id delete a bookmark help [command] display help for command结合当前源码apps/cli/src/commands/bookmarks.ts该命令组实际还包含search、update-tags、content、import-singlefile等子命令。下面逐一详解。6.1bookmarks add一次批量创建多条书签这是最能体现批量能力的命令。其完整选项定义在 apps/cli/src/commands/bookmarks.ts选项说明--link url添加链接书签可重复指定以批量添加多条链接--note text添加笔记TEXT书签可重复指定批量添加--asset file添加本地资产文件图片或 PDF书签可重复指定--stdin从标准输入读取内容并保存为一条笔记书签--list-id id创建后把书签加入指定列表--tag-name tag创建后为书签打上指定标签可重复指定多个--title title覆盖书签标题典型用法# 一次添加两条链接书签 karakeep bookmarks add --link https://example.com/a --link https://example.com/b # 添加一条笔记并同时打两个标签、归入某个列表 karakeep bookmarks add --note 会议纪要Q3 规划 --tag-name work --tag-name meeting --list-id list-id # 用管道把文本内容存为笔记书签 echo 今天读到的灵感 | karakeep bookmarks add --stdin --title 灵感速记 # 批量上传本地图片/PDF karakeep bookmarks add --asset ./photo.png --asset ./report.pdf源码层面add会并行发起所有创建请求Promise.allSettled其中链接与笔记走bookmarks.createBookmarktRPC mutation并统一标记source: cliapps/cli/src/commands/bookmarks.ts资产类书签则会先通过POST /api/v1/assets上传二进制文件拿到assetId后再创建书签且会根据contentType自动区分图片与 PDF 类型apps/cli/src/commands/bookmarks.ts。最后统一执行标签挂载与列表加入apps/cli/src/commands/bookmarks.ts。6.2bookmarks get查看单条书签详情karakeep bookmarks get id karakeep bookmarks get id --include-content # 额外包含完整书签内容非 JSON 模式下get会以人类可读的卡片形式打印书签的标题、ID、类型link/text/asset、URL、标签、归档/收藏状态、创建时间、来源、备注、摘要以及链接类书签的作者、发布者、抓取状态crawlStatus等字段apps/cli/src/commands/bookmarks.ts对资产类书签还会给出可下载的附件地址。6.3bookmarks update更新书签属性karakeep bookmarks update id --title 新标题 karakeep bookmarks update id --note 更新后的备注 --description 新的描述 karakeep bookmarks update id --archive # 归档 karakeep bookmarks update id --no-archive # 取消归档 karakeep bookmarks update id --favourite # 收藏 karakeep bookmarks update id --no-favourite # 取消收藏--archive/--no-archive、--favourite/--no-favourite是成对出现的布尔开关apps/cli/src/commands/bookmarks.ts适合做批量整理脚本。6.4bookmarks list按条件列出书签支持分页karakeep bookmarks list # 默认每页 20 条不含已归档 karakeep bookmarks list --include-archived # 连同已归档书签 karakeep bookmarks list --list-id id # 只看某列表 karakeep bookmarks list --tag-id id # 只看某标签 karakeep bookmarks list --feed-id id # 只看某 RSS 源 karakeep bookmarks list --limit 50 # 每页最多 MAX_NUM_BOOKMARKS_PER_PAGE 条 karakeep bookmarks list --all # 自动翻页取回全部书签 karakeep bookmarks list --include-content # 附带完整内容list支持游标分页非--all模式返回下一页游标Next cursor: base64把游标传给--cursor即可继续翻页apps/cli/src/commands/bookmarks.ts。每次请求的每页上限由服务端常量MAX_NUM_BOOKMARKS_PER_PAGE约束。6.5bookmarks search用查询语法搜索书签karakeep bookmarks search tag:work is:fav # 支持 tag:、is:fav 等匹配器 karakeep bookmarks search rust 教程 --limit 50 karakeep bookmarks search keyword --sort-order relevance # relevance|asc|desc karakeep bookmarks search keyword --search-mode fts # fts|semantic|hybrid karakeep bookmarks search keyword --allsearch的查询字符串与 Web 端搜索语法一致支持tag:name、is:fav等匹配器--search-mode可在全文检索fts、语义检索semantic与混合模式hybrid间切换默认ftsapps/cli/src/commands/bookmarks.ts。结合--json与--all可以很方便地把搜索结果导出给下游脚本。6.6bookmarks update-tags批量增删标签karakeep bookmarks update-tags id --add-tag work --add-tag important --remove-tag old底层调用bookmarks.updateTagsmutationattach/detach分别对应新增与移除apps/cli/src/commands/bookmarks.ts。6.7bookmarks import-singlefile导入 SingleFile 存档Karakeep 支持把 SingleFile 保存的 HTML 页面归档导入为链接书签karakeep bookmarks import-singlefile ./page.html --url https://original.example.com/page karakeep bookmarks import-singlefile ./page.html --url url --if-exists overwrite--if-exists用于指定遇到相同 URL 已有书签时的处理策略可取值包括skip默认、overwrite、overwrite-recrawl、append、append-recrawlapps/cli/src/commands/bookmarks.ts请求发送到POST /api/v1/bookmarks/singlefile。6.8bookmarks delete删除书签karakeep bookmarks delete id执行成功会打印Bookmark with id ... got deletedapps/cli/src/commands/bookmarks.ts。七、lists 子命令列表的管理与书签归属karakeep lists在官方文档中的基础帮助为Usage: karakeep lists [options] [command] Manipulating lists Options: -h, --help display help for command Commands: list lists all lists delete id deletes a list add-bookmark [options] add a bookmark to list remove-bookmark [options] remove a bookmark from list help [command] display help for command当前源码apps/cli/src/commands/lists.ts进一步补充了create与get两个命令karakeep lists list # 以表格列出所有列表含层级路径与书签数 karakeep lists get id # 查看单个列表详情图标、类型、公开状态、协作等 karakeep lists create --name 读书清单 --icon \ --description 技术书籍 --type manual # type: manual|smart karakeep lists create --name AI 相关 --icon --type smart --query tag:ai karakeep lists delete id karakeep lists add-bookmark --list id --bookmark bookmark-id karakeep lists remove-bookmark --list id --bookmark bookmark-id几个值得注意的实现细节lists list会并行调用lists.list与lists.stats两个查询把列表渲染成Id / Name / Description / Bookmarks表格并借助karakeep/shared的listsToTree与listNameFromPath工具展示嵌套层级apps/cli/src/commands/lists.tscreate支持--type smart智能列表需配合--query传入搜索查询表达式apps/cli/src/commands/lists.tsadd-bookmark内部复用了addToList函数apps/cli/src/commands/lists.ts而bookmarks add --list-id也正是通过它把新书签直接挂入列表。八、tags 子命令标签的列出、查询、合并与删除karakeep tags list # 按书签数降序列出全部标签 karakeep tags get tag-id # 按 ID 查看标签 karakeep tags get --name work # 或按名称精确查找 karakeep tags merge --into target-id --from id1 id2 # 合并多个标签到目标标签 karakeep tags delete id # 删除标签源码实现要点apps/cli/src/commands/tags.tstags list展示Id / Name / Num bookmarks表格并按书签数降序排列apps/cli/src/commands/tags.tstags get支持按名称反查先用nameContains列出候选再精确匹配名称得到 IDapps/cli/src/commands/tags.ts详情中还会区分由人打标与由 AI 打标的数量numBookmarksByAttachedTypetags merge通过tags.mergemutation 把若干来源标签合并进目标标签是清理标签体系的高效手段apps/cli/src/commands/tags.ts。九、进阶命令全量导出与服务器间迁移官方文档在功能列表里明确提到书签的批量导入/导出Mass import/export除bookmarks add外当前仓库还提供了两个重量级命令。9.1dump把整个账号数据导出为 tar.gz 归档karakeep dump # 默认输出 karakeep-dump-时间戳.tar.gz karakeep dump --output ./backup.tar.gz karakeep dump --exclude-assets # 跳过二进制资产 karakeep dump --exclude-bookmarks --exclude-lists --exclude-tags karakeep dump --batch-size 100 # 每页书签数默认 50上限 MAX_NUM_BOOKMARKS_PER_PAGEdumpapps/cli/src/commands/dump.ts会依次导出用户设置、列表、标签、规则、RSS 源、AI 提示词、Webhook、书签JSONL 格式 列表成员关系、资产二进制文件最后写入manifest.json并打包成 tar.gz。导出的书签通过游标分页流式读取资产逐个从/api/assets/id下载各数据类别都可用对应的--exclude-*参数裁剪从而只备份关心的部分。9.2migrate在服务器之间迁移数据karakeep migrate --dest-server https://new.example.com --dest-api-key key karakeep migrate --dest-server url --dest-api-key key -y # 跳过确认提示 karakeep migrate --dest-server url --dest-api-key key --exclude-assetsmigrateapps/cli/src/commands/migrate.ts读取当前配置指向的源服务器即--server-addr对应实例把用户设置、列表、RSS 源、AI 提示词、Webhook、标签、规则、书签含标签与列表归属迁移到目标服务器。它维护了列表/标签/RSS 源在源、目标两侧的 ID 映射并在迁移规则引擎规则时做条件与动作中相关 ID 的重映射remapRuleIdsapps/cli/src/commands/migrate.ts资产类书签会先从源下载再上传到目标端。执行前默认会弹出yes/no确认-y可跳过。十、脚本化友好--json输出与数据格式CLI 所有查询类命令都支持全局--json标志把结果以结构化 JSON 输出方便被 jq、Python 等下游工具消费karakeep --json bookmarks list --all karakeep --json tags list karakeep --json lists list karakeep --json bookmarks search tag:work --all值得注意的细节非 JSON 模式下书签列表打印的是精简卡片标题、ID、类型、创建时间、URL、标签、归档/收藏状态等见printBookmarkCard而--json模式会返回完整字段并把书签的 tags 规范化为纯名称数组normalizeBookmarkapps/cli/src/commands/bookmarks.ts便于程序直接使用。十一、底层原理CLI 如何与 Karakeep API 通信CLI 本身并不直接访问数据库而是通过 Karakeep 服务端的tRPC 批量 HTTP 端点通信。关键实现位于 apps/cli/src/lib/trpc.ts客户端使用trpc/client的httpBatchLink请求地址为server-addr/api/trpc即与 Web 前端共用同一套 tRPC 路由AppRouter来自 packages/trpc/routers/_app.ts每次请求都会在 header 中携带authorization: Bearer api-keyapps/cli/src/lib/trpc.ts这也是 API Key 必须正确的原因数据序列化使用superjson因此日期等复杂类型可以在 CLI 与服务端之间无损传输所有命令执行前preAction钩子会先解析全局认证apps/cli/src/index.tsauth与skill两个命令例外无需认证即可运行。另外CLI 中直接调用 REST 端点的场景包括书签资产的二进制上传POST /api/v1/assets、SingleFile 导入POST /api/v1/bookmarks/singlefile、可读内容分块获取GET /api/v1/bookmarks/id/content以及资产下载GET /api/v1/assets/id——凡涉及二进制流的操作都绕过 tRPC 走原生 fetch。十二、关于其他客户端的一点说明官方文档在文末还提到社区维护着一个非官方的 Python 包karakeep-python-api可以从 CLI/脚本中调用 Karakeep API但它并非官方维护使用时需自行甄别其功能完整性与安全性。官方推荐路径仍然是本文介绍的karakeep/cli。十三、小结与最佳实践日常批量入库用karakeep bookmarks add配合--link/--note/--asset重复参数一次创建多条书签配合--tag-name与--list-id一步到位完成归类定期备份用karakeep dump把书签、列表、标签与资产整体导出为 tar.gz配合--exclude-*控制备份粒度更换实例用karakeep migrate在两台服务器间迁移数据注意先确认目标服务器 API Key 具备写入权限脚本集成给关键命令加上全局--json用游标与--all处理大数据量把 CLI 输出接入 cron、CI 或自研工作流配置管理通过karakeep auth init一次性写入~/.config/karakeep/config.json权限 0600日常使用即可省略--api-key与--server-addr。如需查看每条命令的完整选项随时执行karakeep command --help深入理解实现可阅读 apps/cli/src 目录下各命令文件与 apps/cli/src/lib 的配置、tRPC 客户端封装。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考