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/hoarder

本指南围绕 docs/versioned_docs/version-v0.28.0/09-command-line.md 展开，系统讲解 Karakeep（自托管书签管理应用）官方 CLI 的安装、认证配置与全部子命令。读完本文，你将能够通过终端完成书签的增删改查、批量导入导出、列表与标签的维护，以及基于 API Key 的脚本化自动化操作，并结合 apps/cli 源码理解每个命令背后的实现机制。

什么是 Karakeep CLI

Karakeep 提供了一个简洁的命令行界面（CLI），面向希望进行更高级操作的用户，核心定位是“一切皆可书签”（链接、笔记与图片）场景下的批量与自动化管理。其能力集中在两个方面：

操纵书签、列表（Lists）与标签（Tags）：增删改查、归档、收藏、打标签、加入列表等；
书签的批量导入与导出：既支持逐条命令行添加，也支持从 stdin 读取文本、上传本地图片/PDF 资产，以及导入 SingleFile 归档。

CLI 本质上是 Karakeep 服务端 API 的一个终端封装。从 apps/cli/src/index.ts 可以看到，整个程序基于commander构建，所有子命令最终都通过 tRPC 客户端（getAPIClient()）或直接调用 REST 接口（如资产上传/api/v1/assets）与服务器交互。

安装 CLI

CLI 包发布在 npm 上，包名为@karakeep/cli（见 apps/cli/package.json，其 bin 入口为karakeep），也提供了官方 Docker 镜像。

通过 NPM 安装

需要 Node.js 环境，执行全局安装：

npm install -g @karakeep/cli

安装完成后即可在任意目录使用karakeep命令。

通过 Docker 使用

无需安装 Node.js，直接以一次性容器运行，这里以查看帮助为例：

docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help

--rm表示容器退出后自动删除，适合临时执行命令的场景。

全局选项与环境变量

运行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 使用的密钥，也可通过环境变量KARAKEEP_API_KEY提供；
--server-addr <addr>：要连接的 Karakeep 服务器地址，也可通过环境变量KARAKEEP_SERVER_ADDR提供；
--json：以 JSON 格式输出结果，便于脚本解析（该选项在 apps/cli/src/index.ts 中通过new Option("--json", "to output the result as JSON")注册）。

从源码看，环境变量映射在 apps/cli/src/index.ts 中通过 commander 的.env()方法声明；程序还会在preAction钩子中统一解析全局选项，并跳过不需要认证的auth、skill子命令。若最终解析不到 API Key，会直接报错提示通过命令行、环境变量或配置文件提供（apps/cli/src/index.ts）。

获取 API Key 与认证配置

第一步：从设置中获取 API Key

使用 CLI 前，需要登录 Karakeep Web 界面，在个人设置（Settings）中生成 API 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: 'test@gmail.com' }

返回的是该 API Key 归属用户的 id、name 与 email。whoami在 apps/cli/src/commands/whoami.ts 中实现，调用的是 tRPC 的users.whoami查询。

第二步：持久化配置到配置文件

每次携带--api-key与--server-addr比较繁琐，CLI 支持将配置写入配置文件：

若设置了$XDG_CONFIG_HOME，读取$XDG_CONFIG_HOME/karakeep/config.json；
否则读取~/.config/karakeep/config.json。

配置文件格式：

{ "serverAddr": "https://try.karakeep.app", "apiKey": "mysupersecretkey" }

配置路径与默认地址定义在 apps/cli/src/lib/config.ts：默认服务器地址为https://cloud.karakeep.app，getConfigPath()优先使用XDG_CONFIG_HOME，否则回退到用户主目录下的.config。

三种配置来源的优先级

CLI 的解析顺序遵循如下规则（见 apps/cli/src/index.ts 的resolveGlobalOptions）：

命令行选项优先级最高：显式传入的--api-key/--server-addr直接生效；
环境变量次之：KARAKEEP_API_KEY/KARAKEEP_SERVER_ADDR；
配置文件兜底：config.json中的apiKey/serverAddr；
最终默认值：若仍未提供服务器地址，默认连接https://cloud.karakeep.app；若缺少 API Key，则报错退出。

交互式初始化：`karakeep auth init`

不想手写 JSON 配置文件时，可运行：

karakeep auth init

它会以交互方式询问服务器地址与 API Key（已有配置时显示中括号默认值，直接回车沿用），并将结果以0600权限写入配置文件；若配置文件已存在，会询问是否覆盖，也可用-f, --force直接覆盖（实现见 apps/cli/src/commands/auth.ts）。还支持非交互传参：

karakeep auth init --server-addr https://try.karakeep.app --api-key mysupersecretkey

书签（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等扩展命令，以下逐一说明。

添加书签：`bookmarks add`

支持三种类型：链接（link）、文本笔记（note/text）、资产文件（asset，图片或 PDF），且可一次添加多个：

