krodak/clickup

ClickUp CLI (cup) - skill version 1.31.2

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: Run cup --version. If your installed version is older than 1.31.2, update with npm install -g @krodak/clickup-cli and refresh this skill with cup skill.

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 your tasks by name. --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 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 groups | User groups/teams (handle, name, UUID, member count) for --group-assignee flags | | cup fields <listId> | Custom fields on a list (type, required, options) | | cup attachments <taskId> | List attachments on a task (name, size, URL) | | cup task-members <taskId> | List members with access to a task | | cup plan | Show workspace plan and usage | | 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 | | cup list-comments <listId> | Comments on a list | | cup view-comments <viewId> | 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 <id> | Show channel details | | cup chat messages <channelId> [--limit n] | List channel messages | | cup chat members <channelId> | List channel members | | cup chat followers <channelId> | List channel followers | | cup chat replies <messageId> | List message replies | | cup chat reactions <messageId> | List reactions on a message |

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] [--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) | | 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] [--group-assignee uuid\|@handle] [--remove-group-assignee uuid\|@handle] [--parent id] [--detach] [--archive] [--unarchive] [--type type] [--field "Name" val] | Update task fields (including custom fields and group assignees) | | 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] [--group uuid\|@handle,...] [--remove-group uuid\|@handle,...] | Assign/unassign users and groups (all flags accept comma-separated values) | | 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 + --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 <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 list-delete <listId> [--confirm] | Delete list (DESTRUCTIVE, requires --confirm in non-interactive) | | cup folder-delete <folderId> [--confirm] | Delete folder (DESTRUCTIVE, requires --confirm in non-interactive) | | cup space-delete <spaceId> [--confirm] | Delete space (DESTRUCTIVE, requires --confirm in non-interactive) | | 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 list-comment <listId> -m text [--notify-all] | Post comment on a list | | cup view-comment <viewId> -m text [--notify-all] | Post comment on a view | | 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) |

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 (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 | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected | | Description quoting | Use $'...' quoting for -d / -m values containing backticks or newlines: -d $'Use \init()` first.\n\n- Step 1'`. Heredocs and double quotes strip backticks |

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

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

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 updated

Make changes

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

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

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 command

Favorites

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

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.