# Krodak Clickup CLI Clickup CLI > ClickUp CLI (`cup`) - skill version 1.38.2 - Skill: `tomevault-io/krodak-clickup-cli-clickup-cli` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/krodak-clickup-cli-clickup-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/krodak-clickup-cli-clickup-cli/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/krodak-clickup-cli-clickup-cli --- # ClickUp CLI (`cup`) - skill version 1.38.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.38.2, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`. ## 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 [--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 ` | 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) | | `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 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 ` | List views on a list | | `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 | ### 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 [-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] [--archive] [--unarchive] [--type type] [--field "Name" val]` | Update task fields (including custom fields and group assignees) | | `cup comment -m text [--notify-all] [--mention user]` | Post comment (markdown auto-converted to rich text; `--mention` for real @mentions, repeatable) | | `cup comment-edit -m text [--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 [--notify-all] [--mention user]` | Reply to a comment (markdown auto-converted to rich text; `--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] [--remove "Name"]` | Set/remove custom field 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 …(truncated)