Skip to content
Back to search

clickup-cli

ClickUp CLI for AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/krodak--clickup-cli/badge.svg)](/listings/krodak--clickup-cli)

HTML

<a href="/listings/krodak--clickup-cli"><img src="/api/listings/krodak--clickup-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)).

<details open> <summary>&nbsp;<img src="https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white" height="18" align="center">&nbsp;<strong>npm</strong></summary>

npm install -g @krodak/clickup-cli
cup init
cup auth  # verify setup

</details>

<details> <summary>&nbsp;<img src="https://img.shields.io/badge/Homebrew-FBB040?logo=homebrew&logoColor=black" height="18" align="center">&nbsp;<strong>Homebrew</strong></summary>

brew tap krodak/tap
brew install clickup-cli
cup init
cup auth  # verify setup

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 11 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "clickup-cli",
  3. "description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cup command",
  4. "version": "1.46.2",
  5. "author": {
  6. "name": "Krzysztof Rodak"
  7. },
  8. "homepage": "https://github.com/krodak/clickup-cli",
  9. "repository": "https://github.com/krodak/clickup-cli",
  10. "license": "MIT"
  11. }
README.md · README · 285 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="banner.png" alt="cup - ClickUp CLI for AI agents (and humans)" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://www.npmjs.com/package/@krodak/clickup-cli"><img src="https://img.shields.io/npm/v/@krodak/clickup-cli" alt="npm"></a>
  6. <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@krodak/clickup-cli" alt="node"></a>
  7. <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@krodak/clickup-cli" alt="license"></a>
  8. <a href="https://github.com/krodak/clickup-cli/actions/workflows/ci.yml"><img src="https://github.com/krodak/clickup-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  9. <a href="https://github.com/krodak/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-FBB040?logo=homebrew&logoColor=black" alt="homebrew"></a>
  10. </p>
  11. ```bash
  12. npm install -g @krodak/clickup-cli && cup init
  13. ```
  14. ## For AI Agents
  15. Paste this into any AI agent (Claude Code, Codex, Cursor, OpenCode, etc.):
  16. ```
  17. Install and configure the ClickUp CLI for me. Fetch the setup guide from:
  18. https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md
  19. Then walk me through installing the CLI, getting a ClickUp API token,
  20. and running cup init. Finally, install the skill with `cup skill` so
  21. you have persistent access to the full command reference.
  22. ```
  23. The fetched SKILL.md contains everything the agent needs: install commands,
  24. where to get a ClickUp API token, non-interactive setup with `cup init --token --team`,
  25. and the complete command reference. After setup, the agent can run any `cup` command
  26. to manage your tasks, sprints, comments, time tracking, and more.
  27. **Already have the CLI installed?** Just run `cup skill` to install the agent skill to
  28. all detected locations (see [Set up your agent](#set-up-your-agent) below).
  29. ## Talk to your agent
  30. Install the CLI, add the skill file to your agent, and it works with ClickUp. No API knowledge needed.
  31. > **"Read task abc123, do the work, then mark it in review and leave a comment with the commit hash."**
  32. > **"What's my standup? What did I finish, what's in progress, what's overdue?"**
  33. > **"Create a subtask under the initiative for the edge case we found."**
  34. > **"Check my sprint and tell me what's behind schedule."**
  35. > **"Update the description with your findings and flag blockers in a comment."**
  36. The agent reads the skill file, picks the right `cup` commands, and handles everything. You don't need to learn the CLI - the agent does.
  37. ### Terminal mode (TTY)
  38. Task listing commands (`cup tasks`, `cup search`, `cup sprint`, etc.) present an interactive picker — navigate with arrow keys or j/k, Space to select tasks, Enter to confirm. Selected tasks show full details and offer to open in the browser. Other prompts (sprint disambiguation, delete confirmations) also use interactive selection.
  39. ![TTY Mode - interactive tables and detail views](demos/tty-mode.gif)
  40. ### Agent / piped mode
  41. When piped (no TTY), the same commands output clean Markdown (or JSON with `--json`). No prompts, no colors — designed for agents and pipelines.
  42. `cup auth` exits with code 1 when authentication fails, including with `--json` or `CU_OUTPUT=json`; JSON mode preserves the authentication result on stdout. HTTP 429 responses are retried with bounded backoff. Transient gateway errors (502/503/504) are retried only for reads (GET/HEAD): mutations fail without automatic replay because their outcome may be uncertain. Check the remote state before repeating a failed write.
  43. ![Agent Mode - markdown and JSON output](demos/agent-mode.gif)
  44. ## Why a CLI and not MCP?
  45. A CLI + skill file has fewer moving parts. No server process, no protocol layer. The agent already knows how to run shell commands - the skill file teaches it which ones exist. For tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.
  46. ## Install
  47. You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)).
  48. <details open>
  49. <summary>&nbsp;<img src="https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white" height="18" align="center">&nbsp;<strong>npm</strong></summary>
  50. ```bash
  51. npm install -g @krodak/clickup-cli
  52. cup init
  53. cup auth # verify setup
  54. ```
  55. </details>
  56. <details>
  57. <summary>&nbsp;<img src="https://img.shields.io/badge/Homebrew-FBB040?logo=homebrew&logoColor=black" height="18" align="center">&nbsp;<strong>Homebrew</strong></summary>
  58. ```bash
  59. brew tap krodak/tap
  60. brew install clickup-cli
  61. cup init
  62. cup auth # verify setup
  63. ```
  64. </details>
  65. ## Set up your agent
  66. After installing `cup`, run:
  67. ```bash
  68. cup skill
  69. ```
  70. This detects which agents you have (Claude Code, Codex, OpenCode) and installs the [skill file](https://agentskills.io) to the right locations. Run it again after updating `cup` to refresh the skill.
  71. <details>
  72. <summary>Manual install options</summary>
  73. <details>
  74. <summary>&nbsp;<img src="https://img.shields.io/badge/Claude_Code-D97757?logo=anthropic&logoColor=white" height="18" align="center">&nbsp;<strong>Claude Code</strong></summary>
  75. **Install as a [plugin](https://docs.anthropic.com/en/docs/claude-code/plugins)** (recommended):
  76. ```bash
  77. claude plugin add $(npm root -g)/@krodak/clickup-cli
  78. ```
  79. **Or as a personal skill:**
  80. ```bash
  81. cup skill --path ~/.claude/skills/clickup/SKILL.md
  82. ```
  83. </details>
  84. <details>
  85. <summary>&nbsp;<img src="https://img.shields.io/badge/Codex-412991?logo=openai&logoColor=white" height="18" align="center">&nbsp;<strong>Codex</strong></summary>
  86. ```bash
  87. cup skill --path ~/.agents/skills/clickup/SKILL.md
  88. ```
  89. Or for a project-level skill:
  90. ```bash
  91. cup skill --path .agents/skills/clickup/SKILL.md
  92. ```
  93. </details>
  94. <details>
  95. <summary>&nbsp;<img src="https://img.shields.io/badge/OpenCode-24292e?logoColor=white" height="18" align="center">&nbsp;<strong>OpenCode</strong></summary>
  96. ```bash
  97. cup skill --path ~/.config/opencode/skills/clickup/SKILL.md
  98. ```
  99. </details>
  100. <details>
  101. <summary>&nbsp;<strong>Other agents / npx</strong></summary>
  102. Without installing globally, you can use `npx`:
  103. ```bash
  104. npx @krodak/clickup-cli skill --print > SKILL.md
  105. ```
  106. Or install the skill directly from GitHub via the [skills CLI](https://github.com/vercel-labs/skills):
  107. ```bash
  108. npx skills add https://github.com/krodak/clickup-cli
  109. ```
  110. </details>
  111. </details>
  112. ## What it covers
  113. Full CRUD for the core ClickUp workflow:
  114. | Area | Capabilities |
  115. | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  116. | ✅ **Tasks** | Create, read, update, delete, duplicate, merge, search, subtasks, assign (users and groups), dependencies, links, multi-list, bulk operations (status, assign, due-date, tag, priority, field, move) |
  117. | 💬 **Comments** | Post, edit, delete by ID or by task scope for your own comments, threaded replies, notify all, real @mentions (flag or inline `<@id>` token, notifies the user), clickable rich links, list and view comments |
  118. | 🗨️ **Chat** | List channels, send messages, replies, reactions, channel management |
  119. | 📄 **Docs** | List, read, create, edit, delete (v3 API) |
  120. | ⏱️ **Time Tracking** | Start/stop timer, log entries, list/update/delete history, per-user time estimates |
  121. | ☑️ **Checklists** | View, create, delete, add/edit/delete items |
  122. | 🔧 **Custom Fields** | List, create, set, remove values (text, number, dropdown, labels, date, checkbox, url, email, rating, progress, relationship, people) |
  123. | 🏷️ **Tags** | Add/remove on tasks, space-level create/update/delete |
  124. | 🎯 **Goals & OKRs** | Goals CRUD, key results CRUD |
  125. | 🏃 **Sprints** | Auto-detect active sprint, `sprint:current` pseudo-ID for move/create, flexible date parsing, config override, favorite sprint folders |
  126. | ⭐ **Favorites** | Local favorites for quick access to sprint folders, spaces, lists, folders, views, tasks |
  127. | 👁️ **Views** | List, get, create, update, delete views on lists |
  128. | 🔗 **Webhooks** | List, create, update, delete webhooks; scope to space, folder, list, or task |
  129. | 🏢 **Workspace** | Spaces, folders, lists (full CRUD + rename + from template; subfolder parent IDs in JSON), members, user groups, task types, templates, plan, shared hierarchy |
  130. | 📎 **Attachments** | Upload files to tasks, list task attachments, shown in detail views |
  131. | 📦 **Export** | Archive tasks and docs as lossless JSON + markdown: by user, space, roadmap list (initiatives grouped), or whole workspace; comment threads, subtask trees, custom fields, attachment binaries |
  132. [Full API coverage details](docs/api-coverage.md) | [Command reference](docs/commands.md)
  133. ## Configuration
  134. ### Profiles
  135. Multiple profiles for different workspaces or accounts:
  136. ```bash
  137. cup profile add work # interactive setup
  138. cup profile add personal # another workspace
  139. cup profile list # show all profiles
  140. cup profile use personal # switch default
  141. cup tasks -p work # one-off profile override
  142. ```
  143. ### Config file
  144. `~/.config/cup/config.json` (or `$XDG_CONFIG_HOME/cup/config.json`):
  145. ```json
  146. {
  147. "defaultProfile": "work",
  148. "profiles": {
  149. "work": {
  150. "apiToken": "pk_...",
  151. "teamId": "12345678",
  152. "sprintFolderId": "optional"
  153. },
  154. "personal": {
  155. "apiToken": "pk_...",
  156. "teamId": "87654321"
  157. }
  158. }
  159. }
  160. ```
  161. Old flat configs (pre-profiles) are auto-migrated on first load.
  162. ### Environment variables
  163. Environment variables override config file values:
  164. | Variable | Description |
  165. | -------------- | ----------------------------------------------------------------- |
  166. | `CU_API_TOKEN` | ClickUp personal API token (`pk_`) |
  167. | `CU_TEAM_ID` | Workspace (team) ID |
  168. | `CU_PROFILE` | Profile name (overrides `defaultProfile`, overridden by `-p`) |
  169. | `CU_OUTPUT` | Set to `json` to force JSON output when piped (default: markdown) |
  170. When both `CU_API_TOKEN` and `CU_TEAM_ID` are set, the config file is not required. Useful for CI/CD and containerized agents.
  171. ```bash
  172. cup auth # verify setup
  173. ```
  174. ### Non-interactive setup
  175. For CI, scripts, and AI agents, you can skip the interactive prompts:
  176. ```bash
  177. # Write config directly
  178. cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID
  179. # Or use environment variables (no config file needed)
  180. export CU_API_TOKEN=pk_YOUR_TOKEN
  181. export CU_TEAM_ID=YOUR_TEAM_ID
  182. ```
  183. ## Troubleshooting
  184. **"No config file found"** - Run `cup init` to set up your API token and workspace.
  185. **"Config missing apiToken"** - Set `CU_API_TOKEN` environment variable or run `cup init`.
  186. **No output from `cup`** - Make sure you're on v1.5.2+. Older versions had a symlink bug. Update: `npm install -g @krodak/clickup-cli`
  187. **Sprint not detected** - Your sprint folder needs "sprint", "iteration", "cycle", or "scrum" in the name. Or pin it: `cup config set sprintFolderId <id>`. You can also favorite a sprint folder: `cup favorite add sprint-folder <id>`
  188. **Custom field filter fails** - `--field` requires `--list` to resolve field names to IDs: `cup tasks --list <id> --field "Sprint" "Week 1"`
  189. **Wrong workspace** - Switch profile: `cup profile use <name>` or use `-p <name>` for one command.
  190. ## Development
  191. ```bash
  192. npm install
  193. npm test # unit tests (vitest, tests/unit/)
  194. npm run test:e2e # e2e tests (tests/e2e/, requires CLICKUP_API_TOKEN in .env.test)
  195. npm run build # tsup -> dist/
  196. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.