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原 Hoarder为需要更高阶操作的用户提供了一套官方命令行工具CLI可对书签、列表、标签进行增删改查并支持书签的批量导入导出。本文以 v0.33.0 文档为主线结合仓库内apps/cli的真实源码完整讲解 CLI 的安装方式、认证机制、全部子命令的用法与参数以及配置文件的优先级规则读完即可在脚本、定时任务和服务器管理中熟练驾驭karakeep命令。一、CLI 能做什么特性概览Karakeep CLI 是一个面向想对收藏数据做更高级操作的用户的官方工具核心能力有两块见官方集成文档操作书签、列表与标签创建、查询、更新、删除书签管理列表List及书签与列表、标签的关联关系书签的批量导入/导出既可以通过一条命令批量添加多个链接、笔记、图片/PDF 资产也可以把整个账户的数据连同附件打包导出成归档文件。从源码看CLI 是基于 Node.js 的 Commander 框架编写的见 apps/cli/src/index.ts所有命令最终通过 tRPC 客户端与 Karakeep 服务端 API 交互因此它既适用于自托管实例也适用于 Karakeep 云服务。二、安装 CLI2.1 通过 NPM 全局安装需要 Node.js 环境执行npm install -g karakeep/cli安装完成后karakeep命令即被注册到系统 PATH。在 apps/cli/package.json 中可以确认该包的bin字段正是karakeep指向编译产物dist/index.mjs当前仓库中该包版本为0.33.2与文档版本对应。2.2 通过 Docker 运行无需安装 Node.js直接拉取官方镜像执行docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help--rm表示容器执行完即删除适合临时跑一条命令后续所有示例只需把karakeep替换为上面的docker run ...前缀即可。2.3 在仓库内直接运行开发模式如果是从源码构建或参与开发也可在仓库根目录用 pnpm 直接运行pnpm --filter karakeep/cli run -- karakeep --help或使用包内的开发脚本见 apps/cli/package.json以 tsx 直接执行入口pnpm --filter karakeep/cli run run -- --help三、获取 API Key 与验证连接CLI 与 Karakeep 服务端通信依赖API Key需要登录 Karakeep Web 界面在**设置Settings**中生成。拿到 Key 后可以用whoami命令验证它是否有效karakeep --api-key key --server-addr addr whoami例如karakeep --api-key mysupersecretkey --server-addr https://try.karakeep.app whoami成功时返回当前 API Key 归属用户的信息{ id: j29gnbzxxd01q74j2lu88tnb, name: Test User, email: testgmail.com }whoami在源码中的实现非常直接——调用 tRPC 的users.whoami查询并打印结果见 apps/cli/src/commands/whoami.ts。若 Key 无效或地址错误命令会以非零退出码报错因此它很适合写进脚本做连通性自检。四、认证配置配置文件与优先级规则每次命令都带--api-key和--server-addr太繁琐CLI 支持把认证信息持久化到配置文件。4.1 配置文件位置与格式配置文件路径规则见 apps/cli/src/lib/config.ts若设置了环境变量XDG_CONFIG_HOME路径为$XDG_CONFIG_HOME/karakeep/config.json否则使用~/.config/karakeep/config.json。文件内容为 JSON两个可选字段{ serverAddr: https://try.karakeep.app, apiKey: mysupersecretkey }4.2 交互式生成配置karakeep auth init不熟悉路径或不想手写 JSON 时直接运行karakeep auth init该命令会交互式地依次询问服务器地址和 API Key并把结果写入配置文件见 apps/cli/src/commands/auth.ts。它支持以下选项选项说明--server-addr addr直接指定服务器地址跳过询问--api-key key直接指定 API Key跳过询问-f, --force配置文件已存在时直接覆盖不二次确认值得注意的实现细节写入的配置文件权限被设为0o600仅当前用户可读写见 apps/cli/src/commands/auth.ts保护密钥不被其他系统用户读取若文件已存在且未加--force会先询问是否更新非 TTY 环境下则直接报错提示重跑--force。4.3 优先级命令行 环境变量 配置文件CLI 解析认证参数遵循严格的优先级见 apps/cli/src/index.ts命令行选项优先级最高--api-key、--server-addr显式传入时直接生效其次是环境变量KARAKEEP_API_KEY与KARAKEEP_SERVER_ADDR由 Commander 的.env()声明绑定见 apps/cli/src/index.ts最后是配置文件中的apiKey/serverAddr若仍未提供服务器地址默认回退到https://cloud.karakeep.app常量定义见 apps/cli/src/lib/config.ts若最终拿不到 API KeyCLI 会直接报错并提示用auth init或配置文件补齐见 apps/cli/src/index.ts。另外auth与skill两个命令组是唯一不需要认证即可执行的见 apps/cli/src/index.ts其余所有命令在执行前都会自动完成认证解析失败则终止。五、全局选项与命令总览不带任何参数直接运行karakeep会输出完整的帮助信息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) --json to output the result as JSON -V, --version output the version number -h, --help display help for command Commands: auth authentication 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三个全局选项说明如下全局选项作用环境变量--api-key key指定 API KeyKARAKEEP_API_KEY--server-addr addr指定服务端地址KARAKEEP_SERVER_ADDR--json结果以 JSON 格式输出便于脚本解析—--json特别适合管道处理源码中所有命令的打印都经过统一的输出层见 apps/cli/src/lib/output.ts开启该选项后书签详情、列表、标签、搜索等结果都会输出为结构化 JSON。需要说明的是当前仓库源码注册的命令比 v0.33.0 文档列出的更多。除auth、bookmarks、lists、tags、whoami外karakeep --help实际还会显示admin、assets、highlights、skill、migrate、wipe、dump等命令见 apps/cli/src/index.ts。其中dump即批量导出能力的实现详见下文其余命令可通过karakeep 命令 --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 command6.1add创建书签支持链接/笔记/资产三种类型add是功能最丰富的子命令一次调用可批量创建多种类型的书签实现见 apps/cli/src/commands/bookmarks.ts选项说明--link link添加一个链接书签可重复指定以一次添加多个链接--note note添加一个笔记书签可重复指定--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 会议纪要下周发布计划 --tag-name work --list-id lst_xxx # 把 stdin 内容存为笔记 echo 随手记cli 很好用 | karakeep bookmarks add --stdin # 上传本地 PDF 作为资产书签 karakeep bookmarks add --asset ./paper.pdf --title 论文备份从源码看add的实现有几个值得了解的细节链接与笔记走api.bookmarks.createBookmarktRPC 变更source字段固定标记为cli方便日后在界面上识别来源资产书签先通过POST /api/v1/assets上传文件拿到assetId再创建书签contentType为application/pdf时资产类型判定为pdf否则视为image见 apps/cli/src/commands/bookmarks.ts批量添加的每个条目独立执行、独立报错互不阻塞全部完成后统一打印结果对象再统一处理标签与列表归属。6.2get查询单个书签详情karakeep bookmarks get id默认输出人类可读的详情标题、类型、URL、标签、归档/收藏状态、创建/修改时间、来源、备注、摘要、作者/出版商/抓取状态、附件列表等加--include-content可连同完整内容一起返回。--json模式下会输出规范化后的对象——标签被映射为纯字符串数组见 apps/cli/src/commands/bookmarks.ts。6.3update更新书签属性karakeep bookmarks update id [options]支持的更新选项选项说明--title title更新标题--note note更新备注--description description更新描述--archive/--no-archive归档 / 取消归档--favourite/--no-favourite收藏 / 取消收藏例如karakeep bookmarks update bm_xxx --favourite --no-archive。6.4list分页列出书签karakeep bookmarks list [options]选项说明--include-archived默认不含已归档书签开启后一并列出--list-id id只看指定列表内的书签--tag-id id只看带指定标签的书签--feed-id id只看来自指定 RSS 订阅源的书签--include-content结果中包含完整内容--limit limit每页数量默认 20上限为服务端允许的每页最大书签数--all自动翻页拉取全部书签源码中用while (resp.nextCursor)循环翻页见 apps/cli/src/commands/bookmarks.ts--cursor cursor从上一页返回的游标继续翻页翻页游标cursor由服务端返回CLI 会以 Base64 形式打印Next cursor: ...下次传入--cursor即可续读。注意list默认只返回未归档书签需要归档数据时务必加--include-archived。6.5search按查询语法搜索书签除list外CLI 还内置了搜索子命令karakeep bookmarks search query [options]query支持 Karakeep 的查询匹配器语法如tag:name、is:fav、is:archived等详见搜索查询语言文档--limit默认 50--sort-order可选relevance默认、asc、desc--search-mode可选fts全文检索默认、semantic语义检索、hybrid混合模式需服务端配置相应向量能力同样支持--include-content、--all、--cursor。# 搜索带 work 标签且含 发布 的书签 karakeep bookmarks search tag:work 发布 --search-mode hybrid --all6.6delete删除书签karakeep bookmarks delete id删除成功后打印成功提示失败则输出错误原因并以非零退出码结束。6.7content与import-singlefile进阶子命令除文档列出的基础子命令外当前仓库的bookmarks命令组还包含两个实用扩展均可在karakeep bookmarks --help中看到content id分块拉取书签的可读内容适合把网页正文提取出来做二次处理。支持--format markdown|text、--max-chars单次最大字符数服务端有上限约束、--cursor续读下一页非--json模式下内容直接输出到 stdout下一页游标打印到 stderr见 apps/cli/src/commands/bookmarks.ts。import-singlefile file把 SingleFile 保存的 HTML 归档导入为链接书签。必须用--url url指定被归档页面的原始 URL--if-exists控制遇到同 URL 已有书签时的行为可选skip默认、overwrite、overwrite-recrawl、append、append-recrawl见 apps/cli/src/commands/bookmarks.ts。该命令与文档中的SingleFile 集成指南配合使用效果最佳。七、lists 子命令列表管理运行karakeep listsUsage: 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.tslists list列出全部列表。非 JSON 模式渲染成表格展示Id / Name / Description / Bookmarks四列嵌套列表按树形路径展平显示利用karakeep/shared的listsToTree工具书签数量来自lists.stats统计接口。lists create创建列表。必填--name与--icon一个 emoji--type可选manual手动默认或smart智能列表需配合--query指定搜索查询可选--description、--parent-id指定父列表以构建层级。lists get id查看单个列表详情包含类型、描述、查询、父列表、是否公开、协作信息等。lists add-bookmark --list id --bookmark id把书签加入列表。bookmarks add中的--list-id选项底层复用的就是这套逻辑。lists remove-bookmark --list id --bookmark id从列表移除书签。lists delete id删除列表。# 创建智能列表自动收纳所有带 work 标签的书签 karakeep lists create --name 工作资料 --icon --type smart --query tag:work # 把某书签加入某列表 karakeep lists add-bookmark --list lst_work --bookmark bm_xxx八、tags 子命令标签管理运行karakeep tags可查看标签命令组其实现见 apps/cli/src/commands/tags.tstags list列出全部标签按书签数量降序排列表格展示Id / Name / Num bookmarks。tags get id或tags get --name name按 ID 或名称查询标签。按名称查询时内部会先搜索精确匹配的标签再取 ID见 apps/cli/src/commands/tags.ts。详情中会展示标签总书签数以及人工打标 vs AI 自动打标的拆分统计Breakdown: N by human, N by AI——这正好呼应了 Karakeep 的 AI 自动标签能力。tags merge --into id --from ids...把多个标签合并进目标标签--from支持空格分隔的多个 ID。适合清理语义重复的标签。tags delete id删除标签。# 合并标签把 reading 与 read-later 合并为 later karakeep tags merge --into later的id --from reading的id read-later的id标签与书签的关联也可以直接在bookmarks add--tag-name与bookmarks update-tags id --add-tag x --remove-tag y中完成后者的实现会调用bookmarks.updateTags同时执行附加与分离见 apps/cli/src/commands/bookmarks.ts。九、批量导出dump命令文档强调的书签批量导入/导出能力除了用bookmarks add的多值参数批量导入外导出则由dump命令承担——它会把整个账户的数据连同附件打包成一个.tar.gz归档源码见 apps/cli/src/commands/dump.tskarakeep dump [options]选项说明--output file指定归档输出路径默认生成带时间戳的karakeep-dump-ts.tar.gz--exclude-assets跳过二进制资产不下载附件文件--exclude-bookmarks跳过书签元数据/内容--exclude-lists跳过列表及成员关系--exclude-tags跳过标签--exclude-ai-prompts跳过 AI Prompt 模板--exclude-rules跳过规则引擎规则--exclude-feeds跳过 RSS 订阅源--exclude-webhooks跳过 Webhook 配置--exclude-user-settings跳过用户设置--exclude-link-content导出书签时不含链接正文内容--batch-size n书签分页拉取时的每页数量默认 50受服务端上限约束dump的执行流程从源码可以还原是先写manifest.json含格式标识karakeep.dump、导出时间、服务器地址、用户信息与各类数据计数再按序导出用户设置、列表、标签、规则、订阅源、Prompt、Webhook、书签以 JSONL 逐行写入bookmarks/index.jsonl以便流式处理大库、列表成员关系最后逐页下载全部资产文件到assets/files/并生成资产索引统一打成 tar.gz 后清理临时目录。导出过程中的进度信息会在 TTY 下动态刷新。# 完整备份含附件输出到指定文件 karakeep dump --output ./backup-$(date %F).tar.gz # 只导出元数据不下载大附件 karakeep dump --exclude-assets十、注意事项与最佳实践密钥安全API Key 等同于账户的完整读写权限不要写进脚本参数或提交到版本库。优先使用karakeep auth init生成0o600权限的配置文件或通过环境变量注入whoami是验证 Key 是否有效的最快方式。批量操作的心态bookmarks add的多个值、tags merge的多 ID、--all自动翻页都是为脚本化批量管理设计的配合--json输出与jq等工具可轻松构建自动化流水线。环境变量接入 CI/定时任务由于 CLI 支持KARAKEEP_API_KEY与KARAKEEP_SERVER_ADDR环境变量很适合放进 cron、GitHub Actions 等非交互环境配合auth init --force可完成一次性配置。版本对应本文示例基于仓库内karakeep/cli0.33.2与 v0.33.0 文档不同版本可用karakeep --version核对并以各自--help输出的实际命令为准例如content、import-singlefile、search、dump等为较新版本新增的子命令。关于其他客户端官方文档提及社区维护的非官方Python 客户端karakeep-python-api其功能与官方 CLI 不同、也不受官方支持建议优先使用本文介绍的官方 CLI。十一、总结Karakeep CLI 以一套简洁的命令行语法覆盖了书签收藏系统的高阶操作场景whoami验证连接、auth init持久化认证、bookmarks/lists/tags三大命令组完成数据的增删改查与批量操作、dump实现全量备份导出。它既是日常手动管理的快捷键也是脚本化、自动化工作流中访问 Karakeep 数据最直接的官方通道。【免费下载链接】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），仅供参考