Open Source·AI Agent Infrastructure

Your Projects, Controlled by Agents.

Tasks. Goals. Time. Views. 105 commands. Lean MCP by default, full MCP when you need it.

ClickUp has no official CLI for agents.
So we built clickup-cli — the missing CLI for agents on ClickUp.

Install from npm
105
Commands
19
API Groups
CLI
+ MCP Native
OpenClaw
OpenClaw
CLI / MCP
ClickUp
ClickUp
tasks · goals · time · views · webhooks

Why clickup-cli Exists

Without clickup-cli

  • No official CLI — ClickUp only offers a web UI and REST API
  • Agents can’t programmatically manage tasks or projects without custom API wrappers
  • Manual API token management per request
  • No MCP support — agents can’t call ClickUp as a native tool
  • Deep workspace hierarchies require chained API calls with no tooling

With clickup-cli

  • 105 commands covering the full ClickUp API v2 surface
  • Single API token, 3-tier resolution: flag → env var → config file
  • Built-in MCP server — lean daily-work tools by default, full command surface on demand
  • JSON-first output — pipe to jq, save to files, feed to agents
  • Full hierarchy traversal: workspace → space → folder → list → task

Why Use clickup-cli?

🏢

Agency Project Management

Agents create client spaces, scaffold projects, assign tasks, and track time — all autonomously. No more manual ClickUp setup for every new client.

🏃

Sprint Automation

Break down epics into subtasks, set dependencies, assign team members, and track progress. Sprint planning that takes seconds, not hours.

⏱️

Time & Resource Tracking

Start/stop timers, log time entries, and generate utilization reports. Know exactly how your team spends their hours.

🎯

Goal & OKR Management

Create goals with measurable targets, track progress, and get AI-generated status reports. Keep your team aligned on quarterly objectives.

🔗

Cross-Tool Orchestration

Combine with hubspot-cli, instantly-cli, and other TOFU CLIs. Close a deal in HubSpot → auto-create an onboarding project in ClickUp.

⚡

Real-Time Event Hooks

Set up webhooks for task status changes, new comments, and assignment updates. Build event-driven workflows that react instantly.

Quick Start

1. Install

Terminal
npm install -g @bcharleson/clickup-cli

2. Get your API token

1. In ClickUp, click your avatar (bottom left) → Settings

2. Navigate to Apps in the left sidebar

3. Under API Token, click Generate (or copy your existing token)

Token starts with pk_ — this is a personal token with your permissions

3. Authenticate

Terminal
# 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

4. Verify

Terminal
clickup workspaces list --pretty
# Returns your workspaces as formatted JSON

clickup tasks list --list-id 12345 --pretty
# Returns tasks in the specified list

What clickup-cli Gives Your Agent

16 cmds

Workspaces & Hierarchy

Full workspace, space, folder, and list management. Navigate and manage the complete ClickUp hierarchy from the terminal.

8 cmds

Tasks & Subtasks

Complete task lifecycle — create, update, assign, set priorities, manage subtasks, and close tasks. Full CRUD with field filtering.

10 cmds

Comments & Checklists

Add threaded comments to tasks, manage checklists and checklist items. Keep task context and progress tracked programmatically.

10 cmds

Time Tracking & Goals

Start/stop timers, log manual time entries, and track goals with targets. Full time tracking and OKR management from the CLI.

14 cmds

Views & Custom Fields

Create and manage views (list, board, calendar, gantt, timeline). Set and update custom fields and tags on any task.

MCP Server

Built-in MCP server with lean mode by default for daily agent work, plus full mode for the complete command surface.

Agent Workflows

Real prompts agents use to manage ClickUp end-to-end.

New Client Onboarding → Full Project Setup

Agent Prompt

“A new client just signed — create a space called "Acme Corp", add folders for "Onboarding", "Deliverables", and "Meetings", then create a task list in each with the standard onboarding checklist.”

