AI导哈

项目管理CLI工具

ClickUp CLI是一个JSON优先、代理原生的命令行工具，支持ClickUp API v2的所有功能，适用于项目管理自动化和人工操作。

  • by bcharleson
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 bcharleson/clickup-cli

使用说明

ClickUp命令行界面

JSON-首先，用于ClickUp API v2的代理名CLI。

ClickUp的项目管理API没有正式的CLI。此CLI填补了这一空白，涵盖了工作区、空间、文件夹、列表、任务、注释、时间跟踪、目标、Webhook等。每个命令都返回结构化JSON，从终端工作 和 作为MCP工具，您的AI代理可以像人类在命令行中一样管理整个ClickUp工作区。

为什么选择Agent Native？

clickup-cli （这个）
范围 完整点击API v2-19个组中的105个命令
输出 JSON优先——默认情况下机器可解析
MCP支持 内置MCP服务器——每个命令都是MCP工具
代理使用 每个命令在终端或MCP上的工作方式都是相同的
认证 API令牌（三层解析）

本地代理 指：

  • JSON第一个输出 --每个响应都是有效的JSON，管道到 jq 或从任何语言中消费
  • 双入口点 --与CLI相同的命令 和 零自适应MCP工具
  • 结构化错误 --错误返回 { "error": "...", "code": "..." }，不是堆栈跟踪
  • 字段过滤 — --fields id,name,status.status 只返回您需要的东西
  • 自动化中没有交互式提示 --所有可用作标志、环境变量或配置的参数

安装

npm install -g @bcharleson/clickup-cli

快速开始

# 1. Get your API token from ClickUp
# Settings → Apps → API Token → Generate

# 2. Authenticate
export CLICKUP_API_TOKEN="pk_xxxxx"

# 3. List your workspaces
clickup workspaces list --pretty

# 4. List spaces in a workspace
clickup spaces list --team-id 12345678

# 5. List tasks in a list
clickup tasks list --list-id 11111 --pretty

认证

1.获取您的API代币

  1. 在ClickUp中，转到 设置 → 应用 → API代币
  2. 点击 生成 创建个人API令牌
  3. 复制令牌（以开头 pk_)

2.身份验证

三层分辨率（最高优先级优先）：

# Option A: Environment variable (recommended for agents)
export CLICKUP_API_TOKEN="pk_xxxxx"

# Option B: Interactive login (saves to ~/.clickup-cli/config.json)
clickup login

# Option C: Per-command flag
clickup tasks list --list-id 123 --api-token "pk_xxxxx"

3.验证

clickup workspaces list --pretty

ClickUp层次结构

Workspace (team_id) → Space → Folder (optional) → List → Task → Subtask

要点：

  • team_id 在API中=工作区ID（传统命名）
  • 无文件夹列表直接位于空格下方
  • 任务属于一个“主”列表，但可以出现在多个列表中
  • API中的日期以Unix毫秒为单位
  • 优先级：1=紧急，2=高，3=正常，4=低

命令

层次结构（22个命令）

组 命令
工作区 list, seats, plan
空间 list, get, create, update, delete
文件夹 list, get, create, update, delete
清单 list, folderless, get, create, create-folderless, update, delete, add-task, remove-task

任务和内容（35个命令）

组 命令
任务 list, get, create, update, delete, filtered, time-in-status
评论 list-task, create-task, list-list, create-list, list-view, create-view, update, delete, list-replies, create-reply
清单 create, update, delete, create-item, update-item, delete-item
自定义字段 list-workspace, list, list-folder, list-space, set, remove
标签 list, create, update, delete, add-to-task, remove-from-task
依赖项 add, remove, add-link, remove-link

视图和跟踪（24个命令）

组 命令
观点 list-workspace, list-space, list-folder, list-list, get, tasks, delete
时间追踪 list, get, create, update, delete, current, start, stop, history
目标 list, get, create, update, delete, create-key-result, update-key-result, delete-key-result

管理和配置（24个命令）

组 命令
网络钩子 list, create, update, delete
用户 me, get, invite, update, remove
客人 invite, get, update, remove, add-to-task, remove-from-task
成员 task, list
模板 list, create-task
角色 list

