clickup-cli 是一个用于调用 ClickUp API 的命令行工具，专为 AI 智能体和人类用户设计，覆盖约 130 个端点、28 个资源组和 4 个实用命令。
用途 ClickUp API 的响应体积巨大，例如仅查询 5 个任务就可能返回超过 12,000 token 的深层嵌套 JSON（状态、指派人、优先级、自定义字段、检查项、依赖关系等）。对于在上下文窗口内运行的 AI 智能体来说，少数几次 API 调用就可能耗尽大部分可用上下文。clickup-cli 通过默认的 token 高效输出解决这一问题：它会扁平化嵌套对象、只选取必要字段并渲染紧凑表格；需要完整响应时可使用 --output json。该工具还提供简单可预测的接口：clickup-cli <resource> <action> [ID] [flags]，无需 SDK、认证样板代码或 JSON 解析。
主要能力
- 默认 token 高效输出，同时保留 --output json 完整输出选项。
- 从 git 分支自动识别任务 ID：ClickUp 默认 ID（如 feat/CU-abc123-foo → abc123），自定义任务 ID（如 PROJ-42-add-login → PROJ-42，自动注入 custom_task_ids=true&team_id=<ws>）。可剥离的前缀包括 feature/、feat/、fix/、hotfix/、bugfix/、release/、chore/、docs/、refactor/、test/、ci/、perf/、build/、style/ 等。破坏性或含糊的命令（task delete、task link、task unlink、guest share-task、guest unshare-task）不会自动识别，必须显式传入 ID。可通过 CLICKUP_GIT_DETECT=0 禁用一次调用，或在配置中永久禁用。
- 提供 CLI 模式（推荐）和 MCP 服务器模式两种 AI 智能体集成方式。CLI 模式注入命令参考约消耗 1,000 token，每命令返回约 150 token（5 个任务）的紧凑表格输出，无工具 schema 消耗上下文，适用于任何 LLM/智能体框架；自动检测现有文件（CLAUDE.md、agent.md、AGENT.md、.cursorrules、.github/copilot-instructions.md），若无则创建 CLAUDE.md。MCP 模式面向 Claude Desktop、Cursor 等偏好原生工具集成的工具，可自动生成 MCP 配置或手动添加 .mcp.json，暴露 144 个工具覆盖 100% ClickUp API，但工具 schema 消耗的 token 多于 CLI 参考方式。
- MCP 工具可限制：默认暴露全部 144 个工具，可启动时通过 --read-only、任务聚焦（仅 task + comment + time 组）等标志与环境变量限制，过滤后的工具在 tools/list 中隐藏且在 tools/call 中被拒绝。
- OAuth 支持自带应用：可设置 CLICKUP_OAUTH_CLIENT_ID 和 CLICKUP_OAUTH_CLIENT_SECRET（或 --client-id / --client-secret），需注册精确重定向地址 http://127.0.0.1:53682/callback（--redirect-port 可改端口）。支持 --no-browser、--keyring、auth status、auth logout。不随附维护者密钥或代理。实时回环验收与 token 响应验证尚待完成。
- 令牌解析优先级：--token CLI 标志（默认个人，--token-kind oauth 选择 OAuth）→ CLICKUP_TOKEN 环境变量（个人）→ CLICKUP_OAUTH_TOKEN 环境变量（OAuth）→ 最近祖先 .clickup.toml → 操作系统全局配置（Linux 下 ~/.config/clickup-cli/config.toml）。[auth] kind = "oauth" 选择 OAuth，省略则默认个人。默认文件存储，storage = "keychain" 显式选择系统钥匙串且不可用时失败。个人令牌发送 Authorization: <token>；OAuth 令牌发送 Authorization: Bearer <token>，包括上传和 MCP。CLICKUP_CONFIG 可指定单一配置路径并禁用发现。
- 工作区解析优先级：--workspace CLI 标志 → CLICKUP_WORKSPACE 环境变量 → 项目级 .clickup.toml → 全局 ~/.config/clickup-cli/config.toml。
使用方式 安装方式包括：npm（任意有 Node.js 的平台）、Homebrew（macOS 或 Linux，Linux 也有原生 x86_64 和 arm64 二进制）、macOS/Linux 预编译二进制、Alpine/musl Linux、Arch Linux（AUR 的 clickup-cli-bin，无需 Rust 工具链）、Windows（下载 clickup-windows-x86_64.zip 解压并将 clickup-cli.exe、可选 clkup.exe 加入 PATH）、crates.io（需 Rust 1.70+）。每种安装方式都提供两个行为相同的二进制：clickup-cli（规范名称，用于脚本、CI、MCP 配置）和 clkup（短别名）。可验证安装、创建项目级配置（生成 .clickup.toml，若含令牌应加入 .gitignore，项目配置优先于全局配置）、使用 shell 补全与查看当前配置。
适用场景 需要为 AI 智能体或脚本提供 ClickUp API 访问、希望大幅降低 token 消耗、或需要同时覆盖 CLI 与 MCP 角色而不依赖 Node/Python 工具链的用户。
限制 仓库资料中未提供具体价格与收费信息；OAuth 的实时回环验收和令牌响应验证尚待完成；破坏性命令不自动识别任务 ID。社区中另有其他 ClickUp 相关工具，可按用例选择。