Agent creates the full workspace hierarchy, populates lists with templated tasks, and sets due dates — complete project scaffolding in one autonomous flow.

1
clickup spaces create --team-id $TEAM --name "Acme Corp"

Create the client space

2
clickup folders create --space-id $SPACE --name "Onboarding"

Create onboarding folder

3
clickup lists create --folder-id $FOLDER --name "Setup Tasks"

Create task list in folder

4
clickup tasks create --list-id $LIST --name "Kickoff call" --priority 2 --assignees $USER

Create first onboarding task

Morning Standup Report

Agent Prompt

“Pull my tasks due today, anything overdue, and what I completed yesterday. Format it as a standup update.”

Agent queries tasks by assignee and due date, filters by status, and compiles a structured standup report — daily standups automated.

1
clickup tasks list --list-id $LIST --assignees $ME --due-date-lt today --statuses open

Find overdue tasks

2
clickup tasks list --list-id $LIST --assignees $ME --due-date today

Get tasks due today

3
clickup tasks list --list-id $LIST --assignees $ME --statuses closed --date-updated-gt yesterday

Completed yesterday

Sprint Planning → Task Breakdown

Agent Prompt

“Break down the "Launch Marketing Site" task into subtasks: design mockups, copy writing, development, QA testing, and deployment. Set priorities and assign to the team.”

Agent creates subtasks with priorities, assigns team members, adds checklists, and sets dependencies — sprint planning done in seconds.

1
clickup tasks get $TASK_ID

Get parent task details

2
clickup tasks create --list-id $LIST --name "Design Mockups" --parent $TASK_ID --priority 2

Create subtask

3
clickup checklists create --task-id $SUBTASK --name "Design Review"

Add checklist to subtask

4
clickup dependencies add --task-id $DEV --depends-on $DESIGN

Set dependency chain

Time Tracking Summary

Agent Prompt

“How much time did the team log on the Acme Corp project this week? Break it down by task and person.”

Agent pulls time entries across all tasks in a space, aggregates by assignee and task, and produces a time utilization report.

1
clickup tasks list --list-id $LIST --subtasks true

Get all project tasks

2
clickup time-tracking list --team-id $TEAM --task-id $TASK

Pull time entries per task

3
clickup members list --list-id $LIST

Map user IDs to names

Goal Progress Check

Agent Prompt

“Check our Q2 goals — which targets are on track and which are behind? Update the "Revenue" goal target to $500K.”

Agent pulls all goals, checks target progress, identifies at-risk items, and updates targets — OKR management from the terminal.

1
clickup goals list --team-id $TEAM

List all workspace goals

2
clickup goals get $GOAL_ID

Get goal with target progress

3
clickup goals create-key-result --goal-id $GOAL_ID --name "Revenue" --type currency --steps-start 0 --steps-end 500000

Create measurable target

4
clickup goals update-key-result $KEY_RESULT_ID --steps-current 275000 --note "Updated from CRM report"

Update target progress

Webhook → Real-Time Automation

Agent Prompt

“Set up a webhook that fires whenever a task is moved to "Done" in the Acme Corp space, so our billing agent can trigger an invoice.”

Agent creates a webhook subscription for task status changes, enabling downstream automations without polling.

1
clickup webhooks list --team-id $TEAM

Check existing webhooks

2
clickup webhooks create --team-id $TEAM --endpoint https://api.example.com/invoice --events taskStatusUpdated --space-id $SPACE

Create status change webhook

3
clickup webhooks update $WEBHOOK_ID --endpoint https://api.example.com/invoice

Update webhook configuration when needed

Commands Reference

