clickup-cli

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:

Full API JSON for 5 tasks:  ~12,000 tokens (450 lines)
clickup-cli table output:      ~150 tokens (7 lines)
Reduction:                          ~98%

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, clickup-cli gives AI agents a simple, predictable interface to ClickUp: clickup <resource> <action> [ID] [flags]. No SDK, no auth boilerplate, no JSON parsing — just shell commands with structured output.

Install

npm (any platform with Node.js)

npm install -g @nick.bester/clickup-cli

macOS (Homebrew)

brew tap nicholasbester/clickup-cli
brew install clickup-cli

To upgrade to the latest version:

brew upgrade clickup-cli

macOS / Linux (pre-built binary)

Download the latest release for your platform:

# macOS Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-macos-arm64.tar.gz | tar xz
sudo mv clickup /usr/local/bin/

# macOS Intel
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-macos-x86_64.tar.gz | tar xz
sudo mv clickup /usr/local/bin/

# Linux x86_64
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-linux-x86_64.tar.gz | tar xz
sudo mv clickup /usr/local/bin/

# Linux ARM64
curl -L https://github.com/nicholasbester/clickup-cli/releases/latest/download/clickup-linux-arm64.tar.gz | tar xz
sudo mv clickup /usr/local/bin/

Windows

Download clickup-windows-x86_64.zip from the latest release, extract it, and add clickup.exe to your PATH.

From crates.io (any platform)

Requires Rust 1.70+:

cargo install clickup-cli

Docker

docker build -t clickup-cli .
docker run -i --rm -e CLICKUP_TOKEN=pk_xxx -e CLICKUP_WORKSPACE=12345 clickup-cli mcp serve

From source

git clone https://github.com/nicholasbester/clickup-cli.git
cd clickup-cli
cargo install --path .

Verify installation

clickup --version
# clickup 0.6.1

Quick Start

# Configure your API token
clickup setup

# Or non-interactive
clickup setup --token pk_your_token_here

# Verify
clickup auth whoami

Usage Examples

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

# Task management
clickup task list --list 12345
clickup task create --list 12345 --name "My Task" --priority 3
clickup task get abc123
clickup task update abc123 --status "in progress"
clickup task search --status "in progress" --assignee 44106202

# Comments and collaboration
clickup comment list --task abc123
clickup comment create --task abc123 --text "Looking good!"
clickup comment reply COMMENT_ID --text "Thanks!"

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

# Goals and views
clickup goal list
clickup view list --space 12345
clickup view tasks VIEW_ID

# Tags and custom fields
clickup tag list --space 12345
clickup field list --list 12345
clickup field set TASK_ID FIELD_ID --value "some value"

# Chat (v3)
clickup chat channel-list
clickup chat message-send --channel CHAN_ID --text "Hello team"

# Docs (v3)
clickup doc list
clickup doc get DOC_ID

# Output modes
clickup task list --list 12345 --output json        # Full JSON
clickup task list --list 12345 --output json-compact # Default fields as JSON
clickup task list --list 12345 --output csv          # CSV
clickup task list --list 12345 -q                    # IDs only
clickup task list --list 12345 --fields id,name,status  # Custom fields

Command Groups

AI Agent Integration

Two ways to connect AI agents to ClickUp:

Recommended: CLI Mode (shell commands)

The CLI approach is the most token-efficient way to give an agent ClickUp access. Injecting the command reference costs ~1,000 tokens once, and every command returns compact table output (~150 tokens for 5 tasks). There are no tool schemas consuming context. Works with any LLM/agent framework.

clickup agent-config inject            # Auto-detects: CLAUDE.md, agent.md, .cursorrules, etc.
clickup agent-config inject AGENT.md   # Or specify any file explicitly
clickup agent-config show              # Preview the block

Auto-detection checks for existing files in order: CLAUDE.md, agent.md, AGENT.md, .cursorrules, .github/copilot-instructions.md. Falls back to creating CLAUDE.md if none exist.

The agent then runs CLI commands directly — the full ClickUp API in ~1,000 tokens of instructions.

Alternative: MCP Server (native tool calls)

For Claude Desktop, Cursor, and other MCP-capable tools that prefer native tool integration. Note: MCP tool schemas consume more tokens in the agent's context than the CLI reference approach.

Generate the MCP config automatically:

clickup agent-config init --mcp

Or add .mcp.json to your project root manually:

{
  "mcpServers": {
    "clickup-cli": {
      "command": "/opt/homebrew/bin/clickup",
      "args": ["mcp", "serve"]
    }
  }
}

This exposes 143 tools covering 100% of the ClickUp API as native tool calls with token-efficient compact responses. See the MCP documentation for full setup.

Configuration

Config Files

Create a project-level config:

clickup agent-config init --token pk_xxx --workspace 12345

This creates .clickup.toml in the current directory. Add it to .gitignore if it contains a token. Project config takes priority over global config.

Token Resolution (highest priority wins)

1. --token CLI flag
2. CLICKUP_TOKEN environment variable
3. .clickup.toml (project-level)
4. ~/.config/clickup-cli/config.toml (global)

Workspace Resolution

1. --workspace CLI flag
2. CLICKUP_WORKSPACE environment variable
3. .clickup.toml (project-level)
4. ~/.config/clickup-cli/config.toml (global)

Check Current Config

clickup status

clickup-cli v0.6.1

Config:    ~/.config/clickup-cli/config.toml
Token:     pk_441...RB4Y
Workspace: 2648001

Shell Completions

# Bash
clickup completions bash > ~/.bash_completion.d/clickup

# Zsh
clickup completions zsh > ~/.zfunc/_clickup

# Fish
clickup completions fish > ~/.config/fish/completions/clickup.fish

# PowerShell
clickup completions powershell > clickup.ps1

Output Modes

Exit Codes

License

BSL 1.1 (Business Source License) — free to use, contributions welcome. Creating competing commercial products requires permission from the author. Converts to Apache 2.0 on 2030-04-01.