/clickup-cli

name: clickup
description: 'Use when reading or changing anything in ClickUp via the `cup` CLI - tasks, sprints, comments, Docs, Chat, views, webhooks, or workspace structure. Triggers: task queries, status updates, sprint tracking, creating subtasks, posting comments, threaded replies, standup summaries, searching tasks, checking overdue items, assigning tasks, ClickUp Docs and doc pages (read, create, edit), ClickUp Chat channels and messages, views and view tasks, webhooks, exporting or archiving ClickUp data (knowledge transfer, off-boarding), creating or renaming spaces, folders, and lists, list templates, opening tasks in browser, checking auth or config, setting custom fields, deleting tasks, managing tags, managing checklists, editing comments, task links, time tracking, attachments, file uploads, listing members, listing fields, duplicating tasks, bulk operations, goals, key results, saved filters, favorites.'

ClickUp CLI (`cup`) - skill version 1.46.2

Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, time tracking, custom fields, goals, Docs, Chat, views, webhooks, workspace structure, export, and project workflows.

> **Version check:** Run `cup --version`. If your installed version is older than 1.46.2, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill` (`cup skill --path <file>` installs to a custom location, `cup skill --print` writes it to stdout).

Install & Configure

Prerequisites

Node.js 22+ required.

Install

npm install -g @krodak/clickup-cli

Or via Homebrew:

brew tap krodak/tap && brew install clickup-cli

Get an API token

The user needs a personal API token from ClickUp:

1. Open https://app.clickup.com/settings/apps 2. Under "API Token", click "Generate" (or copy existing) 3. The token starts with `pk_`

Configure

**Non-interactive (recommended for agents):**

cup init --token pk_USER_TOKEN --team TEAM_ID

To find the team/workspace ID, the user can check their ClickUp URL: `https://app.clickup.com/TEAM_ID/...`

**Interactive (for humans in a terminal):**

cup init

**Environment variables (no config file needed):**

export CU_API_TOKEN="pk_..."
export CU_TEAM_ID="12345678"

Verify

cup auth

This prints the authenticated username and workspace. If it fails, the token or config is invalid.

Setup

Config stored at `~/.config/cup/config.json` with named profiles. Each profile has `apiToken` and `teamId`. Optional: `sprintFolderId` to pin sprint detection to a specific folder.

Multiple profiles supported - use `cup profile add <name>` to create, `cup profile use <name>` to switch, or `-p <name>` flag for one-off overrides.

`CU_PROFILE` environment variable selects a profile (overridden by `-p` flag).

Saved Filters (Quick Shortcuts)

At the start of each session, run `cup filter list` to discover saved shortcuts for this workspace.

| Command | What it does | | --- | --- | | `cup filter list [--json]` | List all saved shortcuts with commands and descriptions | | `cup filter run <name>` | Execute a saved shortcut (identical to running the full command) | | `cup filter save <name> <cmd> [args...] [-d desc]` | Save a command shortcut | | `cup filter delete <name>` | Remove a shortcut | | `cup filter show <name> [--json]` | Show a single shortcut's details |

Example: `cup filter save sprint-tasks tasks --status "in progress" --list l1 -d "Current sprint tasks"` Then: `cup filter run sprint-tasks` is equivalent to `cup tasks --status "in progress" --list l1`

Output Modes

| Context | Default output | Override | | --- | --- | --- | | Terminal (TTY) | Interactive picker UI | `--json` for JSON | | Piped / non-TTY | Markdown tables | `--json` for JSON |

• Default piped output is **Markdown** - optimized for agent context windows
• `cup task <id>` outputs a Markdown summary when piped; use `--json` for the full raw API object
• Set `CU_OUTPUT=json` to always get JSON when piped
• Agents typically don't need `--json` unless parsing structured data with `jq`

Commands

All commands support `--help` for full flag details. All commands support `--json`.

Read

| Command | What it returns | | --- | --- | | `cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--all] [--include-closed] [--assignee id\|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]` | Tasks assigned to you (filter by status, name, type, list, space, assignee, tag, dates, custom fields). `--all` for all assignees | | `cup assigned [--status s] [--include-closed]` | All my tasks grouped by status | | `cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed]` | Tasks in active sprint (auto-detected) | | `cup sprints [--space nameOrId]` | List all sprints (marks active with \*) | | `cup search [query] [--status s] [--list id] [--space id] [--all] [--include-closed] [--assignee id\|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]` | Search tasks by name, or list tasks filtered by flags when no query is given. `--all` for all assignees | | `cup task <id>` | Single task details (custom fields, checklists, attachments, deps, links) | | `cup subtasks <id> [--status s] [--name q] [--include-closed]` | Subtasks of a task | | `cup comments <id>` | Comments on a task | | `cup activity <id>` | Task details + comment history combined | | `cup inbox [--days n] [--include-closed]` | Tasks updated in last n days (default 30) | | `cup summary [--hours n]` | Standup: completed, in-progress, overdue | | `cup overdue [--all] [--include-closed]` | Tasks past due date (most overdue first) | | `cup spaces [--name partial] [--my] [--archived]` | List/filter workspace spaces | | `cup lists <spaceId> [--name partial] [--archived]` | Lists in a space (including folder l