clickup

ClickUp CLI（cup）— 技能版本 1.46.2

供使用 cup CLI 工具的 AI Agent 参考。涵盖任务管理、Sprint 跟踪、评论、时间跟踪、自定义字段、目标、Docs、Chat、视图、Webhook、工作区结构、导出和项目工作流。

版本检查： 运行 cup --version。如果已安装的版本低于 1.46.2，请使用 npm install -g @krodak/clickup-cli 更新，并通过 cup skill 刷新此技能（cup skill --path <file> 会安装到自定义位置，cup skill --print 会将内容写入标准输出）。

安装与配置

前提条件

需要 Node.js 22+。

安装

npm install -g @krodak/clickup-cli

或通过 Homebrew 安装：

brew tap krodak/tap && brew install clickup-cli

获取 API 令牌

用户需要从 ClickUp 获取个人 API 令牌：

1. 打开 https://app.clickup.com/settings/apps
2. 在“API Token”下，点击“Generate”（或复制现有令牌）
3. 令牌以 pk_ 开头

配置

非交互方式（推荐用于 Agent）：

cup init --token pk_USER_TOKEN --team TEAM_ID

用户可以查看 ClickUp URL 来查找团队/工作区 ID：https://app.clickup.com/TEAM_ID/...

交互方式（适用于在终端中操作的用户）：

cup init

环境变量（无需配置文件）：

export CU_API_TOKEN="pk_..."
export CU_TEAM_ID="12345678"

验证

cup auth

此命令会打印已验证身份的用户名和工作区。如果失败，说明令牌或配置无效。

设置

配置存储在 ~/.config/cup/config.json 中，并使用命名配置文件。每个配置文件都包含 apiToken 和 teamId。可选：使用 sprintFolderId 将 Sprint 检测固定到特定文件夹。

支持多个配置文件——使用 cup profile add <name> 创建，使用 cup profile use <name> 切换，或使用 -p <name> 标志进行单次覆盖。

CU_PROFILE 环境变量用于选择配置文件（-p 标志的优先级更高）。

已保存的筛选器（快捷方式）

每次会话开始时，运行 cup filter list，查看此工作区中已保存的快捷方式。

命令	功能
cup filter list [--json]	列出所有已保存的快捷方式及其命令和说明
cup filter run <name>	执行已保存的快捷方式（等同于运行完整命令）
cup filter save <name> <cmd> [args...] [-d desc]	保存命令快捷方式
cup filter delete <name>	删除快捷方式
cup filter show <name> [--json]	显示单个快捷方式的详细信息

示例：cup filter save sprint-tasks tasks --status "in progress" --list l1 -d "Current sprint tasks" 然后：cup filter run sprint-tasks 等同于 cup tasks --status "in progress" --list l1

输出模式

场景	默认输出	覆盖方式
终端（TTY）	交互式选择器 UI	使用 --json 输出 JSON
管道 / 非 TTY	Markdown 表格	使用 --json 输出 JSON

• 管道输出默认为 Markdown，适合 Agent 的上下文窗口
• 通过管道传输时，cup task <id> 会输出 Markdown 摘要；使用 --json 可获取完整的原始 API 对象
• 设置 CU_OUTPUT=json，使管道输出始终为 JSON
• 除非需要使用 jq 解析结构化数据，否则 Agent 通常无需使用 --json

命令

所有命令都支持 --help 以查看完整标志详情。所有命令都支持 --json。

读取