workspaces (3 commands)
clickup workspaces listList all workspaces (teams) you have access to
clickup workspaces seats --team-id <id>View workspace seat usage
clickup workspaces plan --team-id <id>Get workspace plan details
spaces (5 commands)
clickup spaces list --team-id <id>List all spaces in a workspace
clickup spaces get <space-id>Get space details and features
clickup spaces create --team-id <id> --name <name>Create a new space
clickup spaces update <space-id> --name <name>Update space name or settings
clickup spaces delete <space-id>Delete a space
folders (5 commands)
clickup folders list --space-id <id>List all folders in a space
clickup folders get <folder-id>Get folder details with lists
clickup folders create --space-id <id> --name <name>Create a new folder
clickup folders update <folder-id> --name <name>Update a folder
clickup folders delete <folder-id>Delete a folder
lists (9 commands)
clickup lists list --folder-id <id>List all lists in a folder
clickup lists folderless --space-id <id>List folderless lists in a space
clickup lists get <list-id>Get list details
clickup lists create --folder-id <id> --name <name>Create a new list
clickup lists create-folderless --space-id <id> --name <name>Create a folderless list
clickup lists update <list-id> --name <name>Update a list
clickup lists delete <list-id>Delete a list
clickup lists add-task --list-id <id> --task-id <id>Add a task to an additional list
clickup lists remove-task --list-id <id> --task-id <id>Remove a task from an additional list
tasks (8 commands)
clickup tasks search --query <text>Search tasks by name with compact results
clickup tasks list --list-id <id> [--assignees] [--statuses] [--due-date]List tasks with filters
clickup tasks get --task-id <id>Get full task details
clickup tasks create --list-id <id> --name <name> [--priority] [--assignees] [--due-date]Create a new task
clickup tasks update --task-id <id> [--name] [--status] [--priority] [--assignees]Update task properties
clickup tasks delete --task-id <id>Delete a task
clickup tasks move --task-id <id> --list-id <id>Move a task to a new home list
clickup tasks filtered --team-id <id> [--assignees] [--statuses] [--space-ids]Filter tasks across a workspace
clickup tasks time-in-status --task-id <id>Get time spent in each status
comments (10 commands)
clickup comments list-task --task-id <id>List all comments on a task
clickup comments create-task --task-id <id> --comment-text <text>Add a comment to a task
clickup comments list-list --list-id <id>List comments on a list
clickup comments create-list --list-id <id> --comment-text <text>Add a comment to a list
clickup comments list-view --view-id <id>List comments on a chat view
clickup comments create-view --view-id <id> --comment-text <text>Add a comment to a view
clickup comments update <comment-id> --comment-text <text>Update a comment
clickup comments delete <comment-id>Delete a comment
clickup comments list-replies --comment-id <id>List threaded replies
clickup comments create-reply --comment-id <id> --comment-text <text>Create a threaded reply
checklists (5 commands)
clickup checklists create --task-id <id> --name <name>Create a checklist on a task
clickup checklists update <checklist-id> --name <name>Rename a checklist
clickup checklists delete <checklist-id>Delete a checklist
clickup checklists create-item <checklist-id> --name <name>Add an item to a checklist
clickup checklists update-item <checklist-id> <item-id> --resolved trueCheck/uncheck a checklist item
custom-fields (6 commands)
clickup custom-fields list-workspace --team-id <id>List workspace-level custom fields
clickup custom-fields list --list-id <id>List available custom fields on a list
clickup custom-fields list-folder --folder-id <id>List custom fields for a folder
clickup custom-fields list-space --space-id <id>List custom fields for a space
clickup custom-fields set --task-id <id> --field-id <id> --value <val>Set a custom field value on a task
clickup custom-fields remove --task-id <id> --field-id <id>Remove a custom field value
tags (6 commands)
clickup tags list --space-id <id>List all tags in a space
clickup tags create --space-id <id> --name <name>Create a new tag
clickup tags update --space-id <id> --tag-name <name>Update a tag
clickup tags delete --space-id <id> --tag-name <name>Delete a tag
clickup tags add-to-task --task-id <id> --tag-name <name>Add tag to a task
clickup tags remove-from-task --task-id <id> --tag-name <name>Remove tag from a task
dependencies (4 commands)
clickup dependencies add --task-id <id> --depends-on <id>Create a dependency between tasks
clickup dependencies remove --task-id <id> --depends-on <id>Remove a dependency
clickup dependencies add-link --task-id <id> --links-to <id>Link two related tasks
clickup dependencies remove-link --task-id <id> --links-to <id>Remove a task link
views (7 commands)
clickup views list-workspace --team-id <id>List workspace views
clickup views list-space --space-id <id>List views in a space
clickup views list-folder --folder-id <id>List views in a folder
clickup views list-list --list-id <id>List views in a list
clickup views get <view-id>Get view configuration
clickup views tasks --view-id <id>Get tasks in a view
clickup views delete <view-id>Delete a view
time-tracking (9 commands)
clickup time-tracking list --team-id <id> [--task-id <id>]List time entries, defaulting to the last 30 days
clickup time-tracking get <interval-id> --team-id <id>Get a single time entry
clickup time-tracking create --team-id <id> --task-id <id> --duration <ms> --start <timestamp>Log a manual time entry
clickup time-tracking update <interval-id> --team-id <id> [--duration] [--description]Update a time entry
clickup time-tracking delete <interval-id> --task-id <id>Delete a time entry
clickup time-tracking current --team-id <id>Get the running timer
clickup time-tracking start --team-id <id> --task-id <id>Start a timer on a task
clickup time-tracking stop --team-id <id>Stop the running timer
clickup time-tracking history --team-id <id>Get time entry history
goals (8 commands)
clickup goals list --team-id <id>List all workspace goals
clickup goals get <goal-id>Get goal with targets and progress
clickup goals create --team-id <id> --name <name> --due-date <date>Create a goal
clickup goals update <goal-id> [--name] [--due-date]Update goal metadata
clickup goals delete <goal-id>Delete a goal
clickup goals create-key-result --goal-id <id> --name <name> --type <type>Create a key result target
clickup goals update-key-result <key-result-id> [--steps-current] [--note]Update key result progress
clickup goals delete-key-result <key-result-id>Delete a key result
webhooks (4 commands)
clickup webhooks list --team-id <id>List all active webhooks
clickup webhooks create --team-id <id> --endpoint <url> --events <events>Create a webhook subscription
clickup webhooks update <webhook-id> --endpoint <url>Update a webhook
clickup webhooks delete <webhook-id>Delete a webhook
users, guests & members (16 commands)
clickup users meGet the authenticated user
clickup users get --team-id <id> --user-id <id>Get a user in a workspace
clickup users invite --team-id <id> --email <email>Invite a user to workspace
clickup users update --team-id <id> --user-id <id> --role <role>Update a user role
clickup users remove --team-id <id> --user-id <id>Remove a user from workspace
clickup guests invite --team-id <id> --email <email>Invite a guest to workspace
clickup guests get --team-id <id> --guest-id <id>Get guest details
clickup guests update --team-id <id> --guest-id <id>Update a guest
clickup guests remove --team-id <id> --guest-id <id>Remove a guest
clickup guests add-to-task --task-id <id> --guest-id <id>Add guest to a task
clickup guests remove-from-task --task-id <id> --guest-id <id>Remove guest from a task
clickup members list --list-id <id>List members of a list
clickup members list --task-id <id>List members of a task
clickup members workspace --team-id <id>List all workspace members
clickup members find --team-id <id> --query <name-or-email>Find a member by name or email
clickup members resolve --assignees "me,brandon"Resolve names, emails, or me to ClickUp user IDs
clickup roles list --team-id <id>List available roles
templates (2 commands)
clickup templates list --team-id <id>List available task templates
clickup templates create-task --list-id <id> --template-id <id>Create task from template
auth (3 commands)
clickup login [--token <token>]Authenticate and save token to config file
clickup logoutClear saved credentials
clickup status [--pretty]Show authentication state and workspace info

