clickup-cli 0.6.5

CLI for the ClickUp API, optimized for AI agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

---
layout: default
title: Home
nav_order: 1
---

# clickup-cli

A command-line interface for the [ClickUp API](https://clickup.com/api/), built in Rust and optimized for AI agents.

## The Problem

ClickUp's API returns deeply nested JSON. A single query for 5 tasks produces **~12,000 tokens** of data — statuses wrapped in objects, assignees as arrays of user objects, timestamps as Unix milliseconds, custom fields, checklists, dependencies, and more.

For AI agents operating within context windows (Claude Code, Cursor, Copilot, etc.), this is a serious problem. A few API calls can consume most of the available context, leaving little room for reasoning.

## The Solution

clickup-cli delivers **token-efficient output by default**:

```
┌─────────────────────────────┬──────────────┐
│ Full API JSON (5 tasks)     │ ~12,000 tokens │
│ clickup-cli table output    │    ~150 tokens │
│ Reduction                   │         ~98%   │
└─────────────────────────────┴──────────────┘
```

The CLI flattens nested objects (`status.status` → `"in progress"`), joins arrays (`assignees[].username` → `"Nick, Bob"`), converts timestamps (`1773652547089` → `"2026-03-17"`), and shows only essential fields.

When you need the full response, `--output json` is always available.

## Coverage

**130 endpoints** across **28 resource groups and 4 utility commands**, covering the entire ClickUp v2 and v3 API:

| Category | Resources |
|----------|-----------|
| **Core** | workspace, space, folder, list, task |
| **Collaboration** | comment, checklist, tag, field, task-type, attachment |
| **Tracking** | time, goal, view, member, user |
| **Communication** | chat (v3), doc (v3), webhook, template |
| **Admin** | guest, group, role, shared, audit-log, acl |
| **Utilities** | setup, auth, status, completions, agent-config, mcp |

## Quick Start

```bash
# Install (macOS)
brew tap nicholasbester/clickup-cli
brew install clickup-cli

# Configure
clickup setup --token pk_your_token_here

# Use
clickup task list --list 12345
clickup task create --list 12345 --name "My Task" --priority 3
clickup task get abc123
```

## AI Agent Integration

**Recommended: CLI Mode** — most token-efficient, LLM-agnostic. Inject a ~1,000 token command reference into your agent instructions file and the agent runs CLI commands directly. No tool schemas consuming context.
```bash
clickup agent-config inject   # Auto-detects: CLAUDE.md, agent.md, .cursorrules, etc.
```

**Alternative: MCP Mode** — for tools that prefer native tool integration (Claude Desktop, Cursor). MCP tool schemas consume more tokens than the CLI reference.
```json
{
  "mcpServers": {
    "clickup": { "command": "clickup", "args": ["mcp", "serve"] }
  }
}
```

## Features

- **Shell completions** for bash, zsh, fish, powershell
- **Environment variables** — `CLICKUP_TOKEN`, `CLICKUP_WORKSPACE` for CI/CD
- **Smart error handling** — exit codes, hints, plan upgrade suggestions for 403s
- **`clickup status`** — check current config at a glance

[Command Reference →](commands)  ·  [Installation →](install)  ·  [MCP Server →](mcp)  ·  [GitHub →](https://github.com/nicholasbester/clickup-cli)