# 添加一个链接书签 karakeep bookmarks add --link "https://example.com/article" # 添加多个链接与多条笔记 karakeep bookmarks add --link "https://a.com" --link "https://b.com" --note "我的第一条笔记" --note "第二条笔记" # 上传本地图片/PDF 作为资产书签 karakeep bookmarks add --asset ./screenshot.png --asset ./report.pdf # 从 stdin 读取内容存为笔记 cat note.txt | karakeep bookmarks add --stdin # 添加书签的同时打标签、归入列表并自定义标题 karakeep bookmarks add --link "https://example.com" --tag-name "tech" --tag-name "must-read" --list-id <list-id> --title "我的标题"

对应参数说明（源自 apps/cli/src/commands/bookmarks.ts）：

参数	作用
`--link <link>`	要添加的链接，可多次指定
`--note <note>`	要添加的笔记文本，可多次指定
`--asset <file>`	本地资产文件路径（图片或 PDF），可多次指定
`--stdin`	从 stdin 读取数据存为笔记
`--list-id <id>`	将新书签加入指定列表
`--tag-name <tag>`	为新书签添加标签，可多次指定
`--title <title>`	覆盖书签标题

实现细节：链接与笔记通过 tRPC 的bookmarks.createBookmark创建（source: "cli"会被记录）；资产书签先通过 REST 接口POST {serverAddr}/api/v1/assets上传文件，再依据返回的contentType判断pdf或image类型创建书签；--stdin通过fs.readFileSync(0, "utf-8")读取标准输入。

查询单个书签：`bookmarks get`

karakeep bookmarks get <id> karakeep bookmarks get <id> --include-content # 额外返回完整内容

输出包含标题、Id、类型（link/text/asset）、URL、标签、归档/收藏状态、创建修改时间，链接类书签还会显示作者、发布者、抓取状态（crawlStatus）等。

更新书签：`bookmarks update`

karakeep bookmarks update <id> --title "新标题" karakeep bookmarks update <id> --note "补充一条笔记" karakeep bookmarks update <id> --archive # 归档 karakeep bookmarks update <id> --no-archive # 取消归档 karakeep bookmarks update <id> --favourite # 收藏 karakeep bookmarks update <id> --no-favourite # 取消收藏 karakeep bookmarks update <id> --description "新的描述"

管理标签：`bookmarks update-tags`

karakeep bookmarks update-tags <id> --add-tag tech --add-tag ai karakeep bookmarks update-tags <id> --remove-tag ai

底层调用bookmarks.updateTags，将添加与移除的标签名列表同时提交给服务端。

列出书签：`bookmarks list`

# 列出默认（未归档）书签，每页 20 条 karakeep bookmarks list # 包含已归档书签 karakeep bookmarks list --include-archived # 按列表 / 标签 / RSS 源过滤 karakeep bookmarks list --list-id <id> karakeep bookmarks list --tag-id <id> karakeep bookmarks list --feed-id <id> # 控制分页：每页数量、翻页游标、或一次拉取全部 karakeep bookmarks list --limit 50 karakeep bookmarks list --cursor <cursor> karakeep bookmarks list --all

分页上限为MAX_NUM_BOOKMARKS_PER_PAGE（定义于 packages/shared/types/bookmarks.ts），--limit会被截断到该上限；使用--all时 CLI 会自动循环请求直到nextCursor为空；非 JSON 模式下列表末尾会打印Next cursor: ...供继续翻页。

搜索书签：`bookmarks search`

# 基础全文搜索 karakeep bookmarks search "machine learning" # 使用查询匹配器（如 tag:、is: 等） karakeep bookmarks search "tag:tech is:fav" # 排序与搜索模式 karakeep bookmarks search "rust" --sort-order relevance # relevance | asc | desc karakeep bookmarks search "rust" --search-mode fts # fts | semantic | hybrid karakeep bookmarks search "rust" --limit 50 --all

--sort-order可选relevance、asc、desc（默认relevance）；--search-mode可选fts（全文检索）、semantic（语义检索）、hybrid（混合），默认fts。搜索查询语言的具体匹配器可参考 docs/docs/04-using-karakeep/search-query-language.md。

删除书签：`bookmarks delete`

karakeep bookmarks delete <id>

读取可读内容：`bookmarks content`

以受限分块方式获取书签的可读正文，适合把正文交给其他工具处理：

karakeep bookmarks content <id> --format markdown karakeep bookmarks content <id> --format text --max-chars 10000 karakeep bookmarks content <id> --cursor <cursor> # 续传

--format限markdown或text；--max-chars为 1 到MAX_READABLE_CONTENT_MAX_CHARS之间的整数；响应含nextCursor时表示还有更多内容。

导入 SingleFile 归档：`bookmarks import-singlefile`

将 SingleFile 保存的 HTML 归档作为链接书签导入（需要--url指定原网页地址）：

karakeep bookmarks import-singlefile ./article.html --url "https://example.com/article" # 处理已存在同 URL 书签的情况 karakeep bookmarks import-singlefile ./article.html --url "https://example.com/article" --if-exists overwrite

