ClickUp CLI

JSON-first, agent-native CLI for the ClickUp API v2.

ClickUp has no official CLI for its project management API. This CLI fills that gap — covering workspaces, spaces, folders, lists, tasks, comments, time tracking, goals, webhooks, and more. Every command returns structured JSON, works from the terminal and as an MCP tool — so your AI agents can manage your entire ClickUp workspace the same way a human would from the command line.

Why Agent-Native?

| | clickup-cli (This) | |---|---| | Scope | Full ClickUp API v2 — 105 commands across 19 groups | | Output | JSON-first — machine-parseable by default | | MCP Support | Built-in MCP server — every command is an MCP tool | | Agent Use | Every command works identically from terminal or MCP | | Auth | API token (3-tier resolution) |

Agent-native means:

• JSON-first output — every response is valid JSON, pipe to jq or consume from any language
• Dual entry point — same commands work as CLI and MCP tools with zero adaptation
• Structured errors — errors return { "error": "...", "code": "..." }, not stack traces
• Field filtering — --fields id,name,status.status returns only what you need
• No interactive prompts in automation — all params available as flags, env vars, or config

Install

npm install -g @bcharleson/clickup-cli

Quick Start

# 1. Get your API token from ClickUp
# Settings → Apps → API Token → Generate

# 2. Authenticate
export CLICKUP_API_TOKEN="pk_xxxxx"

# 3. List your workspaces
clickup workspaces list --pretty

# 4. List spaces in a workspace
clickup spaces list --team-id 12345678

# 5. List tasks in a list
clickup tasks list --list-id 11111 --pretty

Auth

1. Get your API token

1. In ClickUp, go to Settings → Apps → API Token
2. Click Generate to create a personal API token
3. Copy the token (starts with pk_)

2. Authenticate

Three-tier resolution (highest priority first):

# Option A: Environment variable (recommended for agents)
export CLICKUP_API_TOKEN="pk_xxxxx"

# Option B: Interactive login (saves to ~/.clickup-cli/config.json)
clickup login

# Option C: Per-command flag
clickup tasks list --list-id 123 --api-token "pk_xxxxx"

3. Verify

clickup workspaces list --pretty

ClickUp Hierarchy

Workspace (team_id) → Space → Folder (optional) → List → Task → Subtask

Key notes:

• team_id in the API = Workspace ID (legacy naming)
• Folderless Lists sit directly under Spaces
• Tasks belong to a "home" List but can appear in multiple Lists
• Dates are Unix milliseconds throughout the API
• Priority: 1=urgent, 2=high, 3=normal, 4=low

Commands

Hierarchy (22 commands)

| Group | Commands | |-------|----------| | workspaces | list, seats, plan | | spaces | list, get, create, update, delete | | folders | list, get, create, update, delete | | lists | list, folderless, get, create, create-folderless, update, delete, add-task, remove-task |

Tasks & Content (35 commands)

| Group | Commands | |-------|----------| | tasks | list, get, create, update, delete, filtered, time-in-status | | comments | list-task, create-task, list-list, create-list, list-view, create-view, update, delete, list-replies, create-reply | | checklists | create, update, delete, create-item, update-item, delete-item | | custom-fields | list-workspace, list, list-folder, list-space, set, remove | | tags | list, create, update, delete, add-to-task, remove-from-task | | dependencies | add, remove, add-link, remove-link |

Views & Tracking (24 commands)

| Group | Commands | |-------|----------| | views | list-workspace, list-space, list-folder, list-list, get, tasks, delete | | time-tracking | list, get, create, update, delete, current, start, stop, history | | goals | list, get, create, update, delete, create-key-result, update-key-result, delete-key-result |

Admin & Config (24 commands)

| Group | Commands | |-------|----------| | webhooks | list, create, update, delete | | users | me, get, invite, update, remove | | guests | invite, get, update, remove, add-to-task, remove-from-task | | members | task, list | | templates | list, create-task | | roles | list |

Auth & Config

