Clickup Cli Js

A CLI for the ClickUp API, optimized for AI agents.

Why?

ClickUp's API responses are massive — easily 12,000+ tokens for 5 tasks. This CLI flattens nested objects, selects essential fields, and renders compact output. ~98% token reduction vs raw JSON.

Improvements over the original:

• Type-preserving compact JSON — numbers stay numbers (priority: 3), booleans stay booleans (active: true), not stringified
• --max-chars — truncate long text values to cap token cost (default 60, 0=off)
• --output compact — pipe-delimited rows, no alignment padding (~20-35% smaller than tables)
• --summary — aggregate summary instead of rows (12 tasks: 4 Open, 6 In Progress | overdue: 3)
• count — just the number (task count --list X --status "in progress" → 4)
• --max-tokens — soft token budget cap with truncation footer

Install

npm install -g clickup-cli-js

Requires Node.js 18+.

Node.js SDK

The package also provides a side-effect-free ESM API for calling ClickUp from a Node.js or TypeScript application. Importing it does not start the CLI or parse your application's command-line arguments.

import { ClickUpClient, ClickUpError } from 'clickup-cli-js';

interface Task {
  id: string;
  name: string;
  status: { status: string };
}

const clickup = new ClickUpClient({
  token: process.env.CLICKUP_TOKEN!,
  timeoutSecs: 30,
});

try {
  const task = await clickup.get<Task>('/v2/task/TASK_ID');
  console.log(task.name);
} catch (error) {
  if (error instanceof ClickUpError) {
    console.error(error.kind, error.status, error.message);
  }
}

The SDK exposes generic get, post, put, patch, delete, deleteWithBody, and uploadFile methods. Paths are relative to https://api.clickup.com/api; for example, use /v2/user. The original new ClickUpClient(token, timeoutSecs) constructor remains supported.

Quick Start

# Configure your API token (interactive)
clickup-cli-js setup

# Or non-interactive
clickup-cli-js setup --token pk_your_token_here

# Verify
clickup-cli-js auth whoami

# Show current config
clickup-cli-js status

Usage

# Hierarchy navigation
clickup-cli-js workspace list
clickup-cli-js space list
clickup-cli-js folder list --space 12345
clickup-cli-js list list --folder 67890

# Task management
clickup-cli-js task list --list 12345
clickup-cli-js task create --list 12345 --name "My Task" --priority 3
clickup-cli-js task get abc123
clickup-cli-js task update abc123 --status "in progress"
clickup-cli-js task search --status "in progress" --assignee 44106202
clickup-cli-js task batch-update abc123 def456 --add-tag urgent --remove-tag stale

# Token-efficient modes
clickup-cli-js task list --list 12345 --output compact
clickup-cli-js task list --list 12345 --output brief
clickup-cli-js task list --list 12345 --summary
clickup-cli-js task count --list 12345 --status "in progress"
clickup-cli-js task list --list 12345 --max-tokens 200
clickup-cli-js task list --list 12345 --all --output-file /tmp/tasks.json

# Auto-detect task ID from git branch
clickup-cli-js task get          # resolves abc123 from feat/CU-abc123-foo
clickup-cli-js task update --status "in progress"

# Comments and collaboration
clickup-cli-js comment list --task abc123
clickup-cli-js comment create --task abc123 --text "Looking good!"
clickup-cli-js tag list --space 12345
clickup-cli-js field list --list 12345
clickup-cli-js field create --list 12345 --name "Release Version" --type short_text
clickup-cli-js field ensure "Priority" abc123 --value "High"

# Time tracking
clickup-cli-js time start --task abc123 --description "Working on feature"
clickup-cli-js time stop
clickup-cli-js time list --start-date 2026-03-01 --end-date 2026-03-31

# Views
clickup-cli-js view list --space 12345
clickup-cli-js view tasks VIEW_ID

Output Modes

