ClickUp CLI (cup) - skill version 1.26.0
Reference for AI agents using the cup CLI tool. Covers task management, sprint tracking, comments, time tracking, custom fields, goals, docs, and project workflows.
Version check: Runcup --version. If your installed version is older than 1.26.0, update withnpm install -g @krodak/clickup-cliand refresh this skill withcup skill.
Install & Configure
Prerequisites
Node.js 22+ required.
Install
npm install -g @krodak/clickup-cliOr via Homebrew:
brew tap krodak/tap && brew install clickup-cliGet an API token
The user needs a personal API token from ClickUp:
- Open https://app.clickup.com/settings/apps
- Under "API Token", click "Generate" (or copy existing)
- The token starts with
pk_
Configure
Non-interactive (recommended for agents):
cup init --token pk_USER_TOKEN --team TEAM_IDTo 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 initEnvironment variables (no config file needed):
export CU_API_TOKEN="pk_..."
export CU_TEAM_ID="12345678"Verify
cup authThis 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--jsonfor the full raw API object- Set
CU_OUTPUT=jsonto always get JSON when piped - Agents typically don't need
--jsonunless parsing structured data withjq
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]` | My tasks (filter by status, name, type, list, space, assignee, tag, dates, custom fields). --all for all tasks in workspace |
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 my tasks by name. --all for all tasks |
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 lists) | |
cup folders <spaceId> [--name partial] [--archived] | Folders in a space (with their lists) | |
cup time-in-status <id> | Show how long a task has been in each status | |
cup members | Workspace members (username, ID, email) | |
cup fields <listId> | Custom fields on a list (type, required, options) | |
cup tags <spaceId> | Tags available in a space | |
cup goals | Workspace goals with progress | |
cup key-results <goalId> | Key results for a goal | |
cup docs [query] | Workspace docs (optionally filter by name) | |
cup doc <docId> [pageId] | Doc metadata + page tree, or a specific page | |
cup doc-pages <docId> | 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 <listId> | List views on a list | |
cup view <viewId> | Get view details | |
cup open <query> | Open task in browser by ID or name | |
cup auth | Check authentication status |
Write
| Command | What it does | |||
|---|---|---|---|---|
| `cup create -n name [-l listId\ | sprint:current] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--start-date d] [--time-estimate t] [--assignee id\ | me] [--tags t] [--custom-item-id n] [--template id] [--field "Name" val]` | Create task (--list accepts sprint:current, --field sets custom fields inline) | |
| `cup update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d\ | none] [--start-date d] [--time-estimate t] [--assignee id\ | me] [--remove-assignee id\ | me] [--parent id] [--detach] [--archive] [--unarchive] [--type type] [--field "Name" val]` | Update task fields (including custom fields) |
cup comment <id> -m text [--notify-all] | Post comment (markdown auto-converted to rich text) | |||
cup comment-edit <commentId> -m text [--resolved] [--unresolved] | Edit a comment (markdown auto-converted to rich text) | |||
cup comment-delete <commentId> or cup comment-delete --task <taskId> --mine [--match text] | Delete a comment by ID or delete one of your task comments | |||
cup replies <commentId> | List threaded replies | |||
cup reply <commentId> -m text [--notify-all] | Reply to a comment (markdown auto-converted to rich text) | |||
| `cup assign <id> [--to ids\ | me] [--remove ids\ | me]` | Assign/unassign users (--to/--remove accept comma-separated IDs) | |
cup depend <id> [--on taskId] [--blocks taskId] [--remove] | Add/remove dependencies | |||
| `cup move <id> [--to listId\ | sprint:current] [--remove listId]` | Add/remove task from lists (--to accepts sprint:current) | ||
cup field <id> [--set "Name" value] [--remove "Name"] | Set/remove custom field values | |||
cup field-create <name> -t <type> [-d desc] [--options "a,b,c"] [--required] | Create a custom field | |||
cup tag <id> [--add tags] [--remove tags] | Add/remove tags on a task | |||
cup link <taskId> <linksTo> [--remove] | Link/unlink tasks | |||
cup attach <taskId> <filePath> | Upload file attachment | |||
cup delete <id> [--confirm] | Delete task (DESTRUCTIVE) | |||
cup duplicate <taskId> | Duplicate a task | |||
cup bulk status <status> <taskIds...> | Bulk update status | |||
| `cup bulk assign <taskIds...> [--to userId\ | me] [--remove userId\ | me]` | Bulk assign/unassign user from tasks | |
| `cup bulk due-date <date\ | none\ | clear> <taskIds...>` | Bulk set or clear due dates | |
cup bulk tag <tagName> <taskIds...> [--remove] | Bulk add/remove tag from tasks | |||
cup bulk priority <taskIds...> --to <priority> | Bulk set priority on many tasks | |||
cup bulk field <taskIds...> --set "Name" value | Bulk set a custom field value | |||
cup bulk move <taskIds...> --to <listId> | Bulk move tasks to a destination list | |||
cup checklist view <id> | View checklists on a task | |||
cup checklist create <id> <name> | Create a checklist | |||
cup checklist delete <checklistId> | Delete a checklist | |||
cup checklist add-item <checklistId> <name> [--parent itemId] | Add item to checklist (nest under parent via --parent) | |||
| `cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--parent itemId\ | null]` | Edit checklist item (reparent with --parent, use "null" to unnest) | ||
cup checklist delete-item <checklistId> <itemId> | Delete checklist item | |||
cup time start <taskId> [-d desc] | Start timer | |||
cup time stop | Stop running timer | |||
cup time status | Show running timer | |||
cup time log <taskId> <duration> [-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 <timeEntryId> [-d desc] [--duration dur] | Update time entry | |||
cup time delete <timeEntryId> | Delete time entry | |||
cup goal-create <name> [-d desc] [--color hex] | Create a goal | |||
cup goal-update <goalId> [-n name] [-d desc] [--color hex] | Update a goal | |||
cup goal-delete <goalId> | Delete a goal | |||
cup key-result-create <goalId> <name> [--type t] [--target n] | Create key result | |||
cup key-result-update <keyResultId> [--progress n] [--note text] | Update key result | |||
cup key-result-delete <keyResultId> | Delete key result | |||
cup doc-create <title> [-c content] | Create a doc | |||
cup doc-page-create <docId> <name> [-c content] [--parent-page pageId] | Create doc page | |||
cup doc-page-edit <docId> <pageId> [--name text] [-c content] | Edit doc page | |||
cup doc-delete <docId> | Delete a doc | |||
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 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) |
Flags & Conventions
| Topic | Detail |
|---|---|
| Task IDs | Native (abc123def) or custom (PROJ-123). Custom IDs auto-detected by PREFIX-DIGITS format |
--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 format |
--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 | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected |
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 archive, cup view-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
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 combinedFind tasks
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 sprint # current sprint
cup assigned # all my tasks by status
cup overdue # past due date
cup inbox --days 7 # recently updatedMake changes
cup update abc123def -s "done"
cup update abc123def --priority high --due-date 2025-03-15
cup create -n "Fix the thing" -p abc123def
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 depend task3 --on task2 # task3 waits for task2
cup move task1 --to list2 --remove list1
cup move task1 --to sprint:current # move 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!Docs
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"Workspace structure
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 fields <listId> # custom fields on a list
cup task-types # custom task types
cup templates # task templatesGoals
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
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 commandFavorites
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 folderStandup
cup summary # completed / in progress / overdue
cup summary --hours 48 # wider windowDELETE SAFETY
IMPORTANT: Always confirm with the user before running cup delete. This is a destructive, irreversible operation. Even when using --confirm flag, verify the task ID is correct with the user first.