MCP Server Setup

Lean MCP mode is the default for daily agent work. Use full mode when an agent needs the complete command surface.

Claude Desktop / Cursor (~/.cursor/mcp.json or claude_desktop_config.json)
{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@bcharleson/clickup-cli", "mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx",
        "CLICKUP_TEAM_ID": "12345678"
      }
    }
  }
}

Lean MCP tools registered by default (~33):

workspaces_listspaces_listfolders_listlists_listlists_folderlesstasks_searchtasks_listtasks_gettasks_createtasks_updatetasks_deletetasks_movetasks_filteredlists_getlists_createlists_create_folderlesslists_updatelists_add_tasklists_remove_taskfolders_getfolders_createfolders_updateusers_memembers_resolvemembers_findmembers_workspacecomments_list_taskcomments_create_tasktags_add_to_tasktags_remove_from_tasktime_tracking_starttime_tracking_stoptime_tracking_current

For the full tool surface, run clickup mcp --full or set CLICKUP_MCP_MODE=full.

OpenClaw Agent Setup

Give any OpenClaw agent full ClickUp access. Install once, set the token, and the agent manages your projects autonomously.

1
Install on the agent's server
npm install -g @bcharleson/clickup-cli
2
Set API token in agent environment
export CLICKUP_API_TOKEN=pk_xxxxx and export CLICKUP_TEAM_ID=12345678 to skip workspace lookup
3
Start MCP server
clickup mcp runs lean mode on stdio; use clickup mcp --full for every API command
4
Add project management instructions to SOUL.md
Tell the agent how to create projects, manage tasks, track time, and handle your workspace hierarchy
5
Test from Slack
"Create a new task in the Acme project" — agent calls clickup tasks create via MCP, returns structured JSON

