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

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.

Agent mode

When piped (no TTY), output is Markdown optimized for AI context windows. Pass --json for structured data.

Terminal mode

In a terminal, you get interactive tables with colors. Most commands scope to your assigned tasks by default.

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

 Other agents

The skill file follows the Agent Skills open standard. Copy skills/clickup-cli/SKILL.md into your agent's skill directory, system prompt, or AGENTS.md.

What it covers

Full CRUD for the core ClickUp workflow:

Area	Capabilities
✅ 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, create, 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 (read + create), members, task types, templates
📎 Attachments	Upload files to tasks, shown in detail views

Full API coverage details | Command reference

Configuration

Profiles

Multiple profiles for different workspaces or accounts:

cup profile add work        # interactive setup
cup profile add personal    # another workspace
cup profile list            # show all profiles
cup profile use personal    # switch default
cup tasks -p work           # one-off profile override

Config file

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

{
  "defaultProfile": "work",
  "profiles": {
    "work": {
      "apiToken": "pk_...",
      "teamId": "12345678",
      "sprintFolderId": "optional"
    },
    "personal": {
      "apiToken": "pk_...",
      "teamId": "87654321"
    }
  }
}

Old flat configs (pre-profiles) are auto-migrated on first load.

Environment variables

Environment variables override config file values:

Variable	Description
CU_API_TOKEN	ClickUp personal API token (pk_)
CU_TEAM_ID	Workspace (team) ID
CU_PROFILE	Profile name (overrides defaultProfile, overridden by -p)
CU_OUTPUT	Set to json to force JSON output when piped (default: markdown)

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

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/