nicholasbester/clickup-cli

A CLI for the ClickUp API , optimized for AI agents and human users.
Covers all ~130 endpoints across 28 resource groups and 4 utility commands.
Documentation
Why?
ClickUp's API responses are massive. A single task list query returns deeply nested JSON — statuses, assignees, priorities, custom fields, checklists, dependencies — easily **12,000+ tokens** for just 5 tasks. For AI agents (Claude Code, Cursor, Copilot, etc.) operating within context windows, this is a serious problem: a few API calls can consume most of an agent's available context.
clickup-cli solves this with **token-efficient output by default**:
The CLI flattens nested objects, selects only essential fields, and renders compact tables. Agents get the information they need without drowning in JSON. When you need the full response, --output json is always available.
Beyond token efficiency, the clickup-cli CLI (or clkup for short) gives AI agents a simple, predictable interface to ClickUp: clickup-cli [ID] [flags]. No SDK, no auth boilerplate, no JSON parsing — just shell commands with structured output.
Install
npm (any platform with Node.js)
Homebrew (macOS or Linux)
To upgrade to the latest version:
Works on Linux too — the tap ships native x86_64 and arm64 Linux binaries.
macOS / Linux (pre-built binary)
Download the latest release for your platform:
**Alpine / musl Linux:**
Arch Linux (AUR)
clickup-cli-bin wraps the prebuilt Linux binaries — no Rust toolchain required. Auto-updated on every release.
Windows
Download clickup-windows-x86_64.zip from the latest release, extract it, and add clickup-cli.exe (and optionally clkup.exe) to your PATH.
From crates.io (any platform)
Requires Rust 1.70+:
Docker
From source
Two binaries
Every install method ships **two** binaries with identical behaviour:
- clickup-cli — canonical name (use this in scripts, CI, MCP configs)
- clkup — short alias, handy for daily interactive typing
Pick whichever you prefer; both accept the same flags and subcommands.
Verify installation
Quick Start
Usage Examples
Auto-detect task ID from git branch
When a git-tracked branch follows a common naming convention, clickup-cli resolves the task ID automatically:
- ClickUp default IDs — feat/CU-abc123-foo → abc123
- Custom task IDs — PROJ-42-add-login → PROJ-42 (auto-injects custom_task_ids=true&team_id= )
Prefixes stripped case-insensitively: feature/, feat/, fix/, hotfix/, bugfix/, release/, chore/, docs/, refactor/, test/, ci/, perf/, build/, style/. Custom-ID matches whose prefix is FEATURE, FEAT, BUGFIX, BUG, FIX, HOTFIX, RELEASE, CHORE, DOCS, DOC, REFACTOR, TEST, CI, PERF, BUILD, STYLE, WIP, or TMP are rejected.
Resolution order (highest priority first): explicit CLI arg → CLICKUP_TASK_ID env var → git branch. Explicit CU-abc123 is transparently stripped to abc123. Destructive or ambiguous commands (task delete, task link, task unlink, guest share-task, guest unshare-task) never auto-detect — pass the ID explicitly.
Disable for one invocation with CLICKUP_GIT_DETECT=0, or permanently in config:
Command Groups
| Group | Commands |
|-------|----------|
| setup | Configure token and workspace |
| auth | whoami, check, login, logout, status |
| 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 |
| checklist | create, update, delete, add-item, update-item, delete-item |
| comment | list, create, update, delete, replies, reply |
| tag | list, create, update, delete |
| field | list, set, unset |
| task-type | list |
| attachment | list, upload |