Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@krodak/clickup-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

cu - 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 && cu 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 cu commands, and handles everything. You don't need to learn the CLI - the agent does.

Install

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

npm

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

Homebrew

brew tap krodak/tap
brew install clickup-cli
cu 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.

API Coverage

Full command reference with examples and flags.

Status: ✅ implemented | 🚧 planned | 🚫 won't add

Tasks

Feature	Command	Status
List my tasks	`cu tasks`	✅
Get task details	`cu task <id>`	✅
Create task	`cu create`	✅
Update task	`cu update <id>`	✅
Delete task	`cu delete <id>`	✅
Search tasks	`cu search <query>`	✅
Open in browser	`cu open <query>`	✅
List subtasks	`cu subtasks <id>`	✅
Assign / unassign	`cu assign <id>`	✅
Duplicate task	`cu duplicate <id>`	🚧
Create from template	`cu create --template`	🚧
Bulk operations	`cu bulk`	🚧

Dependencies & Relations

Feature	Command	Status
Add dependency	`cu depend <id>`	✅
Remove dependency	`cu depend <id> --remove`	✅
Add/remove task link	`cu link <id> <linksTo>`	✅

Multi-list

Feature	Command	Status
Add task to list	`cu move <id> --add`	✅
Remove from list	`cu move <id> --remove`	✅

Sprints & Planning

Feature	Command	Status
Active sprint tasks	`cu sprint`	✅
List all sprints	`cu sprints`	✅
Assigned tasks by status	`cu assigned`	✅
Standup summary	`cu summary`	✅
Overdue tasks	`cu overdue`	✅
Recently updated	`cu inbox`	✅

Comments

Feature	Command	Status
List comments	`cu comments <id>`	✅
Post comment	`cu comment <id>`	✅
Edit comment	`cu comment-edit <id>`	✅
Task + comments combined	`cu activity <id>`	✅
Delete comment	`cu comment-delete <id>`	✅
Threaded replies	`cu replies <id>` / `cu reply <id>`	✅

Checklists

Feature	Command	Status
View checklists	`cu checklist view <id>`	✅
Create checklist	`cu checklist create <id> <name>`	✅
Delete checklist	`cu checklist delete <id>`	✅
Add item	`cu checklist add-item <id> <name>`	✅
Edit item	`cu checklist edit-item <id> <itemId>`	✅
Delete item	`cu checklist delete-item <id> <itemId>`	✅

Custom Fields

Feature	Command	Status
Set field value	`cu field <id> --set`	✅
Remove field value	`cu field <id> --remove`	✅
List available fields	`cu fields <listId>`	🚧

Feature	Command	Status
Add/remove tag on task	`cu tag <id>`	✅
List space tags	`cu tags <spaceId>`	🚧
Create/delete space tag		🚧

Time Tracking

Feature	Command	Status
Start timer	`cu time start <id>`	✅
Stop timer	`cu time stop`	✅
Timer status	`cu time status`	✅
Log time entry	`cu time log <id> <duration>`	✅
List entries	`cu time list`	✅
Update entry	`cu time update <id>`	🚧
Delete entry	`cu time delete <id>`	🚧

Workspace

Feature	Command	Status
List spaces	`cu spaces`	✅
List lists	`cu lists <spaceId>`	✅
Check auth	`cu auth`	✅
List folders	`cu folders <spaceId>`	🚧
List members	`cu members`	🚧

Goals & Key Results

Feature	Command	Status
List goals	`cu goals`	🚧
Create/update goal		🚧
Key results CRUD		🚧

Docs

Feature	Command	Status
Search docs	`cu docs <query>`	🚧
View page content	`cu doc <id>`	🚧

Attachments

Feature	Command	Status
Upload file	`cu attach <id> <file>`	✅
List attachments	shown inline in `cu task`	✅

🚫 Won't add

Feature	Why
Webhooks	Server-side. A CLI can't listen for events.
OAuth flow	`cu init` already handles auth with API tokens.
Guest/ACL	Enterprise admin. Not what you reach for in a terminal.
Chat/DM	Use the ClickUp app. Chat doesn't belong in a CLI.
Audit logs	Enterprise admin.
User/group management	Too destructive for a CLI - removing someone from a workspace is permanent.
View CRUD	Views are visual layouts. Configure them in the UI.

Setup

Feature	Command	Status
First-time setup	`cu init`	✅
Get/set config	`cu config`	✅
Shell completions	`cu completion <shell>`	✅

Output Modes

Context	Default	Override
Terminal (TTY)	Interactive tables + picker	`--json`
Piped (no TTY)	Markdown (optimized for AI)	`--json` or `CU_OUTPUT=json`

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

Configuration

Config file

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

{
  "apiToken": "pk_...",
  "teamId": "12345678"
}

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_OUTPUT`	Set to `json` to force JSON output when piped (default: markdown)

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

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.

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/

@krodak/clickup-cli