命令	返回内容
cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--all] [--include-closed] [--assignee id|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]	分配给你的任务（可按状态、名称、类型、列表、空间、负责人、标签、日期和自定义字段筛选）。--all 表示所有负责人的任务
cup assigned [--status s] [--include-closed]	按状态分组的我的所有任务
cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed]	当前 Sprint 中的任务（自动检测）
cup sprints [--space nameOrId]	列出所有 Sprint（用 * 标记当前 Sprint）
cup search [query] [--status s] [--list id] [--space id] [--all] [--include-closed] [--assignee id|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]	按名称搜索任务；未提供查询词时，则按标志筛选任务列表。--all 表示所有负责人的任务
cup task <id>	单个任务详情（自定义字段、检查清单、附件、依赖项、链接）
cup subtasks <id> [--status s] [--name q] [--include-closed]	某任务的子任务
cup comments <id>	某任务的评论
cup activity <id>	合并显示任务详情和评论历史
cup inbox [--days n] [--include-closed]	最近 n 天更新的任务（默认 30 天）
cup summary [--hours n]	每日站会摘要：已完成、进行中、已逾期
cup overdue [--all] [--include-closed]	已超过截止日期的任务（按逾期时间从长到短排序）
cup spaces [--name partial] [--my] [--archived]	列出／筛选工作区空间
cup lists <spaceId> [--name partial] [--archived]	某空间中的列表（包括文件夹列表）
cup folders <spaceId> [--name partial] [--archived]	某空间中的文件夹（及其列表）；JSON 中的子文件夹包含 parent_folder
cup time-in-status <id>	显示任务处于每种状态的时长
cup members	工作区成员（用户名、ID、电子邮件）
cup groups	用户组／团队（标识符、名称、UUID、成员数量），供 --group-assignee 标志使用
cup fields <listId>	列表中的自定义字段（类型、是否必填、选项）
cup attachments <taskId>	列出任务的附件（名称、大小、URL）
cup attach-get <taskId> [idOrTitle] [-o|--output path] [--all] [--dir d] [--force]	下载任务附件。未指定选择器且只有 1 个附件时会直接下载；有多个附件时必须指定选择器或使用 --all。默认以附件文件名保存
cup task-members <taskId>	列出有权访问任务的成员
cup plan	显示工作区方案和使用情况
cup tags <spaceId>	某空间中可用的标签
cup goals	工作区目标及进度
cup key-results <goalId>	某目标的关键结果
cup docs [query]	工作区文档（可按名称筛选）
cup doc <docId> [pageId]	文档元数据和页面树，或指定页面
cup doc-pages <docId>	文档中所有页面及其内容
cup task-types	自定义任务类型（供 --custom-item-id 使用）
cup templates	任务模板（供 --template 使用）
cup list-templates	列表模板（供 list-from-template 使用）
cup folder-templates	文件夹模板
cup views <id> [--space|--folder|--workspace]	列出列表（默认）、空间、文件夹或工作区中的视图（cup views any --workspace）
cup view <viewId>	获取视图详情
cup view-tasks <viewId> [--me]	列出视图中的任务（--me 仅筛选分配给你的任务）
cup open <query>	按 ID 或名称在浏览器中打开任务
cup auth	检查身份验证状态
cup list-comments <listId>	列表中的评论
cup view-comments <viewId>	视图中的评论
cup webhook list	列出工作区中的 webhook
cup shared	共享的空间、文件夹和列表
cup chat channels [--all] [--type type]	列出聊天频道
cup chat channel <id>	显示频道详情
cup chat messages <channelId> [--limit n]	列出频道消息
cup chat members <channelId>	列出频道成员
cup chat followers <channelId>	列出频道关注者
cup chat replies <messageId>	列出消息回复
cup chat reactions <messageId>	列出消息上的表情回应
cup export user|team|roadmap|initiatives|docs|all ... [--out dir] [--dry-run] [--item-id n] [--yes]	将任务／文档导出到本地存档（无损 JSON + Markdown）。参见下文的 Export

Write

