JSPM

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

For AI Agents

Paste this into any AI agent to get started immediately:

Fetch and follow instructions from https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md

Or install the skill permanently with cup skill (see Set up your agent below).

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
cup auth  # verify setup

  Homebrew

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

Set up your agent

After installing cup, run:

cup skill

This detects which agents you have (Claude Code, Codex, OpenCode) and installs the skill file to the right locations. Run it again after updating cup to refresh the skill.

Manual install options

  Claude Code

Install as a plugin (recommended):

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

Or as a personal skill:

cup skill --path ~/.claude/skills/clickup/SKILL.md

  Codex

cup skill --path ~/.agents/skills/clickup/SKILL.md

Or for a project-level skill:

cup skill --path .agents/skills/clickup/SKILL.md

  OpenCode

cup skill --path ~/.config/opencode/skills/clickup/SKILL.md

 Other agents / npx

Without installing globally, you can use npx:

npx @krodak/clickup-cli skill --print > SKILL.md

Or install the skill directly from GitHub via the skills CLI:

npx skills add https://github.com/krodak/clickup-cli

What it covers

Full CRUD for the core ClickUp workflow:

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:

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

cup auth  # verify setup

Non-interactive setup

For CI, scripts, and AI agents, you can skip the interactive prompts:

# Write config directly
cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID

# Or use environment variables (no config file needed)
export CU_API_TOKEN=pk_YOUR_TOKEN
export CU_TEAM_ID=YOUR_TEAM_ID

Troubleshooting

"No config file found" - Run cup init to set up your API token and workspace.

"Config missing apiToken" - Set CU_API_TOKEN environment variable or run cup init.

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

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>

Custom field filter fails - --field requires --list to resolve field names to IDs: cup tasks --list <id> --field "Sprint" "Week 1"

Wrong workspace - Switch profile: cup profile use <name> or use -p <name> for one command.

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/