clickup-cu

Fast zero-dependency ClickUp CLI for daily task control from terminal or Pi.

cu today
cu start TASK_ID
cu stop
cu estimate TASK_ID 2h
cu done TASK_ID

TASK_ID, PARENT_TASK_ID, USER_ID, WORKSPACE_ID, and LIST_ID are placeholders. Replace them with your ClickUp values.

Why

Use cu when opening ClickUp just to check tasks, start/stop timers, change status, or set estimates feels slow.

cu talks directly to the ClickUp REST API:

Terminal/Pi -> cu -> ClickUp REST API

It is faster and simpler than using MCP for daily repeated actions. Use ClickUp UI or MCP for rare/complex operations.

Install

Requires Node.js 18+.

npm install -g clickup-cu
cu help

Use global install. Local install inside another project usually is not needed.

If another system cu exists, check PATH:

command -v cu      # macOS/Linux
where.exe cu       # Windows

Setup

Get a ClickUp API token:

ClickUp -> Profile/avatar -> Settings -> Apps -> API Token -> Generate

Save it:

cu token pk_your_token_here

Then create config:

cu init

Files:

~/.config/cu/token
~/.config/cu/config.json

Both are written with owner-only permissions (0600). Environment variables also work and override the token file:

export CLICKUP_API_TOKEN="pk_your_token_here"
# or
export CLICKUP_TOKEN="pk_your_token_here"

Example config:

{
  "workspaceId": "YOUR_WORKSPACE_ID",
  "userId": "YOUR_USER_ID",
  "defaultListId": "YOUR_LIST_ID",
  "statuses": {
    "backlog": "BACKLOG",
    "todo": "TO-DO",
    "start": "IN PROGRESS",
    "review": "REVIEW",
    "qa": "QA/TESTING",
    "blocked": "BLOCKED",
    "release": "READY FOR RELEASE",
    "done": "DONE"
  }
}

Daily workflow

cu today                         # dashboard: timer + due/active/blocked/open tasks
cu list                          # list your open tasks
cu list all                      # list open tasks without assignee filter
cu list status "IN PROGRESS"     # list by status
cu show TASK_ID                  # show task details

cu start TASK_ID                 # set IN PROGRESS + start timer
cu progress TASK_ID              # set IN PROGRESS only
cu stop                          # stop current timer
cu done TASK_ID                  # set DONE

Status shortcuts:

cu backlog TASK_ID
cu todo TASK_ID
cu review TASK_ID
cu qa TASK_ID
cu testing TASK_ID
cu blocked TASK_ID
cu release TASK_ID

Time:

cu estimate TASK_ID 2h
cu estimate TASK_ID 2h 30m
cu estimate TASK_ID 45m
cu addtime TASK_ID 45m "backend work"

Create/update:

cu create "Fix login bug"
cu subtask PARENT_TASK_ID "Add API validation"
cu assign TASK_ID me
cu assign TASK_ID USER_ID ANOTHER_USER_ID

Commands

Command	Purpose
cu today	Daily dashboard
cu list [all]	List tasks
cu list status "STATUS"	List tasks by status
cu show TASK_ID	Show one task
cu start TASK_ID	Set start status + start timer
cu stop	Stop current timer
cu backlog/todo/progress/review/qa/testing/blocked/release/done TASK_ID	Change status
cu estimate TASK_ID DURATION	Set estimate
cu addtime TASK_ID DURATION [note]	Add manual time
cu create "TITLE"	Create task in default list
cu subtask PARENT_TASK_ID "TITLE"	Create subtask
cu assign TASK_ID USER_ID_OR_ME...	Add assignees
cu token pk_your_token_here	Save token
cu init	Create/show config
cu help	Show help

Durations support 2h, 30m, 2h 30m. Plain numbers mean minutes.

Pi shortcut

This package includes /cu-fast for Pi.

pi install npm:clickup-cu

Restart Pi or run:

/reload

Use:

/cu-fast
/cu-fast today
/cu-fast start TASK_ID
/cu-fast stop
/cu-fast show TASK_ID
/cu-fast estimate TASK_ID 2h
/cu-fast done TASK_ID

/cu-fast runs local cu through bash after validating arguments, so install and configure the CLI too:

npm install -g clickup-cu
cu token pk_your_token_here
cu init

Safety rules for /cu-fast:

• It only allows known cu subcommands.
• It rejects shell metacharacters, newlines, pipes, redirects, and command chaining.
• It shell-quotes validated arguments before bash execution.
• It treats ClickUp task content as untrusted output, not instructions.

REST mapping

CLI action	REST API
cu today timer	GET /team/{workspaceId}/time_entries/current
cu today/list tasks	GET /team/{workspaceId}/task?...
cu show TASK_ID	GET /task/{taskId}
status commands	PUT /task/{taskId}
cu start TASK_ID timer	POST /team/{workspaceId}/time_entries/start
cu stop	POST /team/{workspaceId}/time_entries/stop
cu estimate TASK_ID DURATION	PUT /task/{taskId} with time_estimate
cu addtime TASK_ID DURATION	POST /team/{workspaceId}/time_entries
cu create "TITLE"	POST /list/{defaultListId}/task
cu subtask PARENT_TASK_ID "TITLE"	POST /list/{listId}/task with parent
cu assign TASK_ID USER_ID_OR_ME...	POST /task/{taskId}/assignee

Development

git clone https://github.com/YOUR_USER/cu.git
cd cu
npm install -g .
npm test
npm pack --dry-run

Publish:

npm version patch
npm publish --access public

Security

• Never commit ~/.config/cu/token.
• Never paste pk_... in chat, issues, logs, screenshots, or recordings.
• Each teammate should generate their own token.
• Rotate exposed tokens.