命令	功能
cup create -n name [-l listId|sprint:current] [--parent parentId] [-d desc|--description-file path] [-s status] [--priority p] [--due-date d] [--start-date d] [--time-estimate t] [--assignee id|me] [--group-assignee uuid|@handle,...] [--tags t] [--custom-item-id n] [--template id] [--field "Name" val]	创建任务（--list 接受 sprint:current，--field 可内联设置自定义字段；--description-file 从文件读取 Markdown，或使用 - 从标准输入读取）
cup update <id> [-n name] [-d desc|--description-file path] [-s status] [--priority p] [--due-date d|none] [--start-date d] [--time-estimate t] [--assignee id|me] [--remove-assignee id|me] [--group-assignee uuid|@handle] [--remove-group-assignee uuid|@handle] [--parent id] [--archive] [--unarchive] [--type type] [--field "Name" val]	更新任务字段（--description-file 从文件读取 Markdown，或使用 - 从标准输入读取）
cup comment <id> -m text|--message-file path [--notify-all] [--mention user]	发布评论（Markdown 会自动转换为富文本；--message-file 从文件读取，或使用 - 从标准输入读取；--mention 用于创建真实的 @提及，可重复使用）
cup comment-edit <commentId> -m text|--message-file path [--resolved] [--unresolved] [--mention user]	编辑评论（Markdown 会自动转换为富文本；--mention 用于创建真实的 @提及）
cup comment-delete <commentId> 或 cup comment-delete --task <taskId> --mine [--match text]	按 ID 删除评论，或删除一条自己的任务评论
cup replies <commentId>	列出串接回复
cup reply <commentId> -m text|--message-file path [--notify-all] [--mention user]	回复评论（Markdown 会自动转换为富文本；--message-file 从文件读取，或使用 - 从标准输入读取；--mention 用于创建真实的 @提及）
cup assign <id> [--to ids|me] [--remove ids|me] [--group uuid|@handle,...] [--remove-group uuid|@handle,...]	分配/取消分配用户和群组（所有标志均接受逗号分隔的值）
cup depend <id> [--on taskId] [--blocks taskId] [--remove]	添加/移除依赖关系
cup move <id> [--to listId|sprint:current] [--remove listId]	将任务添加到列表或从列表中移除。同时使用 --to 和 --remove 会更改任务的 主 列表（使用 v3 home_list endpoint，并自动映射状态）。单独使用 --to 会将任务加入多个列表。--to 接受 sprint:current。
cup field <id> [--set "Name" value|--set "Name" --value-file path] [--remove "Name"]	设置/移除自定义字段值（--value-file 从文件读取值，或使用 - 从标准输入读取；适用于较长的/自由文本值）
cup field-create <name> -t <type> [-d desc] [--options "a,b,c"] [--required] [--list id] [--lists id1,id2]	创建自定义字段——适用于整个工作区（默认）、单个列表（--list）或批量应用于多个列表（--lists，并行处理并按列表报告结果）
cup tag <id> [--add tags] [--remove tags]	为任务添加/移除标签
cup link <taskId> <linksTo> [--remove]	链接/取消链接任务
cup attach <taskId> <filePath>	上传文件附件
cup delete <id> [--confirm]	删除任务（破坏性操作）
cup list-delete <listId> [--confirm]	删除列表（破坏性操作；非交互模式下需要 --confirm）
cup folder-delete <folderId> [--confirm]	删除文件夹（破坏性操作；非交互模式下需要 --confirm）
cup space-delete <spaceId> [--confirm]	删除空间（破坏性操作；非交互模式下需要 --confirm）
cup duplicate <taskId>	复制任务
cup bulk status <status> <taskIds...>	批量更新状态
cup bulk assign <taskIds...> [--to userId|me] [--remove userId|me]	批量为任务分配/取消分配用户
cup bulk due-date <date|none|clear> <taskIds...>	批量设置或清除截止日期
cup bulk tag <tagName> <taskIds...> [--remove]	批量为任务添加/移除标签
cup bulk priority <taskIds...> --to <priority>	批量设置多个任务的优先级
cup bulk field <taskIds...> --set "Name" value	批量设置自定义字段值
cup bulk move <taskIds...> --to <listId>	批量将任务移至目标列表
cup checklist view <id>	查看任务中的检查清单
cup checklist create <id> <name>	创建检查清单
cup checklist delete <checklistId>	删除检查清单
cup checklist add-item <checklistId> <name> [--parent itemId]	向检查清单添加项目（使用 --parent 嵌套到父项目下）
cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--parent itemId|null]	编辑检查清单项目（使用 --parent 更改父级，使用 "null" 取消嵌套）
cup checklist delete-item <checklistId> <itemId>	删除检查清单项目
cup time start <taskId> [-d desc]	开始计时
cup time stop	停止正在运行的计时器
cup time status	显示正在运行的计时器
cup time log <taskId> <duration> [-d desc]	记录手动工时（例如 "2h"、"30m"）
cup time list [--days n] [--task id] [--all]	列出我最近的工时记录（--all 表示列出团队记录）
cup time update <timeEntryId> [-d desc] [--duration dur]	更新工时记录
cup time delete <timeEntryId>	删除工时记录
cup goal-create <name> [-d desc] [--color hex]	创建目标
cup goal-update <goalId> [-n name] [-d desc] [--color hex]	更新目标
cup goal-delete <goalId>	删除目标
cup key-result-create <goalId> <name> [--type t] [--target n]	创建关键结果
cup key-result-update <keyResultId> [--progress n] [--note text]	更新关键结果
cup key-result-delete <keyResultId>	删除关键结果
cup doc-create <title> [-c content]	创建文档（根页面以标题命名；-c 用于写入其 Markdown 内容）
cup doc-page-create <docId> <name> [-c content|--content-file path] [--parent-page pageId]	创建文档页面（--content-file 从文件读取 Markdown，或使用 - 从标准输入读取）
cup doc-page-edit <docId> <pageId> [--name text] [-c content|--content-file path]	编辑文档页面（--content-file 从文件读取 Markdown，或使用 - 从标准输入读取）
cup doc-delete <docId>	不支持——ClickUp 没有删除文档的 API（HTTP 405）。命令会快速失败；请在 UI 中删除文档。若要删除单个页面，请使用 cup doc-page-delete
cup doc-page-delete <docId> <pageId>	删除文档页面
cup space-create <name>	创建空间
cup list-create <spaceId> <name> [--folder folderId] [--copy-statuses-from id]	在空间或文件夹中创建列表
cup folder-create <spaceId> <name>	在空间中创建文件夹
cup list-rename <listId> <newName>	重命名列表
cup folder-rename <folderId> <newName>	重命名文件夹
cup space-rename <spaceId> <newName>	重命名空间
cup tag-create <spaceId> <name> [--fg color] [--bg color]	创建空间标签
cup tag-update <spaceId> <tagName> --name <newName> [--fg c] [--bg c]	更新空间标签
cup tag-delete <spaceId> <name>	删除空间标签
cup list-from-template <name> --template <id> [--space id] [--folder id]	根据模板创建列表
cup view-create <listId> <name> -t <type> [--group-by field]	在列表中创建视图
cup view-update <viewId> [-n name] [--group-by field]	更新视图
cup view-delete <viewId> [--confirm]	删除视图（破坏性操作）
cup list-comment <listId> -m text [--notify-all] [--mention user]	在列表上发布评论（--mention 用于创建真实的 @提及）
cup view-comment <viewId> -m text [--notify-all] [--mention user]	在视图上发布评论（--mention 用于创建真实的 @提及）
cup webhook create --url <url> --events <events> [--space|--folder|--list|--task <id>]	创建 webhook
cup webhook update <webhookId> [--url u] [--events e] [--status s]	更新 webhook
cup webhook delete <webhookId> [--confirm]	删除 webhook（破坏性操作）
cup merge <sourceTaskId> <intoTaskId> [--confirm]	将任务合并到另一任务中（破坏性操作，源任务会被删除）
cup time estimate-by-user <taskId> <userId> <duration> [--replace]	设置每位用户的工时预估
cup chat send <channelId> -m <text> [--post --title t]	向频道发送消息
cup chat reply <messageId> -m <text>	回复消息
cup chat react <messageId> --emoji <name>	添加表情回应
cup chat unreact <messageId> --emoji <name>	移除表情回应
cup chat channel-create <name> [--private] [--topic t]	创建频道
cup chat dm <userIds...>	创建/打开私信
cup chat channel-update <id> [--name n] [--topic t]	更新频道
cup chat channel-delete <id> [--confirm]	删除频道
cup chat message-update <messageId> -m <text>	编辑消息
cup chat message-delete <messageId> [--confirm]	删除消息
cup favorite add <type> <id> [alias] [-n name]	添加本地收藏项
cup favorite remove <alias>	移除收藏项
cup favorite list [--type t]	列出收藏项（可按类型筛选）
cup profile list [--json]	列出所有配置
cup profile add <name>	添加新配置（交互式）
cup profile remove <name>	移除配置
cup profile use <name>	设置默认配置
cup config get <key> / set <key> <value> / path	管理配置
cup completion <shell>	Shell 补全（bash/zsh/fish）

