Linear Issue Workflow
lobehub/lobehub
Handles Linear issues for the team: reading details and images, checking sub-issues, marking progress, labeling AI-created issues and writing completion comments.
Lets your agent read and change ClickUp tasks, sprints, comments, Docs, Chat, views and webhooks through the cup command-line tool.
Install ClickUp CLI
$ npx skills add krodak/clickup-cli --skill clickup -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install krodak/clickup-cli clickup --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/krodak/clickup-cli.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/clickup-cli .claude/skills/clickup && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "clickup" agent skill from https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cli into .claude/skills/clickup/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "clickup", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cliType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add krodak/clickup-cli --skill clickup -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install krodak/clickup-cli clickup --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/krodak/clickup-cli.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/clickup-cli .agents/skills/clickup && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "clickup" agent skill from https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cli into .agents/skills/clickup/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "clickup", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add krodak/clickup-cli --skill clickup -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install krodak/clickup-cli clickup --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/krodak/clickup-cli.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/clickup-cli .cursor/skills/clickup && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "clickup" agent skill from https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cli into .cursor/skills/clickup/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "clickup", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/krodak/clickup-cli.git --path skills/clickup-cli--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add krodak/clickup-cli --skill clickup -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install krodak/clickup-cli clickup --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/krodak/clickup-cli.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/clickup-cli .gemini/skills/clickup && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "clickup" agent skill from https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cli into .gemini/skills/clickup/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "clickup", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install krodak/clickup-cli clickupInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add krodak/clickup-cli --skill clickup -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/krodak/clickup-cli.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/clickup-cli .github/skills/clickup && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "clickup" agent skill from https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cli into .github/skills/clickup/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "clickup", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add krodak/clickup-cli --skill clickup -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install krodak/clickup-cli clickup --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/krodak/clickup-cli.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/clickup-cli .opencode/skills/clickup && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "clickup" agent skill from https://github.com/krodak/clickup-cli/tree/main/skills/clickup-cli into .opencode/skills/clickup/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "clickup", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
clickup- GitHub stars
- 121
- Token cost
- ~8.2k tokens
- SKILL.md length
- 3,108 words
- Files
- 1
- Skills in repo
- 3
- Repo updated
- First seen
- Licence
- MIT
At a glance
Lets your agent read and change ClickUp tasks, sprints, comments, Docs, Chat, views and webhooks through the cup command-line tool.
- Works in 3 steps: Open https://app.clickup.com/settings/apps → Under "API Token", click "Generate" (or… → The token starts with pk_
- Summarizing open and overdue tasks for a standup
- SKILL.md covers Install & Configure, Setup, Saved Filters (Quick Shortcuts) and Output Modes, plus 6 more sections
- Calls npm and brew; needs CU_API_TOKEN
What it does
This is a working reference for the cup CLI, a ClickUp client built for AI agents. It covers querying and updating tasks, sprint tracking, comments with threaded replies, subtasks, checklists, tags, custom fields, time tracking, attachments, goals and key results, plus ClickUp Docs, Chat channels, views, webhooks and the layout of spaces, folders and lists. Export and archive commands support knowledge transfer and off-boarding.
Setup needs Node.js 22 or newer and a personal ClickUp API token that starts with pk_. You run cup init with the token and team ID, or set the CU_API_TOKEN and CU_TEAM_ID environment variables, then confirm with cup auth. Named profiles switch between workspaces, and saved filters give shortcut commands that the agent lists at the start of each session. The file also carries a version check against 1.46.2 and explains how to refresh itself with cup skill.
When your agent uses it
- Summarizing open and overdue tasks for a standup
- Updating task status, assignees or custom fields from the terminal
- Reading, creating or editing ClickUp Docs and doc pages
- Exporting or archiving workspace data before someone leaves the team
Example prompts
- “List my overdue ClickUp tasks and group them by list.”
- “Post a comment on the checkout bug task saying the fix is in review.”
- “Create three subtasks under the onboarding task and assign them to me.”
- “Export everything in the Marketing space so we can archive it before a teammate leaves.”
Requirements
- Node.js 22 or newer
- The cup CLI from the @krodak/clickup-cli npm package
- A ClickUp personal API token and workspace ID
Workflow steps
3 steps, taken from the first numbered list in SKILL.md.
- Open https://app.clickup.com/settings/apps
- Under "API Token", click "Generate" (or copy existing)
- The token starts with pk_
What it can do on your machine
Read from SKILL.md and the folder at commit a775de5. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
npmbrew
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
CU_API_TOKEN
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
ClickUp CLI loads about 8.2k tokens when it runs. Until then it costs about 228 tokens; SKILL.md has 3,108 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from krodak/clickup-cli at commit a775de5, republished under its MIT licence (© krodak). 3,108 words, ~8,198 tokens.
Download SKILL.mdSave it as
.claude/skills/clickup/SKILL.md (or your agent's skills folder).- 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 withnpm install -g @krodak/clickup-cliand refresh this skill withcup skill(cup skill --path <file>installs to a custom location,cup skill --printwrites it to stdout).
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] | Tasks assigned to you (filter by status, name, type, list, space, assignee, tag, dates, custom fields). --all for all assignees |
cup assigned [--status s] [--include-closed] | All my tasks grouped by status |
cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed] | Tasks in active sprint (auto-detected) |
cup sprints [--space nameOrId] | List all sprints (marks active with *) |
cup search [query] [--status s] [--list id] [--space id] [--all] [--include-closed] [--assignee id|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val] | Search tasks by name, or list tasks filtered by flags when no query is given. --all for all assignees |
cup task <id> | Single task details (custom fields, checklists, attachments, deps, links) |
cup subtasks <id> [--status s] [--name q] [--include-closed] | Subtasks of a task |
cup comments <id> | Comments on a task |
cup activity <id> | Task details + comment history combined |
cup inbox [--days n] [--include-closed] | Tasks updated in last n days (default 30) |
cup summary [--hours n] | Standup: completed, in-progress, overdue |
cup overdue [--all] [--include-closed] | Tasks past due date (most overdue first) |
cup spaces [--name partial] [--my] [--archived] | List/filter workspace spaces |
cup lists <spaceId> [--name partial] [--archived] | Lists in a space (including folder lists) |
cup folders <spaceId> [--name partial] [--archived] | Folders in a space (with their lists); JSON includes parent_folder for subfolders |
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 attach-get <taskId> [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 <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 <id> [--space|--folder|--workspace] | List views on a list (default), space, folder, or workspace (cup views any --workspace) |
cup view <viewId> | Get view details |
cup view-tasks <viewId> [--me] | List tasks in a view (--me filters to you) |
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 |
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 <id> [-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 <id> -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 <commentId> -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 <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|--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 <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|--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 <name> -t <type> [-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 <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 (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) |
Show full SKILL.md (949 more words)Show less
Global Flags
| Flag | Description |
|---|---|
-p, --profile <n> | Use a specific profile for this command |
--json | Force JSON output (available on all commands) |
-pis always--profile, never--parent. Global short flags win over subcommand ones, socup create -p <taskId>fails withProfile "<taskId>" not found. Usecup 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, andcup assigneddefault to tasks assigned to the current user. Use--allto 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 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 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 updatedMake 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" --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:
# 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
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.
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-idis the initiativecustom_item_id(team convention;cup task-typeslists them).allrefuses to run non-interactively without--yes; always--dry-runfirst to see the estimate.- Whiteboards, dashboards, automations have no API: export those from the UI by hand.
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 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, 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.
© krodak, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in skills/clickup-cli of krodak/clickup-cli.
Open the folder on GitHubat commit a775de5
Compare with similar skills
ClickUp CLI next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| ClickUp CLI this skillkrodak/clickup-cli | 121 | — | ~8.2k | Automated safety check: Pass | MIT | |
| Linear Issue Workflowlobehub/lobehub | 83k | — | ~1.5k | Automated safety check: Pass | Custom licence | |
| Linearkv0906/pm-kit | 138 | — | ~1.9k | Automated safety check: Notes | MIT | |
| Fizzy CLIbasecamp/fizzy-cli | 244 | — | ~10k | Automated safety check: Pass | MIT | |
| Kanban Mdantopolskiy/kanban-md | 223 | — | ~4k | Automated safety check: Pass | MIT | |
| Gh Issuesserejaris/personal-corp-os | 229 | — | ~1.8k | Automated safety check: Pass | MIT |
Similar skills
Linear
kv0906/pm-kit
Interact with Linear for issue tracking — search, create, sync, and link issues to vault notes.
Fizzy CLI
basecamp/fizzy-cli
Operates Fizzy boards, cards, comments and other resources from the command line, with rules for card numbers, output filtering and checking setup.
Kanban Md
antopolskiy/kanban-md
Manage project tasks using kanban-md, a file-based kanban board CLI.
Gh Issues
serejaris/personal-corp-os
A skill your agent uses when creating, searching, updating, or managing GitHub issues via CLI.
Construction Business Agent
hewi333/Mom-n-Pop-Skills
Runs a construction company's back office by bridging Gmail, Drive and JobTread: routing email attachments to the PM system, checking project status and sending daily Telegram briefings.
More from krodak/clickup-cli
ClickUp CLI Testing
krodak/clickup-cli
Explains how to run and extend the clickup-cli tests: unit tests with a mocked client, e2e tests against a real ClickUp workspace, and the fixture data they rely on.
ClickUp CLI Release Process
krodak/clickup-cli
Walks through releasing a new version of clickup-cli: pre-release checks, version bump, tagging, CI watch, release notes and the Homebrew update.
Related
Categories
Questions about ClickUp CLI
What does ClickUp CLI do?
Lets your agent read and change ClickUp tasks, sprints, comments, Docs, Chat, views and webhooks through the cup command-line tool. This is a working reference for the cup CLI, a ClickUp client built for AI agents. It covers querying and updating tasks, sprint tracking, comments with threaded replies, subtasks, checklists, tags, custom fields, time tracking, attachments, goals and key results, plus ClickUp Docs, Chat channels, views, webhooks and the layout of spaces, folders and lists.
When should I use ClickUp CLI?
ClickUp CLI fits situations like: summarizing open and overdue tasks for a standup; updating task status, assignees or custom fields from the terminal; reading, creating or editing ClickUp Docs and doc pages; exporting or archiving workspace data before someone leaves the team.
How do I install ClickUp CLI in Claude Code?
Run `npx skills add krodak/clickup-cli --skill clickup -a claude-code`. Or copy the skill folder (skills/clickup-cli in krodak/clickup-cli) into .claude/skills/clickup in your project. Claude Code loads it when a task matches its description.
How do I install ClickUp CLI in Codex?
Run `npx skills add krodak/clickup-cli --skill clickup -a codex`. Or copy the skill folder (skills/clickup-cli in krodak/clickup-cli) into .agents/skills/clickup in your project. Codex loads it when a task matches its description.
Can I use ClickUp CLI in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add krodak/clickup-cli --skill clickup -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/clickup, .gemini/skills/clickup, .github/skills/clickup and .opencode/skills/clickup in your project.
What does ClickUp CLI need to run?
Going by SKILL.md and its folder, ClickUp CLI needs the command-line tools its instructions call (npm and brew) and credentials named CU_API_TOKEN. Our summary lists: Node.js 22 or newer; The cup CLI from the @krodak/clickup-cli npm package; A ClickUp personal API token and workspace ID.
Does ClickUp CLI access the network?
SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is ClickUp CLI safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does ClickUp CLI use?
ClickUp CLI is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does ClickUp CLI use?
About 8.2k tokens (SKILL.md is roughly 33k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to ClickUp CLI?
Skills that share tags, products or a category with ClickUp CLI: Linear Issue Workflow (lobehub/lobehub, 83k stars), Linear (kv0906/pm-kit, 138 stars), Fizzy CLI (basecamp/fizzy-cli, 244 stars) and Kanban Md (antopolskiy/kanban-md, 223 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains ClickUp CLI?
krodak (a GitHub user) maintains it in krodak/clickup-cli, which has 121 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 6, 2026.
Source: krodak/clickup-cli on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.