Architecture

Every API endpoint is a CommandDefinition — one source of truth powering both the CLI subcommand and the MCP tool. Metadata-driven with Zod validation and declarative endpoint definitions.

src/
├── core/
│   ├── types.ts        # CommandDefinition, ClickUpClient interfaces
│   ├── client.ts       # REST client (exponential backoff, rate limiting)
│   ├── auth.ts         # 3-tier token resolution
│   ├── config.ts       # ~/.clickup-cli/config.json
│   └── output.ts       # JSON output + --fields filtering
├── commands/
│   ├── workspaces/     # 3 commands
│   ├── spaces/         # 5 commands
│   ├── folders/        # 5 commands
│   ├── lists/          # 9 commands
│   ├── tasks/          # 8 commands
│   ├── comments/       # 10 commands
│   ├── checklists/     # 6 commands
│   ├── custom-fields/  # 6 commands
│   ├── tags/           # 6 commands
│   ├── dependencies/   # 4 commands
│   ├── views/          # 7 commands
│   ├── time-tracking/  # 9 commands
│   ├── goals/          # 8 commands
│   ├── webhooks/       # 4 commands
│   ├── users/          # 5 commands
│   ├── guests/         # 6 commands
│   ├── members/        # 5 commands
│   ├── templates/      # 2 commands
│   └── roles/          # 1 command
└── mcp/
    └── server.ts       # lean MCP by default, full mode available

Same pattern as all TOFU CLIs

The CommandDefinition architecture is shared across instantly-cli, clay-gtm-cli, hubspot-cli, partnerstack-cli, heyreach-cli, and ms365-cli. One schema definition generates the Commander.js subcommand, the Zod schema, and the MCP tool — zero duplication.

ClickUp API v2 Specifics

Uses Authorization header with personal API tokens. Deep workspace hierarchy (workspace → space → folder → list → task). Rate limiting with exponential backoff. Separate endpoints for each resource type.

Ready to give your agent full project control?

Install clickup-cli, set your API token in 60 seconds, and your agent can create tasks, track time, manage goals, and run your entire ClickUp workspace.

Need agents managing your ClickUp projects? We deploy and manage the full setup.