[-c content]` | Create a doc (root page is named after the title; `-c` writes its markdown content) | | `cup doc-page-create <docId> <name> [-c content\|--content-file path] [--parent-page pageId]` | Create doc page (`--content-file` reads markdown from a file or `-` for stdin) | | `cup doc-page-edit <docId> <pageId> [--name text] [-c content\|--content-file path]` | Edit doc page (`--content-file` reads markdown from a file or `-` for stdin) | | `cup doc-delete <docId>` | **Not supported** — ClickUp has no delete-Doc API (HTTP 405). Fails fast; delete Docs in the UI. Use `cup doc-page-delete` for a single page | | `cup doc-page-delete <docId> <pageId>` | Delete doc page | | `cup space-create <name>` | Create a space | | `cup list-create <spaceId> <name> [--folder folderId] [--copy-statuses-from id]` | Create a list in a space or folder | | `cup folder-create <spaceId> <name>` | Create a folder in a space | | `cup list-rename <listId> <newName>` | Rename a list | | `cup folder-rename <folderId> <newName>` | Rename a folder | | `cup space-rename <spaceId> <newName>` | Rename a space | | `cup tag-create <spaceId> <name> [--fg color] [--bg color]` | Create space tag | | `cup tag-update <spaceId> <tagName> --name <newName> [--fg c] [--bg c]` | Update space tag | | `cup tag-delete <spaceId> <name>` | Delete space tag | | `cup list-from-template <name> --template <id> [--space id] [--folder id]` | Create list from template | | `cup view-create <listId> <name> -t <type> [--group-by field]` | Create a view on a list | | `cup view-update <viewId> [-n name] [--group-by field]` | Update a view | | `cup view-delete <viewId> [--confirm]` | Delete a view (DESTRUCTIVE) | | `cup list-comment <listId> -m text [--notify-all] [--mention user]` | Post comment on a list (`--mention` for real @mentions) | | `cup view-comment <viewId> -m text [--notify-all] [--mention user]` | Post comment on a view (`--mention` for real @mentions) | | `cup webhook create --url <url> --events <events> [--space\|--folder\|--list\|--task <id>]` | Create a webhook | | `cup webhook update <webhookId> [--url u] [--events e] [--status s]` | Update a webhook | | `cup webhook delete <webhookId> [--confirm]` | Delete a webhook (DESTRUCTIVE) | | `cup merge <sourceTaskId> <intoTaskId> [--confirm]` | Merge task into another (DESTRUCTIVE, source deleted) | | `cup time estimate-by-user <taskId> <userId> <duration> [--replace]` | Set per-user time estimate | | `cup chat send <channelId> -m <text> [--post --title t]` | Send message to channel | | `cup chat reply <messageId> -m <text>` | Reply to a message | | `cup chat react <messageId> --emoji <name>` | Add reaction | | `cup chat unreact <messageId> --emoji <name>` | Remove reaction | | `cup chat channel-create <name> [--private] [--topic t]` | Create channel | | `cup chat dm <userIds...>` | Create/open DM | | `cup chat channel-update <id> [--name n] [--topic t]` | Update channel | | `cup chat channel-delete <id> [--confirm]` | Delete channel | | `cup chat message-update <messageId> -m <text>` | Edit message | | `cup chat message-delete <messageId> [--confirm]` | Delete message | | `cup favorite add <type> <id> [alias] [-n name]` | Add a local favorite | | `cup favorite remove <alias>` | Remove a favorite | | `cup favorite list [--type t]` | List favorites (optionally filter by type) | | `cup profile list [--json]` | List all profiles | | `cup profile add <name>` | Add a new profile (interactive) | | `cup profile remove <name>` | Remove a profile | | `cup profile use <name>` | Set the default profile | | `cup config get <key>` / `set <key> <value>` / `path` | Manage config | | `cup completion <shell>` | Shell completions (bash/zsh/fish) | ## Global Flags | Flag | Description | | --- | --- | | `-p, --profile <n>` | Use a specific profile for this command | | `--json` | Force JSON output (available on all commands) | > **`-p` is always `--profile`, never `--parent`.** Global short flags win over subcommand > ones, so `cup create -p <taskId>` fails with `Profile "<taskId>" not found`. Use > `cup create --parent <taskId>`. ## Flags & Conventions | Topic | Detail | | --- | --- | | Task IDs | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format | | Task URLs | All commands that accept a task ID also accept full ClickUp URLs (`https://app.clickup.com/t/<id>` or `https://app.clickup.com/t/<workspace>/<id>`). The ID is auto-extracted | | View URLs | All commands that accept a view ID also accept full ClickUp view URLs (`https://app.clickup.com/<workspace>/v/<type>/<viewId>`). The ID is auto-extracted | | `--status` | Fuzzy matching: exact > starts-with > contains. Prints match to stderr | | `--priority` | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4) | | `--due-date` | `YYYY-MM-DD` (date only), `YYYY-MM-DDTHH:MM` (with time), or full ISO 8601 with offset. Time-of-day formats set `due_date_time: true` in ClickUp | | `--assignee` | User ID or `me` | | `--tags` | Comma-separated (e.g. `--tags "bug,frontend"`) | | `--time-estimate` | Duration: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds | | `--type` | `task` (regular) or custom type name/ID (e.g. `initiative`, `Bug`) | | `--custom-item-id` | Custom task type ID for `cup create` (find with `cup task-types`) | | `--space` | Partial name match or exact ID | | `--name` | Partial match, case-insensitive | | `--all` | Show all tasks in workspace, not just assigned to me. Available on `tasks`, `search`, `overdue`. Default: my tasks only (smaller output for agent context windows) | | `--include-closed` | Include closed/done tasks | | `--list` on create | Optional when `--parent` is given (auto-detected). Accepts `sprint:current` pseudo-ID | | `cup field --set` | Supports: text, number, checkbox (true/false), dropdown (option name), labels (comma-separated names), date (YYYY-MM-DD), url, email, emoji/rating (0-5), manual_progress (0-100), tasks/relationship (comma-separated task IDs), users/people (comma-separated user IDs). Names resolved case-insensitively; errors list available fields/options | | `cup field-create` | Use `--options "a,b,c"` for `drop_down` and `labels` types (required). Other types don't need `--options` | | `--field` filter | `--field "Name" value` on `tasks` and `search` requires `--list` to resolve field names to IDs | | `--due-before/after` | `YYYY-MM-DD` date filters for due date range | | `--created-before/after` | `YYYY-MM-DD` date filters for creation date range | | `cup sprint` | Auto-detects active sprint by folder name (sprint/iteration/cycle/scrum), parses multiple date formats. Override with `--folder <id>`, `cup config set sprintFolderId <id>`, or favorite a sprint folder | | `cup favorite` | Local-only favorites (not synced to ClickUp). Types: sprint-folder, space, list, folder, view, task. Favorited sprint-folders auto-used by sprint commands | | `cup link` | Both IDs must be the same type (both custom or both native) | | `cup delete` | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone | | Errors | Exit code 1 on errors. `cup auth --json` (also `CU_OUTPUT=json`) keeps authentication failures as JSON on stdout; other errors go to stderr. Strict parsing rejects excess/unknown arguments | | Rate limiting | The client retries HTTP 429 with `Retry-After`-aware backoff (up to 3 retries). Transient 502/503/504 retries are limited to GET/HEAD reads. Mutations are not replayed after gateway errors or transport failures: check remote state before retrying. Warnings go to stderr | | Multiline markdown (`-d` / `-m` / field values) | **Best for agents:** use `--description-file <path>` / `--message-file <path>` / `--value-file <path>` (or `-` for stdin) to bypass shell quoting entirely — see the multiline example below. For inline multiline, use a **quoted heredoc** `"$(cat <<'EOF' … EOF)"` — it preserves backticks, newlines, and apostrophes. **Footgun:** never split a `$'...'` string with `'\''` for an apostrophe — the tail drops back to normal single quotes and `\n` becomes literal text (e.g. `$'…team'\''s…\n## Goals'` breaks). Plain double quotes execute backticks as commands. | | `--mention <user>` | Real ClickUp @mention (notifies the user). Accepts ID, email, username, or `me`. Repeatable. Also: `<@userId>` inline token in `-m` for mid-sentence mentions. Bare `@Name` is NOT parsed (ambiguous). On `comment`, `reply`, `comment-edit`, `list-comment`, `view-comment` | | Comment links | In comment messages, bare URLs (`https://...`) and markdown links (`[text](url)`) both render as clickable links. Unfurled preview cards are not supported (web-UI only) | > **Note:** `cup search`, `cup tasks`, `cup overdue`, and `cup assigned` default to tasks assigned to the current user. Use `--all` to include tasks assigned to others. This matters when searching for parent initiatives or team-wide items. ## Interactive Mode (TTY) When running in a terminal (not piped), task-listing commands (`cup tasks`, `cup search`, `cup sprint`, `cup overdue`, `cup assigned`, `cup inbox`, `cup summary`) present an interactive task picker: - **↑/↓** or **j/k** to navigate the list - **Space** to toggle task selection - **Enter** to confirm and view details of selected tasks - After viewing details, prompted to open tasks in browser Other interactive prompts: sprint selection (when multiple match), workspace selection (`cup init`), agent selection (`cup skill`), destructive action confirmations (`cup delete`, `cup list-delete`, `cup folder-delete`, `cup space-delete`, `cup archive`, `cup view-delete`, `cup merge`, `cup webhook delete`). When piped or called with `--json`, all commands output non-interactive markdown or JSON. Agents should always use `--json` for structured data or pipe for markdown. ## Agent Workflow Examples ### Investigate a task ```bash cup task abc123def # markdown summary cup subtasks abc123def # child tasks (open only) cup subtasks abc123def --include-closed # all child tasks cup comments abc123def # discussion cup activity abc123def # task + comments combined ``` ### Find tasks ```bash cup tasks --status "in progress" # by status cup tasks --name "login" # by partial name cup tasks --type initiative # initiatives only cup tasks --list 12345 --all # all tasks in list, not just mine cup tasks --tag "bug" --status "to do" # by tag and status cup tasks --list 123 --field "Sprint" "Week 1" # by custom field cup tasks --due-before 2026-04-01 # due before a date cup tasks --assignee me --created-after 2026-03-01 # my tasks created recently cup search "payment flow" # multi-word search cup search auth --status "prog" # fuzzy status match cup search "auth" --list 123 --space 456 # search within list and space cup search --assignee me # no query — all my tasks cup search --assignee me --status "in progress" # filter without query cup sprint # current sprint cup assigned # all my tasks by status cup overdue # past due date cup inbox --days 7 # recently updated ``` ### Make changes ```bash cup update abc123def -s "done" cup update abc123def --priority high --due-date 2025-03-15 cup update abc123def --due-date 2025-03-15T14:30 # date + time (user's timezone) cup update abc123def --due-date 2025-03-15T14:30:00Z # UTC cup create -n "Fix the thing" --parent abc123def # -p is the global --profile, not --parent cup create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend" cup create -n "Bug fix" -l sprint:current # create in active sprint cup create -n "Q3 Roadmap" -l <listId> --custom-item-id 1 cup create -n "New story" -l <listId> --field "Story Points" 5 --field "Stage" "In Review" cup comment abc123def -m "Completed in PR #42" cup comment abc123def -m "## Results\n\n**Passed**: 15/15\n- Unit tests\n- Integration" cup assign abc123def --to me cup assign abc123def --to 12345,67890 # assign multiple users at once cup assign abc123def --group @mobile-team # assign a user group (find handles with `cup groups`) cup assign abc123def --to me --group @backend # assign self and a group together cup update abc123def --group-assignee @mobile-team # group assignment via update cup update abc123def --remove-group-assignee @backend cup depend task3 --on task2 # task3 waits for task2 cup move task1 --to list2 # add task1 to list2 (multi-list membership) cup move task1 --to list2 --remove list1 # change home list from list1 to list2 (v3 home_list) cup move task1 --to sprint:current --remove list1 # move home list to active sprint cup field abc123def --set "Story Points" 5 cup tag abc123def --add "bug,frontend" cup checklist create abc123def "QA Steps" cup checklist add-item <clId> "Run unit tests" cup checklist add-item <clId> "Sub step" --parent <itemId> # nest under parent cup checklist edit-item <clId> <itemId> --resolved cup checklist edit-item <clId> <itemId> --parent <newParent> # reparent (use "null" to unnest) cup link abc123 def456 cup attach abc123def ./screenshot.png cup time start abc123def -d "Working on feature" cup time stop cup time log abc123def 2h -d "Code review" cup delete abc123def --confirm # irreversible! ``` ### Multiline markdown descriptions and comments Agents produce structured markdown (headings, bullets, code, apostrophes). Shell quoting is the main failure point. Two robust patterns: ```bash # 1. Best for agents: write markdown to a file, then reference it (no shell quoting at all) cup create -n "Improve onboarding" -l <listId> --description-file /tmp/desc.md cup update <taskId> --description-file /tmp/desc.md cup comment <taskId> --message-file /tmp/comment.md cup field <taskId> --set "Standup 4 - 6/25" --value-file /tmp/note.md # "-" reads stdin: printf '## Notes\n\nTeam'\''s update with `code`.' | cup update <taskId> --description-file - # 2. Inline multiline: quoted heredoc preserves backticks, newlines, AND apostrophes cup create -n "Improve onboarding" -l <listId> -d "$(cat <<'EOF' ## Overview Refresh the team's onboarding docs. Use `init()` first. ## Goals - Goal one - Goal two EOF )" ``` Do **not** use `$'…team'\''s…\n\n## Goals'` — after the `'\''` apostrophe break the string is in normal single quotes, so `\n` is passed literally and headings/bullets render as `\n\n` text in ClickUp. ### Docs ```bash cup docs "design" # search docs cup doc <docId> <pageId> # view page cup doc-create "Architecture Notes" -c "# Draft" cup doc-page-create <docId> "Section" --parent-page <pageId> cup doc-page-edit <docId> <pageId> -c "# Updated" ``` ### Export (knowledge transfer / off-boarding) Every task stored once (`tasks/<id>/task.json` + `task.md` + comments + attachments); each scope adds an index. Slices compose into one `--out` dir; shared tasks are fetched once. Re-runs skip what is already there. ```bash cup export user me --out ./archive # my tasks, incl. closed + archived cup export team "Atlas" --out ./archive # every list in a space cup export roadmap <listId> --item-id 1004 --out ./archive # initiatives grouped with subtask trees cup export docs --out ./archive # every doc as markdown page trees cup export all --dry-run # plan: counts, estimated time cup export all --yes --out ./archive # whole workspace (long-running; confirms) ``` - `--item-id` is the initiative `custom_item_id` (team convention; `cup task-types` lists them). - `all` refuses to run non-interactively without `--yes`; always `--dry-run` first to see the estimate. - Whiteboards, dashboards, automations have no API: export those from the UI by hand. ### Workspace structure ```bash cup spaces --name "Engineering" # find space ID cup folders <spaceId> # folders with their lists cup lists <spaceId> # lists in a space cup space-create "New Space" # create a space cup folder-create <spaceId> "Q2" # create a folder cup list-create <spaceId> "Backlog" # create a list cup list-create <spaceId> "Sprint" --folder <folderId> cup space-rename <spaceId> "Platform" # rename a space cup folder-rename <folderId> "Q3" # rename a folder cup list-rename <listId> "Sprint 12" # rename a list cup members # workspace members cup groups # user groups/teams (for --group-assignee) cup fields <listId> # custom fields on a list cup task-types # custom task types cup templates # task templates ``` ### Goals ```bash cup goals cup goal-create "Ship v2" -d "Release version 2" cup key-results g123 cup key-result-create g123 "API coverage" --type percentage --target 80 cup key-result-update kr456 --progress 60 --note "On track" ``` ### Profiles ```bash cup profile add personal # add a profile (interactive) cup profile list # list all profiles cup profile use personal # switch default cup tasks -p work # use specific profile for one command ``` ### Favorites ```bash cup favorite add sprint-folder 12345 --name "Team Sprint" # favorite a sprint folder cup favorite add space 67890 eng # favorite a space with alias cup favorite list # list all favorites cup favorite list --type sprint-folder # list only sprint folders cup favorite remove eng # remove by alias cup sprint # auto-uses favorited sprint folder ``` ### Standup ```bash cup summary # completed / in progress / overdue cup summary --hours 48 # wider window ``` ## DELETE SAFETY IMPORTANT: Always confirm with the user before running `cup delete`, `cup list-delete`, `cup folder-delete`, `cup space-delete`, `cup merge`, or `cup webhook delete`. These are destructive, irreversible operations. Even when using `--confirm` flag, verify the ID is correct with the user first.