--if-exists可选值：skip（默认，跳过）、overwrite、overwrite-recrawl、append、append-recrawl，取值校验见 apps/cli/src/commands/bookmarks.ts。实现上会以multipart/form-data将 HTML 文件与 URL 提交到POST /api/v1/bookmarks/singlefile。

列表（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 # 创建列表（manual 手动列表 或 smart 智能列表） karakeep lists create --name "深度学习" --icon "🧠" --type manual --description "我的收藏" karakeep lists create --name "AI 动态" --icon "🤖" --type smart --query "tag:ai is:unread" # 创建子列表 karakeep lists create --name "子列表" --icon "📁" --parent-id <parent-id> # 查看列表详情（含类型、查询条件、公开状态、协作信息） karakeep lists get <id> # 将书签加入/移出列表 karakeep lists add-bookmark --list <list-id> --bookmark <bookmark-id> karakeep lists remove-bookmark --list <list-id> --bookmark <bookmark-id> # 删除列表 karakeep lists delete <id>

其中list输出使用树形工具将列表层级（listsToTree，来自 packages/shared/utils/listUtils.ts）拼装成表格，包含 Id、Name、Description、Bookmarks 四列；create中--type默认manual，智能列表需要--query定义动态筛选条件。

标签（tags）子命令

# 表格列出全部标签（按书签数量降序） karakeep tags list # 按 id 或名称查询标签详情 karakeep tags get <id> karakeep tags get --name "tech" # 合并标签：把多个来源标签合并进目标标签 karakeep tags merge --into <target-tag-id> --from <source-tag-id-1> <source-tag-id-2> # 删除标签 karakeep tags delete <id>

tags get支持--name按名称精确匹配（实现见 apps/cli/src/commands/tags.ts），详情输出会显示书签数量以及按“人工打标 / AI 自动打标”拆分的统计；tags merge对于整理重复标签非常实用。

更多命令：备份、迁移与运维

当前源码 apps/cli/src/index.ts 注册的子命令还包括：

命令	用途
`auth`	认证配置管理（`auth init`交互式初始化）
`admin`	管理员维护命令，如`list`、`debug`、`recrawl`、`reindex`、`regenerate-embedding`、`retag`、`resummarize`、`stats`及对应的`-all`批量版本、`reprocess-assets`等（apps/cli/src/commands/admin.ts）
`assets`	资产下载（`assets download`，apps/cli/src/commands/assets.ts）
`highlights`	高亮管理：`list`/`get`/`delete`（apps/cli/src/commands/highlights.ts）
`dump`	将账户全部数据与资产导出为归档（默认`.tar.gz`，支持`--exclude-*`排除书签、列表、标签、AI Prompts、规则、RSS 源、Webhook 等，见 apps/cli/src/commands/dump.ts）
`migrate`	将数据从源服务器迁移到目标服务器（apps/cli/src/commands/migrate.ts）
`wipe`	清空当前用户在服务器上的全部数据，需`-y, --yes`确认，支持`--exclude-*`保留部分数据类型（apps/cli/src/commands/wipe.ts）
`skill`	输出官方 Karakeep Agent Skill（供 AI Agent 使用）

注意：wipe、dump、migrate、admin等属于高风险或管理类命令，执行前请确认目标服务器与账户，必要时先备份。

JSON 输出与脚本化

所有支持输出结构的命令均可叠加全局--json，将结果以 JSON 形式打印，便于与jq等工具组合实现自动化：

# 列出全部书签并提取 id 与标题 karakeep --json bookmarks list --all | jq '.bookmarks[] | {id, title}' # 搜索并以 JSON 输出 karakeep --json bookmarks search "rust" --search-mode semantic # 获取列表 JSON（含层级） karakeep --json lists list # 获取标签 JSON karakeep --json tags list

典型自动化场景示例：

# 从文件批量添加链接书签并打上统一标签 while read -r url; do karakeep bookmarks add --link "$url" --tag-name "batch-import" done < urls.txt # 将导出的书签 JSON 批量归档 karakeep --json bookmarks list --all | jq -r '.bookmarks[].id' | while read -r id; do karakeep bookmarks update "$id" --archive done

其他客户端

社区还维护了一个非官方的 Python 包karakeep-python-api，可从命令行访问 Karakeep API，但它不属于官方支持范围（官方文档中明确标注为 non-official、community-maintained）。追求稳定与完整能力时，优先使用官方 CLI。

小结

Karakeep CLI 把 Web 界面中的高频管理操作完整暴露到了终端：通过--api-key/--server-addr/ 环境变量 /config.json四层配置来源灵活接入，auth init简化认证初始化，bookmarks、lists、tags三大命令族覆盖日常增删改查与批量导入导出，而dump、migrate、wipe、admin等命令进一步支撑备份、迁移与运维场景。配合--json输出与 tRPC/REST 的实现架构（参见 apps/cli/src/index.ts 与 apps/cli/src/commands 目录），你可以轻松将 Karakeep 纳入自己的脚本与自动化工作流。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析