Open Source·AI Agent Infrastructure

Your Projects, Controlled by Agents.

Tasks. Goals. Time. Views. 105 commands. Every one doubles as an MCP tool.

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
  • Every command is also an MCP tool — plug into any AI agent
  • 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

Every command is exposed as an MCP tool. Claude, Cursor, OpenClaw, and any MCP client can call all 105 commands natively.

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 create --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 --include-subtasks true

Get all project tasks

2
clickup time-tracking list --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 update $GOAL_ID --name "Q2 Revenue" --due-date 2026-06-30

Update goal metadata

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 get $WEBHOOK_ID

Verify webhook configuration

Commands Reference

workspaces (3 commands)
clickup workspaces listList all workspaces (teams) you have access to
clickup workspaces get <team-id>Get workspace details
clickup workspaces seats <team-id>View workspace seat usage
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 (4 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 delete <folder-id>Delete a folder
lists (4 commands)
clickup lists list --folder-id <id>List all lists in a folder
clickup lists get <list-id>Get list details
clickup lists create --folder-id <id> --name <name>Create a new list
clickup lists delete <list-id>Delete a list
tasks (8 commands)
clickup tasks list --list-id <id> [--assignees] [--statuses] [--due-date]List tasks with filters
clickup tasks get <task-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> [--name] [--status] [--priority] [--assignees]Update task properties
clickup tasks delete <task-id>Delete a task
clickup tasks create --list-id <id> --name <name> --parent <task-id>Create a subtask
clickup tasks members <task-id>List task members
clickup tasks tags <task-id>List task tags
comments (5 commands)
clickup comments list --task-id <id>List all comments on a task
clickup comments create --task-id <id> --comment-text <text>Add a comment to a task
clickup comments update <comment-id> --comment-text <text>Update a comment
clickup comments delete <comment-id>Delete a comment
clickup comments list --list-id <id>List comments on a list (threaded)
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 (3 commands)
clickup custom-fields list --list-id <id>List available custom fields on a list
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 (4 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 add --task-id <id> --tag-name <name>Add tag to a task
clickup tags remove --task-id <id> --tag-name <name>Remove tag from a task
dependencies (3 commands)
clickup dependencies create --task-id <id> --depends-on <id>Create a dependency between tasks
clickup dependencies delete --task-id <id> --depends-on <id>Remove a dependency
clickup dependencies links --task-id <id>List all task links and dependencies
views (5 commands)
clickup views list --space-id <id>List views in a space
clickup views get <view-id>Get view configuration
clickup views create --space-id <id> --name <name> --type list|board|calendarCreate a view
clickup views update <view-id> [--name] [--settings]Update view settings
clickup views delete <view-id>Delete a view
time-tracking (5 commands)
clickup time-tracking list --task-id <id>List time entries on a task
clickup time-tracking create --task-id <id> --duration <ms> --start <timestamp>Log a manual time entry
clickup time-tracking start --task-id <id>Start a timer on a task
clickup time-tracking stop --task-id <id>Stop the running timer
clickup time-tracking delete <interval-id> --task-id <id>Delete a time entry
goals (5 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
webhooks (5 commands)
clickup webhooks list --team-id <id>List all active webhooks
clickup webhooks get <webhook-id>Get webhook details
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 & members (8 commands)
clickup users get --team-id <id>Get authorized user details
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 remove --team-id <id> --guest-id <id>Remove a guest
clickup members list --list-id <id>List members of a list
clickup members list --task-id <id>List members of a task
clickup roles list --team-id <id>List available roles
clickup roles create --team-id <id> --name <name>Create a custom role
templates (2 commands)
clickup templates list --team-id <id>List available task templates
clickup templates create --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

Every command is available as an MCP tool. Configure once and your agent has full ClickUp access.

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"
      }
    }
  }
}

MCP tools registered (105 total):

workspaces_listworkspaces_getworkspaces_seatsspaces_listspaces_getspaces_createspaces_updatespaces_deletefolders_listfolders_getfolders_createfolders_deletelists_listlists_getlists_createlists_deletetasks_listtasks_gettasks_createtasks_updatetasks_deletetasks_memberstasks_tagstasks_subtaskcomments_listcomments_createcomments_updatecomments_deletechecklists_createchecklists_updatechecklists_deletechecklists_create_itemchecklists_update_itemcustom_fields_listcustom_fields_setcustom_fields_removetags_listtags_createtags_addtags_removedependencies_createdependencies_deletedependencies_linksviews_listviews_getviews_createviews_updateviews_deletetime_tracking_listtime_tracking_createtime_tracking_starttime_tracking_stoptime_tracking_deletegoals_listgoals_getgoals_creategoals_updategoals_deletewebhooks_listwebhooks_getwebhooks_createwebhooks_updatewebhooks_deleteusers_getguests_inviteguests_getguests_removemembers_listroles_listroles_createtemplates_listtemplates_create

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 — or use clickup login to save to config
3
Start MCP server
clickup mcp — runs on stdio transport, compatible with any MCP client
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/        # 4 commands
│   ├── lists/          # 4 commands
│   ├── tasks/          # 8 commands
│   ├── comments/       # 5 commands
│   ├── checklists/     # 5 commands
│   ├── custom-fields/  # 3 commands
│   ├── tags/           # 4 commands
│   ├── dependencies/   # 3 commands
│   ├── views/          # 5 commands
│   ├── time-tracking/  # 5 commands
│   ├── goals/          # 5 commands
│   ├── webhooks/       # 5 commands
│   ├── users/          # 1 command
│   ├── guests/         # 3 commands
│   ├── members/        # 2 commands
│   ├── templates/      # 2 commands
│   └── roles/          # 2 commands
└── mcp/
    └── server.ts       # MCP server (auto-registers all commands as tools)

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.