clinkding

用途

clinkding 是 linkding（一个自托管书签管理器，类似 Pocket、Instapaper）的命令行管理工具，使用 Go 编写。它让用户可以从终端或通过 AI 智能体管理个人书签集合：保存稍后阅读的网址、全文搜索书签库、用标签和捆绑包组织收藏、保留带备注和元数据的个人链接归档。

主要能力

书签管理

列出与搜索书签：支持关键词搜索、按标签过滤（如 tag:programming）、按添加时间过滤（如 --added-since "7d"）、筛选未读（unread:yes）。
创建书签：可指定标题、标签、描述，并标记为未读；创建前可用 bookmarks check 检查 URL 是否已存在。
更新书签：修改标题、添加或移除标签、标记为已读、更新描述。
查看详情：获取单个书签的完整信息。
归档与删除：归档/取消归档、永久删除。

标签管理

列出全部标签、创建标签、查看标签详情。

捆绑包（Bundles）

捆绑包是相关书签的集合，支持列出、创建、更新、查看详情和删除。

附件（Assets）

为书签上传、列出、下载和删除文件附件。

用户信息

获取用户个人资料信息。

输出格式

auto（默认）：终端友好的表格与颜色。
--json：机器可读，便于脚本和智能体解析。
--plain：制表符分隔的纯文本，便于管道处理。

相对时间过滤

支持人类友好的时间范围，单位包括 h（小时）、d（天）、y（年），例如 24h、7d、180d。

使用方式

安装

Homebrew（macOS/Linux）：

brew install daveonkels/tap/clinkding

Go 安装：

go install github.com/daveonkels/clinkding@latest

也可从 releases 下载对应平台的二进制文件。

初始配置

交互式配置：

clinkding config init

或手动配置：

clinkding config set url https://your-linkding-instance.com
clinkding config set token YOUR_API_TOKEN
clinkding config test

配置文件位置：~/.config/clinkding/config.yaml，包含 url、token 以及 defaults（如 bookmark_limit: 100、output_format: auto）。

也可使用环境变量：

export LINKDING_URL="https://linkding.example.com"
export LINKDING_TOKEN="your-api-token-here"

常用命令示例

列出最近书签：

clinkding bookmarks list

带元数据创建书签：

clinkding bookmarks create https://go.dev \
  --title "Go Programming Language" \
  --tags "golang,programming,reference" \
  --description "Official Go website" \
  --unread

为书签添加标签：

clinkding bookmarks update 42 --add-tags "important,work"

创建捆绑包：

clinkding bundles create "Go Resources" \
  --description "Everything related to Go programming"

上传附件：

clinkding assets upload 42 ~/Documents/screenshot.png

全局标志

所有命令均支持：-c, --config <file>、-u, --url <url>、-t, --token <token>、--json、--plain、--no-color、-q, --quiet、-v, --verbose。

退出码

0 成功；1 通用错误（API/网络）；2 用法错误（标志/参数无效）；3 认证错误；4 未找到；130 中断（Ctrl-C）。

Shell 补全

提供 bash、zsh、fish 的补全命令，例如：

clinkding completion bash > /etc/bash_completion.d/clinkding

适用场景

从对话中保存网址，并附带标题、描述和标签。
搜索书签（如按关键词、标签、未读状态），检索待读内容。
整理与打标签，创建主题捆绑包。
批量操作：为多个书签打标签、归档旧书签。
备份书签：导出为 JSON。
通过 AI 智能体工作流：先获取页面元数据（如使用 summarize 技能），再推断标签并创建书签。

限制与注意事项

需要已部署的 linkding 实例，并配置有效的实例 URL 与 API Token。
认证问题排查：核对 linkding 网页界面中的 API Token、确认 URL 包含协议（https://）、移除 URL 末尾斜杠。
帮助信息可通过 clinkding bookmarks --help 等查看。
项目许可证为 MIT。