clickup-cu

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

Purpose

ClickUp is powerful, but daily task navigation can be slow when you repeatedly open the browser to find tasks, start/stop timers, update status, or set estimates. clickup-cu gives developers and CLI-heavy teams a small command-line workflow for the actions they do many times every day.

Use it to:

• see today's work without opening ClickUp
• start a task and time tracker in one command
• stop the active timer from terminal
• set time estimates quickly
• add manual time entries
• create tasks/subtasks from CLI
• use the same workflow inside Pi with /cu-fast

cu today
cu start test-task-id
cu stop
cu estimate test-task-id 2h

Description

cu is a zero-dependency Node.js CLI that talks directly to the ClickUp REST API. It reads your local ClickUp token/config, calls the API, and prints compact output designed for daily developer workflow.

It is not a full ClickUp replacement. It focuses on common high-frequency actions. For rare or complex ClickUp operations, you can still use ClickUp UI or MCP.

Why direct REST API instead of MCP for daily commands:

cu:  Terminal/Pi -> local cu script -> ClickUp REST API
MCP: Pi -> MCP adapter -> remote MCP server -> ClickUp

cu has fewer layers, less tool/schema overhead, and works outside Pi too.

Install

Global install (recommended)

Install clickup-cu globally so the cu command works from any terminal and any project directory:

npm install -g clickup-cu

Check:

cu help
which cu

Use global install, not local project install:

# good
npm install -g clickup-cu

# avoid inside another project/monorepo
npm install clickup-cu
npm i clickup-cu

Local install adds clickup-cu to the current project dependencies and can fail if that project has workspace/package issues. Global install puts the cu executable on your shell PATH for everyday CLI use.

Setup

1. Get ClickUp API token

ClickUp app:

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

Token looks like pk_....

2. Save token locally

cu token pk_test_token_here

Stored at:

~/.config/cu/token

Do not commit/share this token.

3. Create config

cu init

Config path:

~/.config/cu/config.json

Example:

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

Field	Meaning
workspaceId	ClickUp Workspace/Team ID
userId	Your ClickUp user ID for “my tasks”
defaultListId	List used by cu create
statuses.backlog	Status used by cu backlog
statuses.todo	Status used by cu todo
statuses.start	Status used by cu start and cu progress
statuses.review	Status used by cu review
statuses.qa	Status used by cu qa / cu testing
statuses.blocked	Status used by cu blocked
statuses.release	Status used by cu release
statuses.done	Status used by cu done

Daily use from terminal

Start your day:

cu today

Shows:

• running timer
• due / overdue tasks
• active tasks
• blocked tasks
• not-started tasks
• quick next commands

Start a task:

cu start test-task-id

Stops context switching:

• sets status to IN PROGRESS
• starts ClickUp timer

Stop timer:

cu stop

Show one task:

cu show test-task-id

Move task through statuses:

cu backlog test-task-id
cu todo test-task-id
cu progress test-task-id
cu review test-task-id
cu qa test-task-id
cu blocked test-task-id
cu release test-task-id
cu done test-task-id

Set estimate:

cu estimate test-task-id 2h
cu estimate test-task-id 2h 30m
cu estimate test-task-id 45m

Add manual time:

cu addtime test-task-id 45m "backend work"

Create task in default list:

cu create "Fix login bug"

Create subtask:

cu subtask test-task-id "Add API validation"

Assign people:

cu assign test-task-id me
cu assign test-task-id test-user-id another-test-user-id

Current assign command supports numeric user IDs or me.

Commands

Command	Purpose
cu today	Daily dashboard
cu list	List your open tasks
cu list all	List open tasks without assignee filter
cu list status "IN PROGRESS"	List tasks by status
cu show <id>	Show task details
cu start <id>	Set IN PROGRESS + start timer
cu stop	Stop current timer
cu backlog <id>	Set BACKLOG
cu todo <id>	Set TO-DO
cu progress <id>	Set IN PROGRESS
cu review <id>	Set REVIEW
cu qa <id>	Set QA/TESTING
cu blocked <id>	Set BLOCKED
cu release <id>	Set READY FOR RELEASE
cu done <id>	Set DONE
cu estimate <id> <duration>	Set time estimate
cu addtime <id> <duration> [note]	Add manual time entry
cu create <title>	Create task in default list
cu subtask <parent-id> <title>	Create subtask
`cu assign <user-id	me...>`
cu token <pk_xxx>	Save token
cu init	Create/show config

Use inside Pi

This package also includes Pi prompt:

/cu-fast

Install Pi package:

pi install npm:clickup-cu

Then restart Pi or run:

/reload

Use:

/cu-fast today
/cu-fast start test-task-id
/cu-fast stop
/cu-fast estimate test-task-id 2h

Pi flow:

/cu-fast today -> Pi runs bash: cu today -> ClickUp REST API

Important: Pi shortcut needs CLI installed too:

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

How it works internally

Architecture:

Terminal or Pi
  -> cu command
  -> ~/.config/cu/config.json
  -> ~/.config/cu/token or CLICKUP_API_TOKEN
  -> ClickUp REST API
  -> formatted terminal output

Base API:

https://api.clickup.com/api/v2

Every request sends:

Authorization: pk_your_token
Content-Type: application/json

Main internal helper:

async function api(method, endpoint, body) {
  const res = await fetch(`${API}${endpoint}`, {
    method,
    headers: {
      Authorization: TOKEN,
      'Content-Type': 'application/json',
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  return await res.json();
}

Common REST calls:

CLI action	REST API
cu today timer	GET /team/{workspaceId}/time_entries/current
cu today tasks	GET /team/{workspaceId}/task?...&assignees[]={userId}
cu show	GET /task/{taskId}
cu start status	PUT /task/{taskId}
status commands (cu backlog, cu todo, cu progress, cu review, cu qa, cu blocked, cu release, cu done)	PUT /task/{taskId}
cu start timer	POST /team/{workspaceId}/time_entries/start
cu stop	POST /team/{workspaceId}/time_entries/stop
cu estimate	PUT /task/{taskId} with time_estimate
cu create	POST /list/{defaultListId}/task
cu subtask	POST /list/{listId}/task with parent

MCP alternative

You can control ClickUp through MCP too. It works, but is usually slower for daily actions.

MCP route:

Pi -> pi-mcp-adapter -> mcp-remote -> ClickUp MCP -> ClickUp

Example MCP config:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickup.com/mcp"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    }
  }
}

Then ask Pi:

list my ClickUp tasks
start timer on task test-task-id
stop current ClickUp timer
set estimate of test-task-id to 2h

Use MCP for rare/complex ClickUp actions. Use cu for daily fast workflow.

Use case	Recommended
daily dashboard	cu today
start/stop timer	cu start, cu stop
estimates/manual time	cu estimate, cu addtime
complex search/docs/workspace actions	MCP

Publish / development

Local dev:

git clone https://github.com/YOUR_USER/clickup-cu.git
cd clickup-cu
npm install -g .
cu help

Checks:

npm test
npm pack --dry-run

Publish:

npm login
npm publish --access public

If updating existing npm package:

npm version patch
npm publish --access public

Security

• Never commit ~/.config/cu/token.
• Never paste pk_... in chat/issues/logs.
• Each teammate should generate their own token.
• Rotate token if exposed.