全局标志

标志	说明
-p, --profile <n>	为此命令使用指定的配置
--json	强制使用 JSON 输出（适用于所有命令）

-p 始终表示 --profile，而不是 --parent。 全局短标志的优先级高于子命令的短标志，因此 cup create -p <taskId> 会报错 Profile "<taskId>" not found。请使用 cup create --parent <taskId>。

标志与约定

主题	详情
任务 ID	原生 ID（abc123def）或自定义 ID（PROJ-123）。自定义 ID 会根据 PREFIX-DIGITS 格式自动检测
任务 URL	所有接受任务 ID 的命令也接受完整的 ClickUp URL（https://app.clickup.com/t/<id> 或 https://app.clickup.com/t/<workspace>/<id>）。ID 会自动提取
视图 URL	所有接受视图 ID 的命令也接受完整的 ClickUp 视图 URL（https://app.clickup.com/<workspace>/v/<type>/<viewId>）。ID 会自动提取
--status	模糊匹配：完全匹配 > 前缀匹配 > 包含匹配。匹配结果输出到 stderr
--priority	名称（urgent、high、normal、low）或数字（1-4）
--due-date	YYYY-MM-DD（仅日期）、YYYY-MM-DDTHH:MM（含时间）或完整的 ISO 8601 格式（含偏移量）。时间格式会在 ClickUp 中设置 due_date_time: true
--assignee	用户 ID 或 me
--tags	逗号分隔（例如 --tags "bug,frontend"）
--time-estimate	时长："2h"、"30m"、"1h30m" 或原始毫秒数
--type	task（常规）或自定义类型名称/ID（例如 initiative、Bug）
--custom-item-id	用于 cup create 的自定义任务类型 ID（使用 cup task-types 查找）
--space	名称部分匹配或精确 ID
--name	部分匹配，不区分大小写
--all	显示工作区中的所有任务，而不只是分配给我的任务。适用于 tasks、search、overdue。默认仅显示我的任务（减少 Agent 上下文窗口中的输出）
--include-closed	包含已关闭/已完成的任务
创建时的 --list	指定 --parent 时为可选项（会自动检测）。接受伪 ID sprint:current
cup field --set	支持：文本、数字、复选框（true/false）、下拉菜单（选项名称）、标签（逗号分隔的名称）、日期（YYYY-MM-DD）、URL、电子邮件、表情符号/评分（0-5）、手动进度（0-100）、任务/关系（逗号分隔的任务 ID）、用户/人员（逗号分隔的用户 ID）。名称按不区分大小写的方式解析；错误信息会列出可用字段/选项
cup field-create	对 drop_down 和 labels 类型使用 --options "a,b,c"（必需）。其他类型无需 --options
--field 筛选器	在 tasks 和 search 中使用 --field "Name" value，需要指定 --list 才能将字段名称解析为 ID
--due-before/after	用于到期日期范围的 YYYY-MM-DD 日期筛选器
--created-before/after	用于创建日期范围的 YYYY-MM-DD 日期筛选器
cup sprint	按文件夹名称（sprint/iteration/cycle/scrum）自动检测当前活跃的 sprint，并解析多种日期格式。可使用 --folder <id>、cup config set sprintFolderId <id> 覆盖，或将 sprint 文件夹收藏
cup favorite	仅本地收藏（不会同步到 ClickUp）。类型：sprint-folder、space、list、folder、view、task。已收藏的 sprint 文件夹会由 sprint 命令自动使用
cup link	两个 ID 必须为相同类型（均为自定义 ID 或均为原生 ID）
cup delete	具有破坏性。非交互模式下需要 --confirm。无法撤销
错误	出错时退出代码为 1。cup auth --json（以及 CU_OUTPUT=json）会将身份验证失败信息以 JSON 格式保留在 stdout；其他错误输出到 stderr。严格解析会拒绝多余/未知参数
速率限制	客户端会针对 HTTP 429 重试，并根据 Retry-After 进行退避（最多重试 3 次）。对于瞬时 502/503/504 错误，仅对 GET/HEAD 读取请求进行有限次数的重试。发生网关错误或传输故障后不会重放变更操作：重试前请检查远程状态。警告输出到 stderr
多行 Markdown（-d / -m / 字段值）	最适合 Agent： 使用 --description-file <path> / --message-file <path> / --value-file <path>（或使用 - 表示 stdin），完全绕过 shell 引号处理——请参阅下方的多行示例。若要内联多行内容，请使用带引号的 here-doc "$(cat <<'EOF' … EOF)"——它会保留反引号、换行符和撇号。易错点： 切勿使用 '\'' 来拆分 $'...' 字符串以表示撇号——后半部分会恢复为普通单引号，且 \n 会变成字面文本（例如 $'…team'\''s…\n## Goals' 会出错）。普通双引号会将反引号中的内容作为命令执行。
--mention <user>	创建真实的 ClickUp @提及（会通知用户）。接受 ID、电子邮件、用户名或 me。可重复使用。也支持在 -m 中使用 <@userId> 行内标记，在句中提及用户。不会解析裸写的 @Name（存在歧义）。适用于 comment、reply、comment-edit、list-comment、view-comment
评论链接	在评论消息中，裸 URL（https://...）和 Markdown 链接（[text](url)）都会呈现为可点击链接。不支持展开预览卡片（仅限 Web UI）