Flag	Description
(default)	Aligned table with essential fields
--output compact	Pipe-delimited rows, no padding (agent-friendly)
--output json	Full API response, or filtered to --fields (raw values) if given
--output json-compact	Identical data to json (respects --fields the same way), minified instead of pretty-printed
--output brief	Flattened, lightweight JSON: id, name, status, tags, assignees, description by default (override with --fields) — no raw custom_fields or user objects
--output csv	CSV format
-q / --quiet	IDs only, one per line

Token-Efficiency Features

--fields restricts JSON too

--fields used to only trim table/compact/csv columns. It now restricts json/json-compact/brief output the same way — with no --fields, json/json-compact return the full raw item; with --fields, they return just those fields (raw values, custom fields resolved by name/UUID same as other modes):

clickup-cli-js task get abc123 --output json --fields id,name,status
# [{"id": "abc123", "name": "Fix bug", "status": {"status": "in progress", "color": "#d3d3d3"}}]

json and json-compact return identical data

They're now the same data, just formatted differently — json is pretty-printed, json-compact is minified. Pipe either through jq or JSON.parse and you get the same structure back.

Type-preserving compact JSON (--output brief + MCP)

Numbers and booleans stay native JSON types, not quoted strings, and nested objects/arrays are flattened to plain names — no raw custom_fields definitions or user objects:

clickup-cli-js task list --list 123 --output brief
# [{"id": "abc", "name": "Fix bug", "status": "in progress", "tags": "bug, urgent", "assignees": "alice, bob", "description": "..."}]

vs the original which stringified everything:

[{"id": "abc", "priority": "3", "active": "true", "name": "Fix bug"}]

--output-file <path>

Writes the full response to a file instead of stdout, so large listings survive a terminal or calling tool that truncates output. Stdout gets a short notice instead of the full data:

clickup-cli-js task list --list 123 --all --output-file /tmp/tasks.json
# {"output_file":"/tmp/tasks.json","count":842,"bytes":193021}

Pagination metadata

