pp-clickup

ClickUp — Printing Press CLI

前置条件：安装 CLI

此技能由 clickup-pp-cli 二进制文件驱动。调用此技能中的任何命令前，必须确认 CLI 已安装。 如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，则安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install clickup --cli-only
   

2. 验证：clickup-pp-cli --version
3. 确保显示的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、离线等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。此方式会将程序安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请改为将该目录添加到 $PATH 中：

go install github.com/mvanhorn/printing-press-library/library/project-management/clickup/cmd/clickup-pp-cli@latest

如果安装后 --version 报告“command not found”，则运行时无法在 $PATH 中找到二进制文件目录。在验证成功前，请勿继续执行此技能中的命令。

v2 参考文档涵盖 172 个端点（Tasks、Spaces、Folders、Lists、Goals、Time Tracking、Webhooks、Comments、Custom Fields、Members、Templates、Views），v3 公共 API 则涵盖 Chat、Docs、Audit Logs 和 ACLs。层级同步会遍历整个工作区树，并将数据写入本地 SQLite，以便离线搜索和分析。顶层的 docs 和 chat 命令提供符合惯例的动词，无需记忆 workspaces/-public 规范路径。

何时使用此 CLI

当你需要针对 ClickUp v2 + v3 的完整 API 编写脚本、将整个工作区层级的数据填充到本地 SQLite 存储以供离线分析，或将 ClickUp 作为 MCP 服务提供给 Agent 时，请使用 clickup-pp-cli。它尤其适用于时间跟踪汇总、冲刺报告，以及 Web UI 未提供的批量任务操作。

独特功能

这些功能是此 API 的其他工具所不具备的。

可累积的本地状态

• sync — 按依赖顺序遍历完整的 ClickUp 层级（teams → spaces → folders → lists → tasks；teams → docs；teams → channels），并将每条记录写入本地 SQLite 存储。API 中的每一种父子关系都会自动遍历。

  当你需要对 ClickUp 工作区的完整结构进行离线搜索、分析或复合查询时，请使用此功能。只需一条命令即可填充整棵树。

  clickup-pp-cli sync --json --profile default
  

• sync — 区分“已识别但数组为空的响应封装”与“无法识别的响应结构”，因此资源类型记录数为零的租户也能顺利同步，而不会崩溃。对于没有 space 的工作区，ClickUp 会返回 {"spaces":[]}；原始框架将其视为单条响应，并尝试将封装对象作为单条记录写入，结果因“missing id for space”而失败。

  否则，对于资源集合为空的任何工作区，同步都会静默失败，导致本地存储仅部分填充。

  clickup-pp-cli sync --resources space --profile default --json
  

面向 Agent 的基础设施

• docs — 提供顶层 docs 和 chat 命令，使用符合习惯的动词（search、get、pages、page、listing、create、edit、send、react、reply、members、followers、messages），取代从规范派生的 workspaces/docs/<verb>-public 和 workspaces/chat/get-channels 路径。总计约 22 个别名。原有动词保留为 Cobra 别名，以实现向后兼容。

  可直接使用 docs search、chat list、chat send，无需记住层级很深的 workspaces 命令树。尤其适合编写脚本调用 v3 端点。

  clickup-pp-cli docs search 9017321407 --json --profile default
  

• task attach — 以真正的 multipart/form-data 格式将一个或多个本地文件上传到任务（每个文件发送一个 POST 请求，部件字段为 attachment，并使用各文件对应的 MIME 类型）。支持通过 --custom-task-ids --team-id 指定自定义任务 ID；发送前会验证每个文件，且 --dry-run 可预览上传内容而不实际发送。

  当 Agent 需要将本地文件（报告、屏幕截图、导出文件）附加到 ClickUp 任务时，可使用此命令。

  clickup-pp-cli task attach abc123xyz ./report.pdf --dry-run --json
  

• task attachments — 从 GET /v2/task/{id} 获取任务附件，并以行的形式列出（id、title、extension、size、url、total_comments、resolved_comments、open_comments），支持自定义任务 ID。

  可使用此命令查看哪些已附加文档仍有未解决的审阅评论。

  clickup-pp-cli task attachments abc123xyz --json
  

命令参考

checklist — 管理清单