注意： cup search、cup tasks、cup overdue 和 cup assigned 默认只显示分配给当前用户的任务。使用 --all 可包含分配给其他人的任务。搜索上级计划或团队范围的事项时，这一点很重要。

交互模式（TTY）

在终端中运行（非管道传输）时，任务列表命令（cup tasks、cup search、cup sprint、cup overdue、cup assigned、cup inbox、cup summary）会显示交互式任务选择器：

• 使用 ↑/↓ 或 j/k 浏览列表
• 按 Space 切换任务选择状态
• 按 Enter 确认并查看所选任务的详情
• 查看详情后，系统会提示是否在浏览器中打开任务

其他交互式提示：Sprint 选择（匹配项不止一个时）、工作区选择（cup init）、Agent 选择（cup skill）、破坏性操作确认（cup delete、cup list-delete、cup folder-delete、cup space-delete、cup archive、cup view-delete、cup merge、cup webhook delete）。

通过管道传输或使用 --json 调用时，所有命令都会输出非交互式 Markdown 或 JSON。Agent 应始终使用 --json 获取结构化数据，或通过管道获取 Markdown。

Agent 工作流示例

调查任务

cup task abc123def                   # markdown summary
cup subtasks abc123def               # child tasks (open only)
cup subtasks abc123def --include-closed  # all child tasks
cup comments abc123def               # discussion
cup activity abc123def               # task + comments combined

