尧图网站建设 
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面向希望绕过 Web 界面、对书签bookmark、列表list和标签tag进行更高级、可脚本化操作的用户。本文以 docs/docs/05-integrations/02-command-line.md 为骨架结合apps/cli的真实源码系统讲解 CLI 的安装方式、认证机制、完整命令体系、参数细节与底层实现原理。读完本文你将能够在终端中完成书签的增删改查、批量导入导出、列表与标签管理、数据备份迁移等全部日常运维工作。一、CLI 能做什么核心能力概览Karakeep CLI 的核心定位是面向高级用户与自动化场景的 API 交互前端。根据官方文档它主要提供两大能力操作书签、列表与标签包括书签的创建链接 / 笔记 / 图片与 PDF 等资产、查询、更新、删除、搜索列表的创建与管理标签的合并与删除等书签的批量导入 / 导出支持从 stdin 读入内容、多文件批量添加以及将账号全部数据含二进制资产打包导出为归档文件。从源码结构看CLI 的实际能力远超文档列举的范围。apps/cli/src/index.ts注册了 12 个顶层命令组命令组源码文件用途authapps/cli/src/commands/auth.ts认证配置的交互式初始化bookmarksapps/cli/src/commands/bookmarks.ts书签的增删改查、搜索、内容获取、SingleFile 导入listsapps/cli/src/commands/lists.ts列表的创建、查询、删除与成员管理tagsapps/cli/src/commands/tags.ts标签的列出、查询、合并与删除highlightsapps/cli/src/commands/highlights.ts高亮highlight的列出与删除assetsapps/cli/src/commands/assets.ts资产下载whoamiapps/cli/src/commands/whoami.ts查看 API Key 对应的用户信息dumpapps/cli/src/commands/dump.ts将账号全部数据与资产打包导出为.tar.gzmigrateapps/cli/src/commands/migrate.ts数据迁移从旧服务端批量搬运数据wipeapps/cli/src/commands/wipe.ts清空账号数据adminapps/cli/src/commands/admin.ts管理员维护操作重爬、重建索引、批量重打标签等skillapps/cli/src/commands/skill.ts输出官方 Agent Skill 内容二、安装 CLINPM、Docker 与系统包2.1 通过 NPM 全局安装CLI 以 npm 包形式发布官方包名为karakeep/cli见 apps/cli/package.json其bin字段将可执行命令映射为karakeepnpm install -g karakeep/cli安装完成后终端中直接输入karakeep即可使用。2.2 通过 Docker 运行如果你不想在宿主机安装 Node.js 环境可以使用官方发布的 CLI 镜像--rm表示容器运行完即删除docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help在 Docker 方式下每次调用都需要挂载配置或显式传入--api-key/--server-addr参数详见第三节。2.3 其他安装途径仓库文档中还提到Arch Linux 用户可通过 AUR 安装见 docs/docs/02-installation/03-archlinux.mdparu -S karakeep-cli如果你需要从源码构建可在仓库根目录执行pnpm install后进入apps/cli目录运行pnpm build构建脚本会生成dist/index.mjs并赋予可执行权限或使用pnpm run通过tsx直接运行 TypeScript 源码。三、全局选项与认证机制3.1 全局选项一览运行karakeep --help可看到完整的全局选项以下内容与源码 apps/cli/src/index.ts 中的定义一致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 所需的密钥可通过环境变量KARAKEEP_API_KEY提供--server-addr addr要连接的 Karakeep 服务端地址可通过环境变量KARAKEEP_SERVER_ADDR提供--json以 JSON 格式输出结果方便管道处理与脚本解析。在源码中这三个选项通过 Commander 的Option.env()绑定环境变量见 apps/cli/src/index.ts因此命令行参数、环境变量与配置文件三者可以混用。3.2 获取 API Key 并验证连通性要使用 CLI你需要在 Karakeep 服务端的设置页面中生成一个 API Key。拿到 Key 后可以用whoami命令验证它是否有效karakeep --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 }从源码看whoami命令内部调用的是 tRPC 的users.whoami查询apps/cli/src/commands/whoami.ts返回值即当前 API Key 所归属用户的id、name、email字段。这一步是排查密钥无效 / 服务地址不可达类问题的最快手段。3.3 配置文件把认证信息持久化为避免每次命令都输入冗长的参数CLI 支持从配置文件读取服务端地址与 API Key。配置文件默认路径遵循 XDG 规范若设置了环境变量XDG_CONFIG_HOME则读取$XDG_CONFIG_HOME/karakeep/config.json否则读取~/.config/karakeep/config.json。该逻辑实现在 apps/cli/src/lib/config.ts 的getConfigPath()中。配置文件内容格式为{ serverAddr: https://try.karakeep.app, apiKey: mysupersecretkey }配置文件的字段通过 Zod schema 校验zCliConfigFileSchema见 apps/cli/src/lib/config.tsapiKey与serverAddr均为可选的非空字符串同时允许包含其他未知字段passthrough()因此即使你往文件里额外写了自定义字段也不会导致解析失败。3.4 三种配置来源的优先级官方文档明确规定了配置的生效顺序命令行选项 环境变量 配置文件如果既没有提供服务端地址也没有在配置文件中设置CLI 默认回退到https://cloud.karakeep.app该常量定义于 apps/cli/src/lib/config.ts 的DEFAULT_SERVER_ADDR。源码中的resolveGlobalOptions()apps/cli/src/index.ts精确实现了这一逻辑先看命令行选项是否同时给出apiKey与serverAddr否则加载配置文件再按选项 → 配置文件 → 默认值逐级兜底若最终仍缺少 API Key则直接报错并提示缺失项。另外auth与skill两个命令组不需要认证其余所有命令在执行前都会自动完成全局选项解析preAction钩子apps/cli/src/index.ts。3.5 交互式初始化karakeep auth init不想手写 JSON运行karakeep auth init该命令会以交互方式提示你输入服务端地址与 API Key并把结果写入config.json源码见 apps/cli/src/commands/auth.ts。它还支持--server-addr addr/--api-key key跳过交互直接以命令行参数提供-f, --force配置文件已存在时不加确认直接覆盖若配置文件已存在且未加-f会先询问你是否更新写入文件时会自动创建目录并将文件权限设为0600仅当前用户可读写保护密钥安全。四、命令体系详解从顶层到子命令4.1 顶层命令虽然--help只列出了 6 个命令但如前文所述源码实际上注册了 12 个命令组apps/cli/src/index.ts。其中文档重点介绍的三个是bookmarks、lists、tags其余为高级/运维命令。4.2 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.tsbookmarks组实际拥有 8 个子命令下面逐一说明。创建书签bookmarks addadd支持一次创建多种类型的书签且各选项可重复指定以实现批量添加--link link添加链接书签可重复指定多个 URL--note note添加文本笔记书签可重复指定多条--asset file添加资产书签图片或 PDF传文件路径可重复指定多个文件--stdin从标准输入读取文本作为一条笔记书签保存适合echo xxx | karakeep bookmarks add --stdin这类管道用法--list-id id创建后自动将书签加入指定列表--tag-name tag创建后自动打上指定标签可重复指定多个--title title自定义书签标题默认取页面标题或内容前 50 个字符。典型用法# 添加一个链接并打标签 karakeep bookmarks add --link https://example.com --tag-name tech # 批量添加三个链接 karakeep bookmarks add --link https://a.com --link https://b.com --link https://c.com # 从 stdin 保存一条笔记 echo 购物清单牛奶、鸡蛋 | karakeep bookmarks add --stdin # 添加本地 PDF 并加入指定列表 karakeep bookmarks add --asset ./report.pdf --list-id lv2f9xxd01q74j2lu88tna从源码实现看apps/cli/src/commands/bookmarks.ts链接和笔记直接调用 tRPC 的bookmarks.createBookmark资产类书签则分两步先通过POST {serverAddr}/api/v1/assets上传文件携带Bearer认证头拿到assetId后再创建 ASSET 类型书签并按contentType自动判定资产类型application/pdf记为pdf其余记为image。所有创建请求并行执行Promise.allSettled单个失败不会影响其他书签的创建。查询单个书签bookmarks get idkarakeep bookmarks get id附加选项--include-content可在结果中包含完整书签内容。默认输出为可读格式标题、Id、类型link / text / asset资产会带assetType、URL、标签、归档/收藏状态、创建与修改时间、来源、备注、摘要等对链接书签还会显示作者、发布者、描述与爬取状态crawlStatus对文本书签会直接打印正文对带附件的书签会列出每个附件的 Id 与可访问 URL格式为{serverAddr}/api/assets/{assetId}。加--json后输出规范化的 JSON标签会被拍平为名称数组见normalizeBookmark。更新书签bookmarks update idkarakeep bookmarks update id [options]支持的更新选项--title title更新标题--note note更新备注--archive/--no-archive归档 / 取消归档--favourite/--no-favourite收藏 / 取消收藏--description description更新描述。更新通过 tRPC 的bookmarks.updateBookmark完成apps/cli/src/commands/bookmarks.ts。单独调整标签bookmarks update-tags idkarakeep bookmarks update-tags id --add-tag ai --remove-tag old-tag--add-tag与--remove-tag均可重复指定内部调用bookmarks.updateTags一次性完成挂载attach与摘除detach操作。列出书签bookmarks listkarakeep bookmarks list [options]--include-archived默认只列出未归档书签加此参数后同时包含已归档项--list-id id只列出指定列表内的书签--tag-id id只列出带指定标签的书签--feed-id id只列出来自指定 RSS Feed 的书签--include-content结果中包含完整内容--limit limit每页数量默认 20上限由MAX_NUM_BOOKMARKS_PER_PAGE决定超出会自动截断--all自动翻页拉取全部书签--cursor cursor使用上一次返回的游标继续分页。分页游标在 CLI 内部以 Base64 编码传递源码中Buffer.from(JSON.stringify(resp.nextCursor)).toString(base64)翻页时把上次输出的Next cursor: ...原样传回即可。搜索书签bookmarks search querykarakeep bookmarks search tag:ai is:fav [options]搜索查询支持 Karakeep 的查询匹配器语法如tag:name、is:fav等详见 docs/docs/04-using-karakeep/search-query-language.md。可用选项--limit limit结果条数默认 50--sort-order order排序方式可选relevance默认/asc/desc--search-mode mode搜索模式可选fts全文搜索默认/semantic语义搜索/hybrid混合--include-content结果包含完整内容--all拉取全部结果--cursor cursor分页游标。参数校验在源码中均做了严格限制apps/cli/src/commands/bookmarks.ts非法值会直接报错。获取可读内容bookmarks content id对于需要把书签正文交给其他工具如 LLM的场景content命令可以按块获取可读内容--format format内容格式markdown或text--max-chars count本次获取的最大 Unicode 字符数上限MAX_READABLE_CONTENT_MAX_CHARS--cursor cursor续读游标。响应中包含range本次返回的起止位置与总量与nextCursor字段非 JSON 模式下 CLI 会把正文直接写到 stdout并在末尾提示下一次的游标值适合做流式拼接。导入 SingleFile 归档bookmarks import-singlefile将 SingleFile 保存的完整 HTML 归档导入为链接书签karakeep bookmarks import-singlefile file --url original-url [--if-exists skip]--url url必填被归档页面的原始 URL--if-exists mode当同 URL 书签已存在时的处理策略可选skip默认、overwrite、overwrite-recrawl、append、append-recrawl。该命令走的是独立的上传端点POST {serverAddr}/api/v1/bookmarks/singlefile?ifexistsmodeapps/cli/src/commands/bookmarks.ts是迁移浏览器本地归档内容的高效通道。删除书签bookmarks delete idkarakeep bookmarks delete id删除成功会输出Success: Bookmark with id xxx got deleted。4.3 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实际子命令如下list以表格形式列出全部列表Id、名称、描述、书签数嵌套列表会按路径层级展开借助karakeep/shared的listsToTree/listNameFromPath工具get id查看单个列表详情名称、类型、描述、查询、父列表、是否公开、用户角色、是否有协作者create创建列表参数包括必填的--name name与--icon icon一个 emoji 图标、可选的--type typemanual或smart默认manual、--description、--query智能列表的搜索查询智能列表必填、--parent-id父列表用于构建嵌套结构delete id删除列表add-bookmark --list id --bookmark id把书签加入列表remove-bookmark --list id --bookmark id把书签从列表移除。另外在bookmarks add时使用--list-id参数内部会复用同一套addToList逻辑apps/cli/src/commands/lists.ts。4.4 tags标签操作karakeep tags实际子命令apps/cli/src/commands/tags.tslist以表格列出所有标签Id、名称、书签数默认按书签数降序排列get [id]或get --name name按 Id 或名称查询单个标签输出书签总数以及人工标记 / AI 标记的数量拆分numBookmarksByAttachedType这正是 Karakeep AI 自动打标能力在 CLI 侧的呈现merge --into id --from ids...把多个标签合并进目标标签--from传多个空格分隔的标签 Id适合整理冗余标签delete id删除标签。4.5 其他命令whoami返回 API Key 所属用户信息见 3.2 节highlights list [--bookmark id] [--limit n] [--all] [--cursor c]、highlights get id、highlights delete id管理书签高亮源码 apps/cli/src/commands/highlights.tsassets download id [--output path]下载指定资产文件源码 apps/cli/src/commands/assets.tsdump [--output file] [--exclude-*]把账号全部数据打包为.tar.gz详见第五节migrate在服务端之间批量迁移书签/列表/标签等数据源码 apps/cli/src/commands/migrate.tswipe清空账号数据危险操作源码 apps/cli/src/commands/wipe.tsadmin管理员维护命令包括对单个书签的debug/recrawl/reindex/regenerate-embedding/retag/resummarize以及全库范围的recrawl-links/reindex-all/retag-all/resummarize-all/regenerate-embeddings/reprocess-assets和作业统计jobs stats、订阅同步subscriptions sync等源码 apps/cli/src/commands/admin.tsskill直接把官方 Karakeep Agent Skillskills/SKILL.md打印到 stdout方便 AI Agent 读取源码 apps/cli/src/commands/skill.ts。五、数据导出与迁移dump命令实战dump是 CLI 中最具实用价值的运维命令之一它能把账号下的所有数据连同二进制资产一并打包成一个归档文件源码 apps/cli/src/commands/dump.tskarakeep dump --output ./backup-$(date %F).tar.gz归档内结构清晰manifest.json格式标记karakeep.dump、版本号、导出时间、服务端地址、用户信息与各类数据计数、users/settings.json、lists/index.json与lists/membership.json、tags/index.json、rules/index.json、feeds/index.json、prompts/index.json、webhooks/index.json、bookmarks/index.jsonlJSON Lines 流式写入适合大库、assets/index.json与assets/files/资产二进制文件。dump支持按需裁剪的排除参数用于只备份部分数据或跳过体积较大的二进制资产--exclude-assets跳过资产含索引与文件--exclude-bookmarks跳过书签元数据/内容--exclude-lists跳过列表及成员关系--exclude-tags跳过标签--exclude-ai-prompts跳过 AI 提示词--exclude-rules跳过规则引擎规则--exclude-feeds跳过 RSS Feed--exclude-webhooks跳过 Webhook--exclude-user-settings跳过用户设置--exclude-link-content跳过链接正文内容仅保留元数据可显著缩小体积--batch-size n分页拉取书签时的每页数量上限MAX_NUM_BOOKMARKS_PER_PAGE默认 50。执行过程中会实时显示每类数据的导出进度书签、列表扫描、资产下载均带进度指示最终调用系统tar打包。该命令与 Web 端的数据导出备份能力互为补充是服务器迁移可配合 docs/docs/06-administration/06-server-migration.md和定期异地备份的推荐手段。六、输出格式化人类可读与 JSON 自由切换所有命令都支持全局的--json标志。以bookmarks list为例默认输出是带颜色高亮的人类可读卡片标题、Id、类型、创建时间、URL、标签、归档/收藏状态、备注等加上--json后则输出规范化的 JSON 结构其中标签从对象数组被拍平为字符串数组便于jq等工具进一步处理。输出层的实现集中在 apps/cli/src/lib/output.tsprintObject根据--json标志决定调用JSON.stringify缩进 4 空格还是 Node 的console.dirprintStatusMessage/printSuccess/printError则统一输出Success: .../Error: ...形式的状态行成功绿色、失败红色。这意味着 CLI 既适合人眼阅读也能无缝接入 shell 脚本与自动化流水线。七、底层实现解析CLI 如何与 Karakeep API 通信理解 CLI 的通信机制有助于排查连接问题也有助于开发自己的脚本。关键实现在 apps/cli/src/lib/trpc.tsCLI 使用tRPC 客户端与 Karakeep 服务端通信连接地址为{serverAddr}/api/trpc通过httpBatchLink批量发送请求可减少 HTTP 往返次数并使用superjson作为序列化器这也是为什么日期等复杂类型能正确往返每个请求自动附带Authorization: Bearer {apiKey}请求头这就是 API Key 的传递方式tRPC 的AppRouter类型直接复用karakeep/trpc包packages/trpc/routers因此 CLI 与 Web 前端共享同一套类型安全的路由定义命令参数与返回值都有静态类型保障。命令框架基于 Commandercommander-js/extra-typings并在preAction钩子中统一完成全局选项解析与认证注入apps/cli/src/index.tsauth与skill两个命令组被豁免认证检查。项目采用 Vite 打包为单个可执行dist/index.mjs并在 apps/cli/package.json 中声明了bin入口因此可以像普通二进制一样全局调用。八、其他客户端与注意事项官方文档还提到社区维护着一个非官方的 Python 客户端包karakeep-python-api它可以从 CLI 之外以 Python 方式访问 Karakeep API。需要特别强调该包不是官方产物使用时请自行评估其维护状态与兼容性本文所述的一切能力均以官方 CLI 为准。使用 CLI 时还有几点值得注意密钥安全auth init写入的配置文件权限为0600但如果你习惯用命令行参数传 Key注意它会出现在 shell 历史记录中生产环境建议优先使用环境变量或配置文件默认服务地址未指定--server-addr且配置文件中也没有时CLI 会连接https://cloud.karakeep.appKarakeep 官方云服务自建实例用户务必显式指定自己的服务端地址管理员命令需要权限admin组命令重爬、重建索引等仅对具备管理员角色的账号可用普通用户调用会因权限不足而失败只读操作与危险操作delete、wipe、migrate等为破坏性命令执行前请确认 Id 与目标地址无误必要时先使用dump做一次完整备份。九、结语Karakeep CLI 将 Web 端的主要能力完整投射到终端从bookmarks add的批量建书签、bookmarks search的全文/语义检索到lists/tags的组织结构管理再到dump的全量数据导出与migrate的跨实例迁移它足以支撑自动化收藏流水线与服务器运维备份两大类真实场景。配合--json输出与管道操作你可以轻松将 Karakeep 接入自己的脚本、定时任务或 AI Agent 工作流。进一步探索可阅读 docs/docs/04-using-karakeep/bookmarking.md 与 docs/docs/04-using-karakeep/search-query-language.md 了解服务端支持的数据模型与查询语法从而让 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/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Karakeep 命令行工具（CLI）完整指南：安装、认证与书签/列表/标签的脚本化操作
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面向希望绕过 Web 界面、对书签bookmark、列表list和标签tag进行更高级、可脚本化操作的用户。本文以 docs/docs/05-integrations/02-command-line.md 为骨架结合apps/cli的真实源码系统讲解 CLI 的安装方式、认证机制、完整命令体系、参数细节与底层实现原理。读完本文你将能够在终端中完成书签的增删改查、批量导入导出、列表与标签管理、数据备份迁移等全部日常运维工作。一、CLI 能做什么核心能力概览Karakeep CLI 的核心定位是面向高级用户与自动化场景的 API 交互前端。根据官方文档它主要提供两大能力操作书签、列表与标签包括书签的创建链接 / 笔记 / 图片与 PDF 等资产、查询、更新、删除、搜索列表的创建与管理标签的合并与删除等书签的批量导入 / 导出支持从 stdin 读入内容、多文件批量添加以及将账号全部数据含二进制资产打包导出为归档文件。从源码结构看CLI 的实际能力远超文档列举的范围。apps/cli/src/index.ts注册了 12 个顶层命令组命令组源码文件用途authapps/cli/src/commands/auth.ts认证配置的交互式初始化bookmarksapps/cli/src/commands/bookmarks.ts书签的增删改查、搜索、内容获取、SingleFile 导入listsapps/cli/src/commands/lists.ts列表的创建、查询、删除与成员管理tagsapps/cli/src/commands/tags.ts标签的列出、查询、合并与删除highlightsapps/cli/src/commands/highlights.ts高亮highlight的列出与删除assetsapps/cli/src/commands/assets.ts资产下载whoamiapps/cli/src/commands/whoami.ts查看 API Key 对应的用户信息dumpapps/cli/src/commands/dump.ts将账号全部数据与资产打包导出为.tar.gzmigrateapps/cli/src/commands/migrate.ts数据迁移从旧服务端批量搬运数据wipeapps/cli/src/commands/wipe.ts清空账号数据adminapps/cli/src/commands/admin.ts管理员维护操作重爬、重建索引、批量重打标签等skillapps/cli/src/commands/skill.ts输出官方 Agent Skill 内容二、安装 CLINPM、Docker 与系统包2.1 通过 NPM 全局安装CLI 以 npm 包形式发布官方包名为karakeep/cli见 apps/cli/package.json其bin字段将可执行命令映射为karakeepnpm install -g karakeep/cli安装完成后终端中直接输入karakeep即可使用。2.2 通过 Docker 运行如果你不想在宿主机安装 Node.js 环境可以使用官方发布的 CLI 镜像--rm表示容器运行完即删除docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help在 Docker 方式下每次调用都需要挂载配置或显式传入--api-key/--server-addr参数详见第三节。2.3 其他安装途径仓库文档中还提到Arch Linux 用户可通过 AUR 安装见 docs/docs/02-installation/03-archlinux.mdparu -S karakeep-cli如果你需要从源码构建可在仓库根目录执行pnpm install后进入apps/cli目录运行pnpm build构建脚本会生成dist/index.mjs并赋予可执行权限或使用pnpm run通过tsx直接运行 TypeScript 源码。三、全局选项与认证机制3.1 全局选项一览运行karakeep --help可看到完整的全局选项以下内容与源码 apps/cli/src/index.ts 中的定义一致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 所需的密钥可通过环境变量KARAKEEP_API_KEY提供--server-addr addr要连接的 Karakeep 服务端地址可通过环境变量KARAKEEP_SERVER_ADDR提供--json以 JSON 格式输出结果方便管道处理与脚本解析。在源码中这三个选项通过 Commander 的Option.env()绑定环境变量见 apps/cli/src/index.ts因此命令行参数、环境变量与配置文件三者可以混用。3.2 获取 API Key 并验证连通性要使用 CLI你需要在 Karakeep 服务端的设置页面中生成一个 API Key。拿到 Key 后可以用whoami命令验证它是否有效karakeep --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 }从源码看whoami命令内部调用的是 tRPC 的users.whoami查询apps/cli/src/commands/whoami.ts返回值即当前 API Key 所归属用户的id、name、email字段。这一步是排查密钥无效 / 服务地址不可达类问题的最快手段。3.3 配置文件把认证信息持久化为避免每次命令都输入冗长的参数CLI 支持从配置文件读取服务端地址与 API Key。配置文件默认路径遵循 XDG 规范若设置了环境变量XDG_CONFIG_HOME则读取$XDG_CONFIG_HOME/karakeep/config.json否则读取~/.config/karakeep/config.json。该逻辑实现在 apps/cli/src/lib/config.ts 的getConfigPath()中。配置文件内容格式为{ serverAddr: https://try.karakeep.app, apiKey: mysupersecretkey }配置文件的字段通过 Zod schema 校验zCliConfigFileSchema见 apps/cli/src/lib/config.tsapiKey与serverAddr均为可选的非空字符串同时允许包含其他未知字段passthrough()因此即使你往文件里额外写了自定义字段也不会导致解析失败。3.4 三种配置来源的优先级官方文档明确规定了配置的生效顺序命令行选项 环境变量 配置文件如果既没有提供服务端地址也没有在配置文件中设置CLI 默认回退到https://cloud.karakeep.app该常量定义于 apps/cli/src/lib/config.ts 的DEFAULT_SERVER_ADDR。源码中的resolveGlobalOptions()apps/cli/src/index.ts精确实现了这一逻辑先看命令行选项是否同时给出apiKey与serverAddr否则加载配置文件再按选项 → 配置文件 → 默认值逐级兜底若最终仍缺少 API Key则直接报错并提示缺失项。另外auth与skill两个命令组不需要认证其余所有命令在执行前都会自动完成全局选项解析preAction钩子apps/cli/src/index.ts。3.5 交互式初始化karakeep auth init不想手写 JSON运行karakeep auth init该命令会以交互方式提示你输入服务端地址与 API Key并把结果写入config.json源码见 apps/cli/src/commands/auth.ts。它还支持--server-addr addr/--api-key key跳过交互直接以命令行参数提供-f, --force配置文件已存在时不加确认直接覆盖若配置文件已存在且未加-f会先询问你是否更新写入文件时会自动创建目录并将文件权限设为0600仅当前用户可读写保护密钥安全。四、命令体系详解从顶层到子命令4.1 顶层命令虽然--help只列出了 6 个命令但如前文所述源码实际上注册了 12 个命令组apps/cli/src/index.ts。其中文档重点介绍的三个是bookmarks、lists、tags其余为高级/运维命令。4.2 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.tsbookmarks组实际拥有 8 个子命令下面逐一说明。创建书签bookmarks addadd支持一次创建多种类型的书签且各选项可重复指定以实现批量添加--link link添加链接书签可重复指定多个 URL--note note添加文本笔记书签可重复指定多条--asset file添加资产书签图片或 PDF传文件路径可重复指定多个文件--stdin从标准输入读取文本作为一条笔记书签保存适合echo xxx | karakeep bookmarks add --stdin这类管道用法--list-id id创建后自动将书签加入指定列表--tag-name tag创建后自动打上指定标签可重复指定多个--title title自定义书签标题默认取页面标题或内容前 50 个字符。典型用法# 添加一个链接并打标签 karakeep bookmarks add --link https://example.com --tag-name tech # 批量添加三个链接 karakeep bookmarks add --link https://a.com --link https://b.com --link https://c.com # 从 stdin 保存一条笔记 echo 购物清单牛奶、鸡蛋 | karakeep bookmarks add --stdin # 添加本地 PDF 并加入指定列表 karakeep bookmarks add --asset ./report.pdf --list-id lv2f9xxd01q74j2lu88tna从源码实现看apps/cli/src/commands/bookmarks.ts链接和笔记直接调用 tRPC 的bookmarks.createBookmark资产类书签则分两步先通过POST {serverAddr}/api/v1/assets上传文件携带Bearer认证头拿到assetId后再创建 ASSET 类型书签并按contentType自动判定资产类型application/pdf记为pdf其余记为image。所有创建请求并行执行Promise.allSettled单个失败不会影响其他书签的创建。查询单个书签bookmarks get idkarakeep bookmarks get id附加选项--include-content可在结果中包含完整书签内容。默认输出为可读格式标题、Id、类型link / text / asset资产会带assetType、URL、标签、归档/收藏状态、创建与修改时间、来源、备注、摘要等对链接书签还会显示作者、发布者、描述与爬取状态crawlStatus对文本书签会直接打印正文对带附件的书签会列出每个附件的 Id 与可访问 URL格式为{serverAddr}/api/assets/{assetId}。加--json后输出规范化的 JSON标签会被拍平为名称数组见normalizeBookmark。更新书签bookmarks update idkarakeep bookmarks update id [options]支持的更新选项--title title更新标题--note note更新备注--archive/--no-archive归档 / 取消归档--favourite/--no-favourite收藏 / 取消收藏--description description更新描述。更新通过 tRPC 的bookmarks.updateBookmark完成apps/cli/src/commands/bookmarks.ts。单独调整标签bookmarks update-tags idkarakeep bookmarks update-tags id --add-tag ai --remove-tag old-tag--add-tag与--remove-tag均可重复指定内部调用bookmarks.updateTags一次性完成挂载attach与摘除detach操作。列出书签bookmarks listkarakeep bookmarks list [options]--include-archived默认只列出未归档书签加此参数后同时包含已归档项--list-id id只列出指定列表内的书签--tag-id id只列出带指定标签的书签--feed-id id只列出来自指定 RSS Feed 的书签--include-content结果中包含完整内容--limit limit每页数量默认 20上限由MAX_NUM_BOOKMARKS_PER_PAGE决定超出会自动截断--all自动翻页拉取全部书签--cursor cursor使用上一次返回的游标继续分页。分页游标在 CLI 内部以 Base64 编码传递源码中Buffer.from(JSON.stringify(resp.nextCursor)).toString(base64)翻页时把上次输出的Next cursor: ...原样传回即可。搜索书签bookmarks search querykarakeep bookmarks search tag:ai is:fav [options]搜索查询支持 Karakeep 的查询匹配器语法如tag:name、is:fav等详见 docs/docs/04-using-karakeep/search-query-language.md。可用选项--limit limit结果条数默认 50--sort-order order排序方式可选relevance默认/asc/desc--search-mode mode搜索模式可选fts全文搜索默认/semantic语义搜索/hybrid混合--include-content结果包含完整内容--all拉取全部结果--cursor cursor分页游标。参数校验在源码中均做了严格限制apps/cli/src/commands/bookmarks.ts非法值会直接报错。获取可读内容bookmarks content id对于需要把书签正文交给其他工具如 LLM的场景content命令可以按块获取可读内容--format format内容格式markdown或text--max-chars count本次获取的最大 Unicode 字符数上限MAX_READABLE_CONTENT_MAX_CHARS--cursor cursor续读游标。响应中包含range本次返回的起止位置与总量与nextCursor字段非 JSON 模式下 CLI 会把正文直接写到 stdout并在末尾提示下一次的游标值适合做流式拼接。导入 SingleFile 归档bookmarks import-singlefile将 SingleFile 保存的完整 HTML 归档导入为链接书签karakeep bookmarks import-singlefile file --url original-url [--if-exists skip]--url url必填被归档页面的原始 URL--if-exists mode当同 URL 书签已存在时的处理策略可选skip默认、overwrite、overwrite-recrawl、append、append-recrawl。该命令走的是独立的上传端点POST {serverAddr}/api/v1/bookmarks/singlefile?ifexistsmodeapps/cli/src/commands/bookmarks.ts是迁移浏览器本地归档内容的高效通道。删除书签bookmarks delete idkarakeep bookmarks delete id删除成功会输出Success: Bookmark with id xxx got deleted。4.3 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实际子命令如下list以表格形式列出全部列表Id、名称、描述、书签数嵌套列表会按路径层级展开借助karakeep/shared的listsToTree/listNameFromPath工具get id查看单个列表详情名称、类型、描述、查询、父列表、是否公开、用户角色、是否有协作者create创建列表参数包括必填的--name name与--icon icon一个 emoji 图标、可选的--type typemanual或smart默认manual、--description、--query智能列表的搜索查询智能列表必填、--parent-id父列表用于构建嵌套结构delete id删除列表add-bookmark --list id --bookmark id把书签加入列表remove-bookmark --list id --bookmark id把书签从列表移除。另外在bookmarks add时使用--list-id参数内部会复用同一套addToList逻辑apps/cli/src/commands/lists.ts。4.4 tags标签操作karakeep tags实际子命令apps/cli/src/commands/tags.tslist以表格列出所有标签Id、名称、书签数默认按书签数降序排列get [id]或get --name name按 Id 或名称查询单个标签输出书签总数以及人工标记 / AI 标记的数量拆分numBookmarksByAttachedType这正是 Karakeep AI 自动打标能力在 CLI 侧的呈现merge --into id --from ids...把多个标签合并进目标标签--from传多个空格分隔的标签 Id适合整理冗余标签delete id删除标签。4.5 其他命令whoami返回 API Key 所属用户信息见 3.2 节highlights list [--bookmark id] [--limit n] [--all] [--cursor c]、highlights get id、highlights delete id管理书签高亮源码 apps/cli/src/commands/highlights.tsassets download id [--output path]下载指定资产文件源码 apps/cli/src/commands/assets.tsdump [--output file] [--exclude-*]把账号全部数据打包为.tar.gz详见第五节migrate在服务端之间批量迁移书签/列表/标签等数据源码 apps/cli/src/commands/migrate.tswipe清空账号数据危险操作源码 apps/cli/src/commands/wipe.tsadmin管理员维护命令包括对单个书签的debug/recrawl/reindex/regenerate-embedding/retag/resummarize以及全库范围的recrawl-links/reindex-all/retag-all/resummarize-all/regenerate-embeddings/reprocess-assets和作业统计jobs stats、订阅同步subscriptions sync等源码 apps/cli/src/commands/admin.tsskill直接把官方 Karakeep Agent Skillskills/SKILL.md打印到 stdout方便 AI Agent 读取源码 apps/cli/src/commands/skill.ts。五、数据导出与迁移dump命令实战dump是 CLI 中最具实用价值的运维命令之一它能把账号下的所有数据连同二进制资产一并打包成一个归档文件源码 apps/cli/src/commands/dump.tskarakeep dump --output ./backup-$(date %F).tar.gz归档内结构清晰manifest.json格式标记karakeep.dump、版本号、导出时间、服务端地址、用户信息与各类数据计数、users/settings.json、lists/index.json与lists/membership.json、tags/index.json、rules/index.json、feeds/index.json、prompts/index.json、webhooks/index.json、bookmarks/index.jsonlJSON Lines 流式写入适合大库、assets/index.json与assets/files/资产二进制文件。dump支持按需裁剪的排除参数用于只备份部分数据或跳过体积较大的二进制资产--exclude-assets跳过资产含索引与文件--exclude-bookmarks跳过书签元数据/内容--exclude-lists跳过列表及成员关系--exclude-tags跳过标签--exclude-ai-prompts跳过 AI 提示词--exclude-rules跳过规则引擎规则--exclude-feeds跳过 RSS Feed--exclude-webhooks跳过 Webhook--exclude-user-settings跳过用户设置--exclude-link-content跳过链接正文内容仅保留元数据可显著缩小体积--batch-size n分页拉取书签时的每页数量上限MAX_NUM_BOOKMARKS_PER_PAGE默认 50。执行过程中会实时显示每类数据的导出进度书签、列表扫描、资产下载均带进度指示最终调用系统tar打包。该命令与 Web 端的数据导出备份能力互为补充是服务器迁移可配合 docs/docs/06-administration/06-server-migration.md和定期异地备份的推荐手段。六、输出格式化人类可读与 JSON 自由切换所有命令都支持全局的--json标志。以bookmarks list为例默认输出是带颜色高亮的人类可读卡片标题、Id、类型、创建时间、URL、标签、归档/收藏状态、备注等加上--json后则输出规范化的 JSON 结构其中标签从对象数组被拍平为字符串数组便于jq等工具进一步处理。输出层的实现集中在 apps/cli/src/lib/output.tsprintObject根据--json标志决定调用JSON.stringify缩进 4 空格还是 Node 的console.dirprintStatusMessage/printSuccess/printError则统一输出Success: .../Error: ...形式的状态行成功绿色、失败红色。这意味着 CLI 既适合人眼阅读也能无缝接入 shell 脚本与自动化流水线。七、底层实现解析CLI 如何与 Karakeep API 通信理解 CLI 的通信机制有助于排查连接问题也有助于开发自己的脚本。关键实现在 apps/cli/src/lib/trpc.tsCLI 使用tRPC 客户端与 Karakeep 服务端通信连接地址为{serverAddr}/api/trpc通过httpBatchLink批量发送请求可减少 HTTP 往返次数并使用superjson作为序列化器这也是为什么日期等复杂类型能正确往返每个请求自动附带Authorization: Bearer {apiKey}请求头这就是 API Key 的传递方式tRPC 的AppRouter类型直接复用karakeep/trpc包packages/trpc/routers因此 CLI 与 Web 前端共享同一套类型安全的路由定义命令参数与返回值都有静态类型保障。命令框架基于 Commandercommander-js/extra-typings并在preAction钩子中统一完成全局选项解析与认证注入apps/cli/src/index.tsauth与skill两个命令组被豁免认证检查。项目采用 Vite 打包为单个可执行dist/index.mjs并在 apps/cli/package.json 中声明了bin入口因此可以像普通二进制一样全局调用。八、其他客户端与注意事项官方文档还提到社区维护着一个非官方的 Python 客户端包karakeep-python-api它可以从 CLI 之外以 Python 方式访问 Karakeep API。需要特别强调该包不是官方产物使用时请自行评估其维护状态与兼容性本文所述的一切能力均以官方 CLI 为准。使用 CLI 时还有几点值得注意密钥安全auth init写入的配置文件权限为0600但如果你习惯用命令行参数传 Key注意它会出现在 shell 历史记录中生产环境建议优先使用环境变量或配置文件默认服务地址未指定--server-addr且配置文件中也没有时CLI 会连接https://cloud.karakeep.appKarakeep 官方云服务自建实例用户务必显式指定自己的服务端地址管理员命令需要权限admin组命令重爬、重建索引等仅对具备管理员角色的账号可用普通用户调用会因权限不足而失败只读操作与危险操作delete、wipe、migrate等为破坏性命令执行前请确认 Id 与目标地址无误必要时先使用dump做一次完整备份。九、结语Karakeep CLI 将 Web 端的主要能力完整投射到终端从bookmarks add的批量建书签、bookmarks search的全文/语义检索到lists/tags的组织结构管理再到dump的全量数据导出与migrate的跨实例迁移它足以支撑自动化收藏流水线与服务器运维备份两大类真实场景。配合--json输出与管道操作你可以轻松将 Karakeep 接入自己的脚本、定时任务或 AI Agent 工作流。进一步探索可阅读 docs/docs/04-using-karakeep/bookmarking.md 与 docs/docs/04-using-karakeep/search-query-language.md 了解服务端支持的数据模型与查询语法从而让 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/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考