身份验证与配置

命令 描述
login 使用API令牌进行身份验证
logout 删除存储的凭据
status 显示当前身份验证+帐户信息

全局选项

--api-token <token>   Override stored auth
--output <format>     json (default) or pretty
--pretty              Shorthand for --output pretty
--quiet               Suppress output, exit codes only
--fields <fields>     Comma-separated field filter (supports nested: status.status)

例子

# Navigate the hierarchy
clickup workspaces list --fields teams
clickup spaces list --team-id 12345678
clickup folders list --space-id 98765
clickup lists list --folder-id 54321
clickup tasks list --list-id 11111

# Create a task with full details
clickup tasks create --list-id 123 \
  --name "Implement OAuth flow" \
  --description "Add OAuth 2.0 support" \
  --priority 2 \
  --status "in progress" \
  --assignees "456,789" \
  --due-date "1711929600000" \
  --tags "backend,auth" \
  --time-estimate 14400000

# Search tasks across a workspace
clickup tasks filtered --team-id 123 --assignees "456"
clickup tasks filtered --team-id 123 --statuses "in progress" --space-ids "111,222"

# Comments and checklists
clickup comments create-task --task-id abc --comment-text "Ready for review"
clickup checklists create --task-id abc --name "Deploy checklist"
clickup checklists create-item --checklist-id ck1 --name "Run tests"

# Time tracking
clickup time-tracking start --team-id 123 --task-id abc --description "Working on OAuth"
clickup time-tracking current --team-id 123
clickup time-tracking stop --team-id 123

# Goals and OKRs
clickup goals create --team-id 123 --name "Q1 Revenue Target" \
  --due-date "1711929600000" --owners "456"
clickup goals create-key-result --goal-id abc \
  --name "Close 50 deals" --type number --steps-start 0 --steps-end 50

# Webhooks
clickup webhooks create --team-id 123 \
  --endpoint "https://example.com/webhooks/clickup" \
  --events "taskCreated,taskUpdated,taskStatusUpdated"

# Custom fields
clickup custom-fields list --list-id 123
clickup custom-fields set --task-id abc --field-id cf_1 --value "high"

# Tags
clickup tags list --space-id 123
clickup tags add-to-task --task-id abc --tag-name "urgent"

# Dependencies
clickup dependencies add --task-id taskB --depends-on taskA
clickup dependencies add-link --task-id task1 --links-to task2

# Views
clickup views list-workspace --team-id 123
clickup views tasks --view-id v123

# Users and guests
clickup users me
clickup users invite --team-id 123 --email "user@example.com"
clickup guests invite --team-id 123 --email "guest@example.com"

# Pipe to jq
clickup tasks list --list-id 123 | jq '.tasks[].name'
clickup tasks filtered --team-id 123 | jq '.tasks[] | {id, name, status: .status.status}'

MCP 服务器

CLI包括一个内置的MCP服务器，将所有105个命令作为工具公开：

# Start the MCP server
clickup mcp

MCP配置

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@bcharleson/clickup-cli", "mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

或者使用本地安装：

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/clickup-cli/dist/mcp.js"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

MCP工具名称

所有工具均已命名 {group}_{subcommand} 连字符转换为下划线：

  • tasks_list, tasks_get, tasks_create, tasks_update, tasks_delete, tasks_filtered
  • comments_create_task, comments_list_task, ...
  • time_tracking_start, time_tracking_stop, time_tracking_current, ...
  • goals_create, goals_create_key_result, ...
  • webhooks_create, webhooks_list, ...

建筑

此CLI遵循跨平台共享的元数据驱动架构 hubspot-cli 和 即时cli:

  • 命令定义 --单个结构驱动CLI注册和MCP工具注册
  • Zod模式 --CLI和MCP之间共享输入验证
  • 声明性端点 — { method, path, fieldMappings } 驱动HTTP请求构建
  • 瘦REST客户端 --裸令牌身份验证、429秒上的指数回退、速率限制标头处理
  • 双入口 — dist/index.js （CLI）和 dist/mcp.js （MCP服务器）

许可证

麻省理工学院

相关 MCP