查找任务

cup tasks --status "in progress"     # by status
cup tasks --name "login"             # by partial name
cup tasks --type initiative          # initiatives only
cup tasks --list 12345 --all         # all tasks in list, not just mine
cup tasks --tag "bug" --status "to do"  # by tag and status
cup tasks --list 123 --field "Sprint" "Week 1"  # by custom field
cup tasks --due-before 2026-04-01    # due before a date
cup tasks --assignee me --created-after 2026-03-01  # my tasks created recently
cup search "payment flow"            # multi-word search
cup search auth --status "prog"      # fuzzy status match
cup search "auth" --list 123 --space 456  # search within list and space
cup search --assignee me             # no query — all my tasks
cup search --assignee me --status "in progress"  # filter without query
cup sprint                           # current sprint
cup assigned                         # all my tasks by status
cup overdue                          # past due date
cup inbox --days 7                   # recently updated

进行更改

cup update abc123def -s "done"
cup update abc123def --priority high --due-date 2025-03-15
cup update abc123def --due-date 2025-03-15T14:30     # date + time (user's timezone)
cup update abc123def --due-date 2025-03-15T14:30:00Z # UTC
cup create -n "Fix the thing" --parent abc123def   # -p is the global --profile, not --parent
cup create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
cup create -n "Bug fix" -l sprint:current         # create in active sprint
cup create -n "Q3 Roadmap" -l <listId> --custom-item-id 1
cup create -n "New story" -l <listId> --field "Story Points" 5 --field "Stage" "In Review"
cup comment abc123def -m "Completed in PR #42"
cup comment abc123def -m "## Results\n\n**Passed**: 15/15\n- Unit tests\n- Integration"
cup assign abc123def --to me
cup assign abc123def --to 12345,67890        # assign multiple users at once
cup assign abc123def --group @mobile-team    # assign a user group (find handles with `cup groups`)
cup assign abc123def --to me --group @backend  # assign self and a group together
cup update abc123def --group-assignee @mobile-team   # group assignment via update
cup update abc123def --remove-group-assignee @backend
cup depend task3 --on task2            # task3 waits for task2
cup move task1 --to list2                        # add task1 to list2 (multi-list membership)
cup move task1 --to list2 --remove list1         # change home list from list1 to list2 (v3 home_list)
cup move task1 --to sprint:current --remove list1 # move home list to active sprint
cup field abc123def --set "Story Points" 5
cup tag abc123def --add "bug,frontend"
cup checklist create abc123def "QA Steps"
cup checklist add-item <clId> "Run unit tests"
cup checklist add-item <clId> "Sub step" --parent <itemId>           # nest under parent
cup checklist edit-item <clId> <itemId> --resolved
cup checklist edit-item <clId> <itemId> --parent <newParent>         # reparent (use "null" to unnest)
cup link abc123 def456
cup attach abc123def ./screenshot.png
cup time start abc123def -d "Working on feature"
cup time stop
cup time log abc123def 2h -d "Code review"
cup delete abc123def --confirm          # irreversible!