If more results exist beyond what was fetched (because --all wasn't passed, or the 100-page safety cap was hit), an extra note is printed after the results:

clickup-cli-js task list --list 123
# ...rows...
# Note: more results available. Pass --all to fetch everything.

In json/json-compact/brief modes the same information is a trailing JSON line: {"pagination":{"has_more":true,"hint":"..."}}.

--max-chars N (default 60)

Truncates long text values with …:

clickup-cli-js task list --list 123 --max-chars 30   # truncate to 30 chars
clickup-cli-js task list --list 123 --max-chars 0    # no truncation

--output compact

Pipe-delimited rows without alignment padding:

id|name|status|priority|assignees|due_date
abc123|Fix bug|Open|3|alice, bob|2026-03-17

--summary

Aggregate summary instead of rows:

clickup-cli-js task list --list 123 --summary
# 12 tasks: 4 Open, 6 In Progress, 2 Done | overdue: 3 | assignees: alice(5), bob(4), unassigned(3)

count

Just the number:

clickup-cli-js task count --list 123 --status "in progress"
# 4

--max-tokens N

Soft token budget — returns rows that fit + a truncation footer:

clickup-cli-js task list --list 123 --max-tokens 200
# ...rows...
# {"truncated":true,"shown":15,"total":87}

Command Groups

Group	Commands
setup	Configure token and workspace
auth	whoami, check
workspace	list, seats, plan
space	list, get, create, update, delete
folder	list, get, create, update, delete
list	list, get, create, update, delete, add-task, remove-task
task	list, search, get, create, update, delete, time-in-status, add-tag, remove-tag, add-dep, remove-dep, link, unlink, move, set-estimate, replace-estimates, count, batch-update
comment	list, create, update, delete, replies, reply
tag	list, create, update, delete
field	list, create, set, unset, ensure
time	list, get, current, create, update, delete, start, stop, tags, add-tags, remove-tags, rename-tag, history
view	list, get, create, update, delete, tasks
member	list
user	invite, get, update, remove (Enterprise)
status	Show current config
mcp	serve — MCP server for LLM tool integration

Global Flags

Flag	Description
--token TOKEN	Override config file token
--workspace ID	Override default workspace
--output MODE	table, compact, json, json-compact, csv, brief
--fields LIST	Comma-separated field names (restricts JSON output too)
--output-file PATH	Write full response to a file; stdout gets a short notice
--no-header	Omit table header row
--all	Fetch all pages
--limit N	Cap total results
--page N	Manual page (v2 page-based)
--cursor X	Manual cursor (v3 cursor-based)
--start MS + --start-id ID	Boundary pair (v2 comment endpoints)
-q / --quiet	IDs only
--timeout SECS	HTTP timeout (default 30)
--max-chars N	Max chars per text value (default 60, 0=off)
--max-tokens N	Soft token budget cap

Auto-detect Task ID from Git Branch

When a task-scoped command runs without an explicit ID, the CLI resolves the ID from the current git branch:

• feat/CU-abc123-foo → abc123
• PROJ-42-add-login → PROJ-42 (custom task ID, auto-injects custom_task_ids=true&team_id=<ws>)

Resolution order: explicit arg → CLICKUP_TASK_ID env var → git branch.

Destructive commands (task delete, task link, task unlink) never auto-detect — pass the ID explicitly.

Disable with CLICKUP_GIT_DETECT=0 env var.

Destructive Confirmations

Delete operations (task delete, space delete, folder delete, list delete, comment delete, tag delete, time delete, view delete, user remove) require confirmation:

• Interactive (TTY): prompts with @inquirer/prompts confirm
• Non-interactive (CI/non-TTY): refuses unless --yes is passed

clickup-cli-js task delete abc123 --yes   # skip confirmation

MCP Server

The CLI includes an MCP (Model Context Protocol) server for LLM tool integration:

clickup-cli-js mcp serve

Exposes 62 tools covering all implemented ClickUp API endpoints. Responses use type-preserving compact JSON for token efficiency.

Add to your MCP client config (e.g., .mcp.json):

{
  "mcpServers": {
    "clickup": {
      "command": "clickup-cli-js",
      "args": ["mcp", "serve"]
    }
  }
}

Limiting MCP Tools

clickup-cli-js mcp serve --read-only
clickup-cli-js mcp serve --groups task,comment,time
clickup-cli-js mcp serve --profile safe
clickup-cli-js mcp serve --exclude-tools clickup_task_delete

Or via environment variables: CLICKUP_MCP_PROFILE, CLICKUP_MCP_READ_ONLY, CLICKUP_MCP_GROUPS, CLICKUP_MCP_EXCLUDE_GROUPS, CLICKUP_MCP_TOOLS, CLICKUP_MCP_EXCLUDE_TOOLS.

Configuration

Config Files

Level	File
Project	.clickup.json (current directory, walks up)
Global	~/.config/clickup-cli/config.json (Linux) or ~/Library/Preferences/clickup-cli/config.json (macOS)

{
  "auth": { "token": "pk_..." },
  "defaults": { "workspace_id": "12345" },
  "git": { "enabled": true, "verbose": true }
}

Token Resolution (highest priority wins)

1. --token CLI flag
2. CLICKUP_TOKEN environment variable
3. .clickup.json (project-level)
4. Global config

Workspace Resolution

1. --workspace CLI flag
2. CLICKUP_WORKSPACE environment variable
3. .clickup.json (project-level)
4. Global config

Exit Codes

Code	Meaning
0	Success
1	Client error (bad input)
2	Auth/permission error (401, 403)
3	Not found (404)
4	Rate limited (429)
5	Server error (5xx)
6	Network error (DNS/connection failure — request never reached ClickUp)
7	Timeout (exceeded --timeout)

Free-form Text Flags

Flags like --description, --text, --content accept:

• @path — read value from a file
• @- — read value from stdin
• @@text — literal text starting with @
• anything else — used verbatim

Attribution

This project is a TypeScript port of clickup-cli by Nicholas Bester, a Rust CLI for the ClickUp API. The command structure, API endpoint mappings, git-branch task-ID detection, pagination strategies, and token-efficient output philosophy are derived from the original project, which is licensed under Apache-2.0.

License

Apache-2.0