• clickup-pp-cli checklist delete — 从任务中删除清单。
• clickup-pp-cli checklist edit — 重命名任务清单，或调整清单顺序，使其显示在任务中其他清单的上方或下方。

comment — 管理评论

• clickup-pp-cli comment delete — 删除任务评论。
• clickup-pp-cli comment update — 替换任务评论的内容、分配评论，并将评论标记为已解决。

folder — 管理文件夹

• clickup-pp-cli folder delete — 从工作区中删除文件夹。
• clickup-pp-cli folder get — 查看文件夹中的列表。
• clickup-pp-cli folder update — 重命名文件夹。

goal — 管理目标

• clickup-pp-cli goal delete — 从工作区中移除目标。
• clickup-pp-cli goal get — 查看目标的详细信息，包括其目标值。
• clickup-pp-cli goal update — 重命名目标、设置截止日期、替换描述、添加或移除所有者，并设置目标颜色。

group — 管理群组

• clickup-pp-cli group delete-team — 此端点用于移除[用户群组](https://docs.clickup.com/en/articles/4010016-teams-how-to-create-user-...
• clickup-pp-cli group get-teams1 — 此端点用于查看[用户群组](https://docs.clickup.com/en/articles/4010016-teams-how-to-create-user-gro...
• clickup-pp-cli group update-team — 此端点用于管理[用户群组](https://docs.clickup.com/en/articles/4010016-teams-how-to-create-user-g...

key-result — 管理关键结果

• clickup-pp-cli key-result delete — 删除目标中的一项指标。
• clickup-pp-cli key-result edit — 更新一项指标。

list — 管理列表

• clickup-pp-cli list delete — 从工作区中删除列表。
• clickup-pp-cli list get — 查看列表信息。
• clickup-pp-cli list update — 重命名列表、更新列表信息描述、设置截止日期/时间、设置列表的优先级、设置受分配者、设置...

oauth — 管理 OAuth

• clickup-pp-cli oauth — 这些是用于 API 身份验证和执行 OAuth 流程的路由。应用...

space — 管理空间

• clickup-pp-cli space delete — 从工作区中删除空间。
• clickup-pp-cli space get — 查看工作区中可用的空间。
• clickup-pp-cli space update — 重命名空间、设置空间颜色，并为其启用 ClickApps。

task — 管理任务

• clickup-pp-cli task attach — 将一个或多个本地文件作为附件上传到任务（multipart/form-data）
• clickup-pp-cli task attachments — 列出任务的附件及其大小、URL 和评论计数（总数/已解决/未解决）
• clickup-pp-cli task delete — 从工作区中删除任务。
• clickup-pp-cli task get — 查看任务信息。你只能查看自己有权访问的任务的信息。带有附件的任务...
• clickup-pp-cli task get-bulk-timein-status — 查看两个或更多任务在每种状态下持续了多长时间。必须先启用“状态中的总时长”ClickApp...
• clickup-pp-cli task update — 在请求正文中包含一个或多个字段，以更新任务。

team — 管理团队

• clickup-pp-cli team — 查看经过身份验证的用户可用的工作区。

user — 管理用户

• clickup-pp-cli user — 查看经过身份验证的用户的 ClickUp 账户详情。

view — 管理视图

• clickup-pp-cli view delete — 删除视图
• clickup-pp-cli view get — 查看特定任务或页面视图的信息。返回的视图信息因视图类型而异。
• clickup-pp-cli view update — 重命名视图，并更新视图的分组、排序、筛选条件、列和设置。

webhook — 管理 webhook

• clickup-pp-cli webhook delete — 删除 webhook，以停止监控其事件和位置。
• clickup-pp-cli webhook update — 更新 webhook，以更改要监控的事件。

workspaces — 管理工作区

查找合适的命令

知道要做什么，但不清楚该用哪个命令时，可以直接询问 CLI：

clickup-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help，或缩小查询范围。

操作示例

从工作区深入到任务

clickup-pp-cli team space get <team_id> --json --profile default

获取工作区下的所有空间 ID。将结果通过管道传给 space folder get / space list get-folderless，继续深入查询。

为 Agent 上下文提供精简 JSON

clickup-pp-cli task get <task_id> --select id,name,status.status,assignees --profile default --agent

--agent 会通过一个标志启用 JSON+compact+no-input+no-color+yes。--select 可筛选出高价值字段，即使任务数据丰富，也能将响应控制在 1KB 以内。

通过 v3 别名发送聊天消息

clickup-pp-cli workspaces chat create-message <team_id> <channel_id> --type message --content "shipped: rate-limit fix" --json --profile default

这是明确无歧义的完整路径。较短的 chat send 别名会映射到同一端点。ClickUp 会在 .data.id 下返回新消息 ID，供 chat react / chat reply 使用。

对已同步的任务进行本地分析

clickup-pp-cli analytics --type task --json --profile default

基于本地 SQLite 存储进行汇总。同步后无需调用 API。计数和基础分组功能可用；按嵌套路径分组（status.status）存在已知的框架限制。

通过自定义 ID 将本地文件附加到任务

clickup-pp-cli task attach PROJ-123 ./report.pdf --custom-task-ids --team-id 1234567 --agent

以 multipart/form-data 格式上传 report.pdf。先添加 --dry-run，即可预览 URL、MIME 类型和文件大小，而不会发送请求。

查找包含待处理审核评论的附件

clickup-pp-cli task attachments PROJ-123 --custom-task-ids --team-id 1234567 --json --select title,total_comments,resolved_comments,open_comments

open_comments = 总数 - 已解决数。公共 API 不会公开评论文本，只提供计数。

身份验证设置

ClickUp 支持通过 Authorization 标头使用个人 API 令牌（pk_...）和 OAuth bearer 令牌。在 shell 或 ~/.config/clickup-pp-cli/config.toml 中设置 CLICKUP_AUTHORIZATION_TOKEN。运行 clickup-pp-cli doctor 以验证身份验证和 API 可访问性。

Agent 模式

为任何命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 可保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于内容冗长的 API，这对控制上下文大小至关重要：

  clickup-pp-cli folder get mock-value --agent --select id,name,status
  

• 可预览 — --dry-run 可在不发送请求的情况下显示请求内容

• 支持离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 从不提示输入；所有输入都通过标志提供

• 显式重试 — 仅当已存在的创建结果应视为成功时使用 --idempotent；仅当缺失的删除目标应视为成功时使用 --ignore-missing

响应封装

从本地存储或 API 读取数据的命令会在输出外层添加来源信息封装：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时查询还是本地存储。只有当 stdout 连接到终端时，才会将易读的 N results (live) 摘要输出到 stderr——通过管道接收数据或使用 Agent 的程序会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有任何不妥之处时，请记录下来：

clickup-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
clickup-pp-cli feedback --stdin < notes.txt
clickup-pp-cli feedback list --json --limit 10

记录会保存在本地的 ~/.clickup-pp-cli/feedback.jsonl。除非设置了 CLICKUP_FEEDBACK_ENDPOINT，且传入 --send 或设置 CLICKUP_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅保存在本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体，写成一行：这部分内容会不断累积。

输出交付

每个命令都接受 --deliver <sink>。输出会发送到指定的接收端，同时写入标准输出，也可以替代标准输出，这样 Agent 就能路由命令结果，而无需手动管道传输。支持三种接收端：

接收端	效果
stdout	默认；仅写入标准输出
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

遇到未知方案时，系统会拒绝请求并返回结构化错误，列出支持的方案。Webhook 请求失败时会返回非零状态码，并在标准错误中记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果定时 Agent 每次运行都使用相同配置调用同一命令，就可以使用配置——这就是 HeyGen 的“Beacon”模式。

clickup-pp-cli profile save briefing --json
clickup-pp-cli --profile briefing folder get mock-value
clickup-pp-cli profile list --json
clickup-pp-cli profile show briefing
clickup-pp-cli profile delete briefing --yes

显式标志的优先级始终高于配置值；配置值的优先级高于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 clickup-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上方的先决条件
3. 其他任何内容 → 直接使用（作为带有 --agent 的 CLI 命令执行）

安装 MCP 服务

从此 CLI 已发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册它：

claude mcp add clickup-pp-mcp -- clickup-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which clickup-pp-cli 如果未找到，则提供安装选项（请参阅此技能顶部的先决条件）。
2. 将用户查询匹配到上方“独特功能”和“命令参考”中的最佳命令。
3. 使用 --agent 标志执行：

   clickup-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：clickup-pp-cli <command> --help。