多行 Markdown 描述和评论

Agent 会生成结构化 Markdown（标题、项目符号、代码、撇号）。Shell 引号是最容易出错的环节。以下两种模式较为可靠：

# 1. Best for agents: write markdown to a file, then reference it (no shell quoting at all)
cup create -n "Improve onboarding" -l <listId> --description-file /tmp/desc.md
cup update <taskId> --description-file /tmp/desc.md
cup comment <taskId> --message-file /tmp/comment.md
cup field <taskId> --set "Standup 4 - 6/25" --value-file /tmp/note.md
# "-" reads stdin:
printf '## Notes\n\nTeam'\''s update with `code`.' | cup update <taskId> --description-file -

# 2. Inline multiline: quoted heredoc preserves backticks, newlines, AND apostrophes
cup create -n "Improve onboarding" -l <listId> -d "$(cat <<'EOF'
## Overview

Refresh the team's onboarding docs. Use `init()` first.

## Goals

- Goal one
- Goal two
EOF
)"

不要使用 $'…team'\''s…\n\n## Goals'——在 '\'' 撇号处打断后，字符串会恢复为普通单引号，因此 \n 会按原样传递，标题和项目符号在 ClickUp 中会显示为 \n\n 文本。

文档

cup docs "design"                              # search docs
cup doc <docId> <pageId>                       # view page
cup doc-create "Architecture Notes" -c "# Draft"
cup doc-page-create <docId> "Section" --parent-page <pageId>
cup doc-page-edit <docId> <pageId> -c "# Updated"