| Command | Description | |---------|-------------| | login | Authenticate with API token | | logout | Remove stored credentials | | status | Show current auth + account info |

Global Options

--api-token <token>   Override stored auth
--output <format>     json (default) or pretty
--pretty              Shorthand for --output pretty
--quiet               Suppress output, exit codes only
--fields <fields>     Comma-separated field filter (supports nested: status.status)

Examples

# Navigate the hierarchy
clickup workspaces list --fields teams
clickup spaces list --team-id 12345678
clickup folders list --space-id 98765
clickup lists list --folder-id 54321
clickup tasks list --list-id 11111

# Create a task with full details
clickup tasks create --list-id 123 \
  --name "Implement OAuth flow" \
  --description "Add OAuth 2.0 support" \
  --priority 2 \
  --status "in progress" \
  --assignees "456,789" \
  --due-date "1711929600000" \
  --tags "backend,auth" \
  --time-estimate 14400000

# Search tasks across a workspace
clickup tasks filtered --team-id 123 --assignees "456"
clickup tasks filtered --team-id 123 --statuses "in progress" --space-ids "111,222"

# Comments and checklists
clickup comments create-task --task-id abc --comment-text "Ready for review"
clickup checklists create --task-id abc --name "Deploy checklist"
clickup checklists create-item --checklist-id ck1 --name "Run tests"

# Time tracking
clickup time-tracking start --team-id 123 --task-id abc --description "Working on OAuth"
clickup time-tracking current --team-id 123
clickup time-tracking stop --team-id 123

# Goals and OKRs
clickup goals create --team-id 123 --name "Q1 Revenue Target" \
  --due-date "1711929600000" --owners "456"
clickup goals create-key-result --goal-id abc \
  --name "Close 50 deals" --type number --steps-start 0 --steps-end 50

# Webhooks
clickup webhooks create --team-id 123 \
  --endpoint "https://example.com/webhooks/clickup" \
  --events "taskCreated,taskUpdated,taskStatusUpdated"

# Custom fields
clickup custom-fields list --list-id 123
clickup custom-fields set --task-id abc --field-id cf_1 --value "high"

# Tags
clickup tags list --space-id 123
clickup tags add-to-task --task-id abc --tag-name "urgent"

# Dependencies
clickup dependencies add --task-id taskB --depends-on taskA
clickup dependencies add-link --task-id task1 --links-to task2

# Views
clickup views list-workspace --team-id 123
clickup views tasks --view-id v123

# Users and guests
clickup users me
clickup users invite --team-id 123 --email "[email protected]"
clickup guests invite --team-id 123 --email "[email protected]"

# Pipe to jq
clickup tasks list --list-id 123 | jq '.tasks[].name'
clickup tasks filtered --team-id 123 | jq '.tasks[] | {id, name, status: .status.status}'

MCP Server

The CLI includes a built-in MCP server exposing all 105 commands as tools:

# Start the MCP server
clickup mcp

MCP Config

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@bcharleson/clickup-cli", "mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

Or with a local install:

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/path/to/clickup-cli/dist/mcp.js"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

MCP Tool Names

All tools are named {group}_{subcommand} with hyphens converted to underscores:

• tasks_list, tasks_get, tasks_create, tasks_update, tasks_delete, tasks_filtered
• comments_create_task, comments_list_task, ...
• time_tracking_start, time_tracking_stop, time_tracking_current, ...
• goals_create, goals_create_key_result, ...
• webhooks_create, webhooks_list, ...

Architecture

This CLI follows a metadata-driven architecture shared across hubspot-cli and instantly-cli:

• CommandDefinition — single struct drives both CLI registration and MCP tool registration
• Zod schemas — input validation shared between CLI and MCP
• Declarative endpoints — { method, path, fieldMappings } drives HTTP request building
• Thin REST client — bare token auth, exponential backoff on 429s, rate-limit header handling
• Dual entry — dist/index.js (CLI) and dist/mcp.js (MCP server)

License

MIT