cup - ClickUp CLI

A ClickUp CLI built for AI agents that also works well for humans. Outputs Markdown when piped (optimized for AI context windows), interactive tables when run in a terminal.

npm install -g @krodak/clickup-cli && cup init

cup is the binary name. The previous cu name was retired in v0.21.0 to avoid conflict with the Unix cu(1) utility.

Talk to your agent

Install the CLI, add the skill file to your agent, and it works with ClickUp. No API knowledge needed.

"Read task abc123, do the work, then mark it in review and leave a comment with the commit hash."

"What's my standup? What did I finish, what's in progress, what's overdue?"

"Create a subtask under the initiative for the edge case we found."

"Check my sprint and tell me what's behind schedule."

"Update the description with your findings and flag blockers in a comment."

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.

Why a CLI and not MCP?

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.

Install

You need Node 22+ and a ClickUp personal API token (pk_... from ClickUp Settings > Apps).

  npm

npm install -g @krodak/clickup-cli
cup init

  Homebrew

brew tap krodak/tap
brew install clickup-cli
cup init

Set up your agent

The package includes a skill file that teaches agents all available commands and when to use them. All three major coding agents support skills natively:

  Claude Code

Install as a plugin (recommended):

claude plugin add $(npm root -g)/@krodak/clickup-cli

This registers the skill under the clickup-cli: namespace. Claude loads it automatically when you work with ClickUp tasks.

Or install as a personal skill (no namespace prefix):

SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
mkdir -p ~/.claude/skills/clickup
cp "$SKILL/SKILL.md" ~/.claude/skills/clickup/SKILL.md

  Codex

Codex supports agent skills across CLI, IDE extension, and web. Skills use the same SKILL.md format with YAML frontmatter.

Install as a user skill (available across all your projects):

SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
mkdir -p ~/.agents/skills/clickup
cp "$SKILL/SKILL.md" ~/.agents/skills/clickup/SKILL.md

Or install as a project skill (checked into your repo):

SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
mkdir -p .agents/skills/clickup
cp "$SKILL/SKILL.md" .agents/skills/clickup/SKILL.md

You can also use the built-in installer: $skill-installer clickup

  OpenCode

SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
mkdir -p ~/.config/opencode/skills/clickup
cp "$SKILL/SKILL.md" ~/.config/opencode/skills/clickup/SKILL.md

What it covers

Full CRUD for the core ClickUp workflow:

Tasks - create, read, update, delete, duplicate, search, subtasks, assign, dependencies, links, multi-list, bulk status updates

Comments - post, edit, delete, threaded replies, notify all

Docs - list, read, create, edit, delete (v3 API)

Time Tracking - start/stop timer, log entries, list/update/delete history

Checklists - view, create, delete, add/edit/delete items

Custom Fields - list, set, remove values (dropdown, date, checkbox, text, etc.)

Tags - add/remove on tasks, space-level create/update/delete

Goals & OKRs - goals CRUD, key results CRUD

Sprints - auto-detect active sprint, flexible date parsing, config override

Workspace - spaces, folders, lists, members, task types, templates

Attachments - upload files to tasks, shown in detail views

Full API coverage details | Command reference

Output Modes

Most commands scope to your assigned tasks by default - keeping output small and relevant for agent context windows.

Configuration

Config file

~/.config/cup/config.json (or $XDG_CONFIG_HOME/cup/config.json):

{
  "apiToken": "pk_...",
  "teamId": "12345678",
  "sprintFolderId": "optional - folder ID to skip auto-detection"
}

Environment variables

Environment variables override config file values:

When both are set, the config file is not required. Useful for CI/CD and containerized agents.

Custom Task IDs

ClickUp workspaces can configure custom task IDs with a prefix per space (e.g., PROJ-123, DEV-42). The CLI detects these automatically - any ID matching the PREFIX-DIGITS format (uppercase letters, hyphen, digits) is treated as a custom task ID.

All commands that accept task IDs work with both native IDs and custom IDs:

cup task PROJ-123
cup update DEV-42 --status done
cup comment PROJ-456 -m "Fixed in latest commit"
cup subtasks DEV-100

Custom ID resolution uses the teamId from your config, which is required (cup init sets it up).

Task links with custom IDs: The cup link command passes both task IDs in a single API request. When both IDs are custom, this works correctly. However, mixing custom and native IDs in a single link command may not work as expected because the ClickUp API applies the custom_task_ids flag to all IDs in the request.

Development

npm install
npm test          # unit tests (vitest, tests/unit/)
npm run test:e2e  # e2e tests (tests/e2e/, requires CLICKUP_API_TOKEN in .env.test)
npm run build     # tsup -> dist/