--- 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 ` installs to a custom location, `cup skill --print` writes it to stdout). ## Install & Configure ### Prerequisites Node.js 22+ required. ### Install ```bash npm install -g @krodak/clickup-cli ``` Or via Homebrew: ```bash 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):** ```bash 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):** ```bash cup init ``` **Environment variables (no config file needed):** ```bash export CU_API_TOKEN="pk_..." export CU_TEAM_ID="12345678" ``` ### Verify ```bash 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 ` to create, `cup profile use ` to switch, or `-p ` 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 ` | Execute a saved shortcut (identical to running the full command) | | `cup filter save [args...] [-d desc]` | Save a command shortcut | | `cup filter delete ` | Remove a shortcut | | `cup filter show [--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 ` 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 ` | Single task details (custom fields, checklists, attachments, deps, links) | | `cup subtasks [--status s] [--name q] [--include-closed]` | Subtasks of a task | | `cup comments ` | Comments on a task | | `cup activity ` | 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 [--name partial] [--archived]` | Lists in a space (including folder lists) | | `cup folders [--name partial] [--archived]` | Folders in a space (with their lists); JSON includes `parent_folder` for subfolders | | `cup time-in-status ` | Show how long a task has been in each status | | `cup members` | Workspace members (username, ID, email) | | `cup groups` | User groups/teams (handle, name, UUID, member count) for `--group-assignee` flags | | `cup fields ` | Custom fields on a list (type, required, options) | | `cup attachments ` | List attachments on a task (name, size, URL) | | `cup attach-get [idOrTitle] [-o\|--output path] [--all] [--dir d] [--force]` | Download task attachment(s). No selector + 1 attachment downloads it; multiple requires a selector or `--all`. Saves to the attachment's filename by default | | `cup task-members ` | List members with access to a task | | `cup plan` | Show workspace plan and usage | | `cup tags ` | Tags available in a space | | `cup goals` | Workspace goals with progress | | `cup key-results ` | Key results for a goal | | `cup docs [query]` | Workspace docs (optionally filter by name) | | `cup doc [pageId]` | Doc metadata + page tree, or a specific page | | `cup doc-pages ` | All pages in a doc with content | | `cup task-types` | Custom task types (for `--custom-item-id`) | | `cup templates` | Task templates (for `--template`) | | `cup list-templates` | List templates (for `list-from-template`) | | `cup folder-templates` | Folder templates | | `cup views [--space\|--folder\|--workspace]` | List views on a list (default), space, folder, or workspace (`cup views any --workspace`) | | `cup view ` | Get view details | | `cup view-tasks [--me]` | List tasks in a view (`--me` filters to you) | | `cup open ` | Open task in browser by ID or name | | `cup auth` | Check authentication status | | `cup list-comments ` | Comments on a list | | `cup view-comments ` | Comments on a view | | `cup webhook list` | List webhooks in workspace | | `cup shared` | Shared spaces, folders, and lists | | `cup chat channels [--all] [--type type]` | List chat channels | | `cup chat channel ` | Show channel details | | `cup chat messages [--limit n]` | List channel messages | | `cup chat members ` | List channel members | | `cup chat followers ` | List channel followers | | `cup chat replies ` | List message replies | | `cup chat reactions ` | List reactions on a message | | `cup export user\|team\|roadmap\|initiatives\|docs\|all ... [--out dir] [--dry-run] [--item-id n] [--yes]` | Export tasks/docs to a local archive (lossless JSON + markdown). See Export below | ### Write | Command | What it does | | --- | --- | | `cup create -n name [-l listId\|sprint:current] [--parent parentId] [-d desc\|--description-file path] [-s status] [--priority p] [--due-date d] [--start-date d] [--time-estimate t] [--assignee id\|me] [--group-assignee uuid\|@handle,...] [--tags t] [--custom-item-id n] [--template id] [--field "Name" val]` | Create task (`--list` accepts `sprint:current`, `--field` sets custom fields inline; `--description-file` reads markdown from a file or `-` for stdin) | | `cup update [-n name] [-d desc\|--description-file path] [-s status] [--priority p] [--due-date d\|none] [--start-date d] [--time-estimate t] [--assignee id\|me] [--remove-assignee id\|me] [--group-assignee uuid\|@handle] [--remove-group-assignee uuid\|@handle] [--parent id] [--archive] [--unarchive] [--type type] [--field "Name" val]` | Update task fields (`--description-file` reads markdown from a file or `-` for stdin) | | `cup comment -m text\|--message-file path [--notify-all] [--mention user]` | Post comment (markdown auto-converted to rich text; `--message-file` reads from a file or `-` for stdin; `--mention` for real @mentions, repeatable) | | `cup comment-edit -m text\|--message-file path [--resolved] [--unresolved] [--mention user]` | Edit a comment (markdown auto-converted to rich text; `--mention` for real @mentions) | | `cup comment-delete ` or `cup comment-delete --task --mine [--match text]` | Delete a comment by ID or delete one of your task comments | | `cup replies ` | List threaded replies | | `cup reply -m text\|--message-file path [--notify-all] [--mention user]` | Reply to a comment (markdown auto-converted to rich text; `--message-file` reads from a file or `-` for stdin; `--mention` for real @mentions) | | `cup assign [--to ids\|me] [--remove ids\|me] [--group uuid\|@handle,...] [--remove-group uuid\|@handle,...]` | Assign/unassign users and groups (all flags accept comma-separated values) | | `cup depend [--on taskId] [--blocks taskId] [--remove]` | Add/remove dependencies | | `cup move [--to listId\|sprint:current] [--remove listId]` | Add/remove task from lists. **`--to` + `--remove` together changes the task's _home_ list** (uses v3 `home_list` endpoint with auto status mapping). `--to` alone adds multi-list membership. `--to` accepts `sprint:current`. | | `cup field [--set "Name" value\|--set "Name" --value-file path] [--remove "Name"]` | Set/remove custom field values (`--value-file` reads the value from a file or `-` for stdin; use for long/free-text values) | | `cup field-create -t [-d desc] [--options "a,b,c"] [--required] [--list id] [--lists id1,id2]` | Create a custom field — workspace-wide (default), on one list (`--list`), or bulk across lists (`--lists`, parallel, per-list reporting) | | `cup tag [--add tags] [--remove tags]` | Add/remove tags on a task | | `cup link [--remove]` | Link/unlink tasks | | `cup attach ` | Upload file attachment | | `cup delete [--confirm]` | Delete task (DESTRUCTIVE) | | `cup list-delete [--confirm]` | Delete list (DESTRUCTIVE, requires --confirm in non-interactive) | | `cup folder-delete [--confirm]` | Delete folder (DESTRUCTIVE, requires --confirm in non-interactive) | | `cup space-delete [--confirm]` | Delete space (DESTRUCTIVE, requires --confirm in non-interactive) | | `cup duplicate ` | Duplicate a task | | `cup bulk status ` | Bulk update status | | `cup bulk assign [--to userId\|me] [--remove userId\|me]` | Bulk assign/unassign user from tasks | | `cup bulk due-date ` | Bulk set or clear due dates | | `cup bulk tag [--remove]` | Bulk add/remove tag from tasks | | `cup bulk priority --to ` | Bulk set priority on many tasks | | `cup bulk field --set "Name" value` | Bulk set a custom field value | | `cup bulk move --to ` | Bulk move tasks to a destination list | | `cup checklist view ` | View checklists on a task | | `cup checklist create ` | Create a checklist | | `cup checklist delete ` | Delete a checklist | | `cup checklist add-item [--parent itemId]` | Add item to checklist (nest under parent via `--parent`) | | `cup checklist edit-item [--name n] [--resolved] [--unresolved] [--assignee id] [--parent itemId\|null]` | Edit checklist item (reparent with `--parent`, use `"null"` to unnest) | | `cup checklist delete-item ` | Delete checklist item | | `cup time start [-d desc]` | Start timer | | `cup time stop` | Stop running timer | | `cup time status` | Show running timer | | `cup time log [-d desc]` | Log manual entry (e.g. "2h", "30m") | | `cup time list [--days n] [--task id] [--all]` | List my recent time entries (--all for team) | | `cup time update [-d desc] [--duration dur]` | Update time entry | | `cup time delete ` | Delete time entry | | `cup goal-create [-d desc] [--color hex]` | Create a goal | | `cup goal-update [-n name] [-d desc] [--color hex]` | Update a goal | | `cup goal-delete ` | Delete a goal | | `cup key-result-create [--type t] [--target n]` | Create key result | | `cup key-result-update [--progress n] [--note text]` | Update key result | | `cup key-result-delete ` | Delete key result | | `cup doc-create [-c content]` | Create a doc (root page is named after the title; `-c` writes its markdown content) | | `cup doc-page-create <docId> <name> [-c content\|--content-file path] [--parent-page pageId]` | Create doc page (`--content-file` reads markdown from a file or `-` for stdin) | | `cup doc-page-edit <docId> <pageId> [--name text] [-c content\|--content-file path]` | Edit doc page (`--content-file` reads markdown from a file or `-` for stdin) | | `cup doc-delete <docId>` | **Not supported** — ClickUp has no delete-Doc API (HTTP 405). Fails fast; delete Docs in the UI. Use `cup doc-page-delete` for a single page | | `cup doc-page-delete <docId> <pageId>` | Delete doc page | | `cup space-create <name>` | Create a space | | `cup list-create <spaceId> <name> [--folder folderId] [--copy-statuses-from id]` | Create a list in a space or folder | | `cup folder-create <spaceId> <name>` | Create a folder in a space | | `cup list-rename <listId> <newName>` | Rename a list | | `cup folder-rename <folderId> <newName>` | Rename a folder | | `cup space-rename <spaceId> <newName>` | Rename a space | | `cup tag-create <spaceId> <name> [--fg color] [--bg color]` | Create space tag | | `cup tag-update <spaceId> <tagName> --name <newName> [--fg c] [--bg c]` | Update space tag | | `cup tag-delete <spaceId> <name>` | Delete space tag | | `cup list-from-template <name> --template <id> [--space id] [--folder id]` | Create list from template | | `cup view-create <listId> <name> -t <type> [--group-by field]` | Create a view on a list | | `cup view-update <viewId> [-n name] [--group-by field]` | Update a view | | `cup view-delete <viewId> [--confirm]` | Delete a view (DESTRUCTIVE) | | `cup list-comment <listId> -m text [--notify-all] [--mention user]` | Post comment on a list (`--mention` for real @mentions) | | `cup view-comment <viewId> -m text [--notify-all] [--mention user]` | Post comment on a view (`--mention` for real @mentions) | | `cup webhook create --url <url> --events <events> [--space\|--folder\|--list\|--task <id>]` | Create a webhook | | `cup webhook update <webhookId> [--url u] [--events e] [--status s]` | Update a webhook | | `cup webhook delete <webhookId> [--confirm]` | Delete a webhook (DESTRUCTIVE) | | `cup merge <sourceTaskId> <intoTaskId> [--confirm]` | Merge task into another (DESTRUCTIVE, source deleted) | | `cup time estimate-by-user <taskId> <userId> <duration> [--replace]` | Set per-user time estimate | | `cup chat send <channelId> -m <text> [--post --title t]` | Send message to channel | | `cup chat reply <messageId> -m <text>` | Reply to a message | | `cup chat react <messageId> --emoji <name>` | Add reaction | | `cup chat unreact <messageId> --emoji <name>` | Remove reaction | | `cup chat channel-create <name> [--private] [--topic t]` | Create channel | | `cup chat dm <userIds...>` | Create/open DM | | `cup chat channel-update <id> [--name n] [--topic t]` | Update channel | | `cup chat channel-delete <id> [--confirm]` | Delete channel | | `cup chat message-update <messageId> -m <text>` | Edit message | | `cup chat message-delete <messageId> [--confirm]` | Delete message | | `cup favorite add <type> <id> [alias] [-n name]` | Add a local favorite | | `cup favorite remove <alias>` | Remove a favorite | | `cup favorite list [--type t]` | List favorites (optionally filter by type) | | `cup profile list [--json]` | List all profiles | | `cup profile add <name>` | Add a new profile (interactive) | | `cup profile remove <name>` | Remove a profile | | `cup profile use <name>` | Set the default profile | | `cup config get <key>` / `set <key> <value>` / `path` | Manage config | | `cup completion <shell>` | Shell completions (bash/zsh/fish) | ## Global Flags | Flag | Description | | --- | --- | | `-p, --profile <n>` | Use a specific profile for this command | | `--json` | Force JSON output (available on all commands) | > **`-p` is always `--profile`, never `--parent`.** Global short flags win over subcommand > ones, so `cup create -p <taskId>` fails with `Profile "<taskId>" not found`. Use > `cup create --parent <taskId>`. ## Flags & Conventions | Topic | Detail | | --- | --- | | Task IDs | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format | | Task URLs | All commands that accept a task ID also accept full ClickUp URLs (`https://app.clickup.com/t/<id>` or `https://app.clickup.com/t/<workspace>/<id>`). The ID is auto-extracted | | View URLs | All commands that accept a view ID also accept full ClickUp view URLs (`https://app.clickup.com/<workspace>/v/<type>/<viewId>`). The ID is auto-extracted | | `--status` | Fuzzy matching: exact > starts-with > contains. Prints match to stderr | | `--priority` | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4) | | `--due-date` | `YYYY-MM-DD` (date only), `YYYY-MM-DDTHH:MM` (with time), or full ISO 8601 with offset. Time-of-day formats set `due_date_time: true` in ClickUp | | `--assignee` | User ID or `me` | | `--tags` | Comma-separated (e.g. `--tags "bug,frontend"`) | | `--time-estimate` | Duration: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds | | `--type` | `task` (regular) or custom type name/ID (e.g. `initiative`, `Bug`) | | `--custom-item-id` | Custom task type ID for `cup create` (find with `cup task-types`) | | `--space` | Partial name match or exact ID | | `--name` | Partial match, case-insensitive | | `--all` | Show all tasks in workspace, not just assigned to me. Available on `tasks`, `search`, `overdue`. Default: my tasks only (smaller output for agent context windows) | | `--include-closed` | Include closed/done tasks | | `--list` on create | Optional when `--parent` is given (auto-detected). Accepts `sprint:current` pseudo-ID | | `cup field --set` | Supports: text, number, checkbox (true/false), dropdown (option name), labels (comma-separated names), date (YYYY-MM-DD), url, email, emoji/rating (0-5), manual_progress (0-100), tasks/relationship (comma-separated task IDs), users/people (comma-separated user IDs). Names resolved case-insensitively; errors list available fields/options | | `cup field-create` | Use `--options "a,b,c"` for `drop_down` and `labels` types (required). Other types don't need `--options` | | `--field` filter | `--field "Name" value` on `tasks` and `search` requires `--list` to resolve field names to IDs | | `--due-before/after` | `YYYY-MM-DD` date filters for due date range | | `--created-before/after` | `YYYY-MM-DD` date filters for creation date range | | `cup sprint` | Auto-detects active sprint by folder name (sprint/iteration/cycle/scrum), parses multiple date formats. Override with `--folder <id>`, `cup config set sprintFolderId <id>`, or favorite a sprint folder | | `cup favorite` | Local-only favorites (not synced to ClickUp). Types: sprint-folder, space, list, folder, view, task. Favorited sprint-folders auto-used by sprint commands | | `cup link` | Both IDs must be the same type (both custom or both native) | | `cup delete` | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone | | Errors | Exit code 1 on errors. `cup auth --json` (also `CU_OUTPUT=json`) keeps authentication failures as JSON on stdout; other errors go to stderr. Strict parsing rejects excess/unknown arguments | | Rate limiting | The client retries HTTP 429 with `Retry-After`-aware backoff (up to 3 retries). Transient 502/503/504 retries are limited to GET/HEAD reads. Mutations are not replayed after gateway errors or transport failures: check remote state before retrying. Warnings go to stderr | | Multiline markdown (`-d` / `-m` / field values) | **Best for agents:** use `--description-file <path>` / `--message-file <path>` / `--value-file <path>` (or `-` for stdin) to bypass shell quoting entirely — see the multiline example below. For inline multiline, use a **quoted heredoc** `"$(cat <<'EOF' … EOF)"` — it preserves backticks, newlines, and apostrophes. **Footgun:** never split a `$'...'` string with `'\''` for an apostrophe — the tail drops back to normal single quotes and `\n` becomes literal text (e.g. `$'…team'\''s…\n## Goals'` breaks). Plain double quotes execute backticks as commands. | | `--mention <user>` | Real ClickUp @mention (notifies the user). Accepts ID, email, username, or `me`. Repeatable. Also: `<@userId>` inline token in `-m` for mid-sentence mentions. Bare `@Name` is NOT parsed (ambiguous). On `comment`, `reply`, `comment-edit`, `list-comment`, `view-comment` | | Comment links | In comment messages, bare URLs (`https://...`) and markdown links (`[text](url)`) both render as clickable links. Unfurled preview cards are not supported (web-UI only) | > **Note:** `cup search`, `cup tasks`, `cup overdue`, and `cup assigned` default to tasks assigned to the current user. Use `--all` to include tasks assigned to others. This matters when searching for parent initiatives or team-wide items. ## Interactive Mode (TTY) When running in a terminal (not piped), task-listing commands (`cup tasks`, `cup search`, `cup sprint`, `cup overdue`, `cup assigned`, `cup inbox`, `cup summary`) present an interactive task picker: - **↑/↓** or **j/k** to navigate the list - **Space** to toggle task selection - **Enter** to confirm and view details of selected tasks - After viewing details, prompted to open tasks in browser Other interactive prompts: sprint selection (when multiple match), workspace selection (`cup init`), agent selection (`cup skill`), destructive action confirmations (`cup delete`, `cup list-delete`, `cup folder-delete`, `cup space-delete`, `cup archive`, `cup view-delete`, `cup merge`, `cup webhook delete`). When piped or called with `--json`, all commands output non-interactive markdown or JSON. Agents should always use `--json` for structured data or pipe for markdown. ## Agent Workflow Examples ### Investigate a task ```bash cup task abc123def # markdown summary cup subtasks abc123def # child tasks (open only) cup subtasks abc123def --include-closed # all child tasks cup comments abc123def # discussion cup activity abc123def # task + comments combined ``` ### Find tasks ```bash cup tasks --status "in progress" # by status cup tasks --name "login" # by partial name cup tasks --type initiative # initiatives only cup tasks --list 12345 --all # all tasks in list, not just mine cup tasks --tag "bug" --status "to do" # by tag and status cup tasks --list 123 --field "Sprint" "Week 1" # by custom field cup tasks --due-before 2026-04-01 # due before a date cup tasks --assignee me --created-after 2026-03-01 # my tasks created recently cup search "payment flow" # multi-word search cup search auth --status "prog" # fuzzy status match cup search "auth" --list 123 --space 456 # search within list and space cup search --assignee me # no query — all my tasks cup search --assignee me --status "in progress" # filter without query cup sprint # current sprint cup assigned # all my tasks by status cup overdue # past due date cup inbox --days 7 # recently updated ``` ### Make changes ```bash cup update abc123def -s "done" cup update abc123def --priority high --due-date 2025-03-15 cup update abc123def --due-date 2025-03-15T14:30 # date + time (user's timezone) cup update abc123def --due-date 2025-03-15T14:30:00Z # UTC cup create -n "Fix the thing" --parent abc123def # -p is the global --profile, not --parent cup create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend" cup create -n "Bug fix" -l sprint:current # create in active sprint cup create -n "Q3 Roadmap" -l <listId> --custom-item-id 1 cup create -n "New story" -l <listId> --field "Story Points" 5 --field "Stage" "In Review" cup comment abc123def -m "Completed in PR #42" cup comment abc123def -m "## Results\n\n**Passed**: 15/15\n- Unit tests\n- Integration" cup assign abc123def --to me cup assign abc123def --to 12345,67890 # assign multiple users at once cup assign abc123def --group @mobile-team # assign a user group (find handles with `cup groups`) cup assign abc123def --to me --group @backend # assign self and a group together cup update abc123def --group-assignee @mobile-team # group assignment via update cup update abc123def --remove-group-assignee @backend cup depend task3 --on task2 # task3 waits for task2 cup move task1 --to list2 # add task1 to list2 (multi-list membership) cup move task1 --to list2 --remove list1 # change home list from list1 to list2 (v3 home_list) cup move task1 --to sprint:current --remove list1 # move home list to active sprint cup field abc123def --set "Story Points" 5 cup tag abc123def --add "bug,frontend" cup checklist create abc123def "QA Steps" cup checklist add-item <clId> "Run unit tests" cup checklist add-item <clId> "Sub step" --parent <itemId> # nest under parent cup checklist edit-item <clId> <itemId> --resolved cup checklist edit-item <clId> <itemId> --parent <newParent> # reparent (use "null" to unnest) cup link abc123 def456 cup attach abc123def ./screenshot.png cup time start abc123def -d "Working on feature" cup time stop cup time log abc123def 2h -d "Code review" cup delete abc123def --confirm # irreversible! ``` ### Multiline markdown descriptions and comments Agents produce structured markdown (headings, bullets, code, apostrophes). Shell quoting is the main failure point. Two robust patterns: ```bash # 1. Best for agents: write markdown to a file, then reference it (no shell quoting at all) cup create -n "Improve onboarding" -l <listId> --description-file /tmp/desc.md cup update <taskId> --description-file /tmp/desc.md cup comment <taskId> --message-file /tmp/comment.md cup field <taskId> --set "Standup 4 - 6/25" --value-file /tmp/note.md # "-" reads stdin: printf '## Notes\n\nTeam'\''s update with `code`.' | cup update <taskId> --description-file - # 2. Inline multiline: quoted heredoc preserves backticks, newlines, AND apostrophes cup create -n "Improve onboarding" -l <listId> -d "$(cat <<'EOF' ## Overview Refresh the team's onboarding docs. Use `init()` first. ## Goals - Goal one - Goal two EOF )" ``` Do **not** use `$'…team'\''s…\n\n## Goals'` — after the `'\''` apostrophe break the string is in normal single quotes, so `\n` is passed literally and headings/bullets render as `\n\n` text in ClickUp. ### Docs ```bash cup docs "design" # search docs cup doc <docId> <pageId> # view page cup doc-create "Architecture Notes" -c "# Draft" cup doc-page-create <docId> "Section" --parent-page <pageId> cup doc-page-edit <docId> <pageId> -c "# Updated" ``` ### Export (knowledge transfer / off-boarding) Every task stored once (`tasks/<id>/task.json` + `task.md` + comments + attachments); each scope adds an index. Slices compose into one `--out` dir; shared tasks are fetched once. Re-runs skip what is already there. ```bash cup export user me --out ./archive # my tasks, incl. closed + archived cup export team "Atlas" --out ./archive # every list in a space cup export roadmap <listId> --item-id 1004 --out ./archive # initiatives grouped with subtask trees cup export docs --out ./archive # every doc as markdown page trees cup export all --dry-run # plan: counts, estimated time cup export all --yes --out ./archive # whole workspace (long-running; confirms) ``` - `--item-id` is the initiative `custom_item_id` (team convention; `cup task-types` lists them). - `all` refuses to run non-interactively without `--yes`; always `--dry-run` first to see the estimate. - Whiteboards, dashboards, automations have no API: export those from the UI by hand. ### Workspace structure ```bash cup spaces --name "Engineering" # find space ID cup folders <spaceId> # folders with their lists cup lists <spaceId> # lists in a space cup space-create "New Space" # create a space cup folder-create <spaceId> "Q2" # create a folder cup list-create <spaceId> "Backlog" # create a list cup list-create <spaceId> "Sprint" --folder <folderId> cup space-rename <spaceId> "Platform" # rename a space cup folder-rename <folderId> "Q3" # rename a folder cup list-rename <listId> "Sprint 12" # rename a list cup members # workspace members cup groups # user groups/teams (for --group-assignee) cup fields <listId> # custom fields on a list cup task-types # custom task types cup templates # task templates ``` ### Goals ```bash cup goals cup goal-create "Ship v2" -d "Release version 2" cup key-results g123 cup key-result-create g123 "API coverage" --type percentage --target 80 cup key-result-update kr456 --progress 60 --note "On track" ``` ### Profiles ```bash cup profile add personal # add a profile (interactive) cup profile list # list all profiles cup profile use personal # switch default cup tasks -p work # use specific profile for one command ``` ### Favorites ```bash cup favorite add sprint-folder 12345 --name "Team Sprint" # favorite a sprint folder cup favorite add space 67890 eng # favorite a space with alias cup favorite list # list all favorites cup favorite list --type sprint-folder # list only sprint folders cup favorite remove eng # remove by alias cup sprint # auto-uses favorited sprint folder ``` ### Standup ```bash cup summary # completed / in progress / overdue cup summary --hours 48 # wider window ``` ## DELETE SAFETY IMPORTANT: Always confirm with the user before running `cup delete`, `cup list-delete`, `cup folder-delete`, `cup space-delete`, `cup merge`, or `cup webhook delete`. These are destructive, irreversible operations. Even when using `--confirm` flag, verify the ID is correct with the user first.