导出（知识转移 / 离职交接）

每个任务只存储一次（tasks/<id>/task.json + task.md + 评论 + 附件）；每个范围都会添加一个索引。多个切片会合并到同一个 --out 目录中；共享任务只会获取一次。重新运行时会跳过已有内容。

cup export user me --out ./archive                    # my tasks, incl. closed + archived
cup export team "Atlas" --out ./archive             # every list in a space
cup export roadmap <listId> --item-id 1004 --out ./archive   # initiatives grouped with subtask trees
cup export docs --out ./archive                       # every doc as markdown page trees
cup export all --dry-run                              # plan: counts, estimated time
cup export all --yes --out ./archive                  # whole workspace (long-running; confirms)

• --item-id 是计划的 custom_item_id（团队约定；cup task-types 会列出这些 ID）。
• all 在非交互模式下必须使用 --yes 才能运行；务必先使用 --dry-run 查看估算结果。
• 白板、仪表盘和自动化没有 API：请手动从 UI 导出。

工作区结构

cup spaces --name "Engineering"      # find space ID
cup folders <spaceId>                # folders with their lists
cup lists <spaceId>                  # lists in a space
cup space-create "New Space"         # create a space
cup folder-create <spaceId> "Q2"     # create a folder
cup list-create <spaceId> "Backlog"  # create a list
cup list-create <spaceId> "Sprint" --folder <folderId>
cup space-rename <spaceId> "Platform"   # rename a space
cup folder-rename <folderId> "Q3"       # rename a folder
cup list-rename <listId> "Sprint 12"    # rename a list
cup members                          # workspace members
cup groups                           # user groups/teams (for --group-assignee)
cup fields <listId>                  # custom fields on a list
cup task-types                       # custom task types
cup templates                        # task templates

目标

cup goals
cup goal-create "Ship v2" -d "Release version 2"
cup key-results g123
cup key-result-create g123 "API coverage" --type percentage --target 80
cup key-result-update kr456 --progress 60 --note "On track"

配置文件

cup profile add personal             # add a profile (interactive)
cup profile list                     # list all profiles
cup profile use personal             # switch default
cup tasks -p work                    # use specific profile for one command

收藏

cup favorite add sprint-folder 12345 --name "Team Sprint"  # favorite a sprint folder
cup favorite add space 67890 eng                           # favorite a space with alias
cup favorite list                                          # list all favorites
cup favorite list --type sprint-folder                     # list only sprint folders
cup favorite remove eng                                    # remove by alias
cup sprint                                                 # auto-uses favorited sprint folder

站会

cup summary                          # completed / in progress / overdue
cup summary --hours 48               # wider window

删除安全须知

重要：运行 cup delete、cup list-delete、cup folder-delete、cup space-delete、cup merge 或 cup webhook delete 前，务必先征得用户确认。这些操作具有破坏性且不可逆。即使使用了 --confirm 标志，也要先与用户核实 ID 是否正确。