@krodak/clickup-cli 0.20.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +2 -2
- package/README.md +120 -106
- package/dist/index.js +241 -119
- package/package.json +1 -3
- package/skills/clickup-cli/SKILL.md +151 -154
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@krodak/clickup-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "ClickUp CLI for AI agents and humans",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -20,7 +20,6 @@
|
|
|
20
20
|
"initiative"
|
|
21
21
|
],
|
|
22
22
|
"bin": {
|
|
23
|
-
"cu": "./dist/index.js",
|
|
24
23
|
"cup": "./dist/index.js"
|
|
25
24
|
},
|
|
26
25
|
"files": [
|
|
@@ -53,7 +52,6 @@
|
|
|
53
52
|
},
|
|
54
53
|
"devDependencies": {
|
|
55
54
|
"@eslint/js": "^10.0.1",
|
|
56
|
-
"@inquirer/testing": "^3.3.0",
|
|
57
55
|
"@types/node": "^25.3.0",
|
|
58
56
|
"dotenv": "^17.3.1",
|
|
59
57
|
"eslint": "^10.0.2",
|
|
@@ -1,21 +1,17 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: clickup
|
|
3
|
-
description: 'Use when managing ClickUp tasks, sprints, or comments via the `
|
|
3
|
+
description: 'Use when managing ClickUp tasks, sprints, or comments via the `cup` CLI tool. Triggers: task queries, status updates, sprint tracking, creating subtasks, posting comments, threaded replies, standup summaries, searching tasks, checking overdue items, assigning tasks, listing spaces and lists, 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.'
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# ClickUp CLI (`
|
|
6
|
+
# ClickUp CLI (`cup`)
|
|
7
7
|
|
|
8
|
-
Reference for AI agents using the `
|
|
8
|
+
Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, and project workflows.
|
|
9
9
|
|
|
10
10
|
Keywords: ClickUp, task management, sprint, project management, agile, backlog, subtasks, standup, overdue, search
|
|
11
11
|
|
|
12
|
-
## Binary Names
|
|
13
|
-
|
|
14
|
-
Both `cu` and `cup` are available as binary names. They are identical. Use `cup` if `cu` conflicts with the Unix `cu(1)` utility on your system. All examples below use `cu`, but `cup` works the same way.
|
|
15
|
-
|
|
16
12
|
## Setup
|
|
17
13
|
|
|
18
|
-
Config at `~/.config/
|
|
14
|
+
Config at `~/.config/cup/config.json` with `apiToken` and `teamId`. Optional: `sprintFolderId` to pin sprint detection to a specific folder. Run `cup init` to set up interactively.
|
|
19
15
|
|
|
20
16
|
Environment variables `CU_API_TOKEN` and `CU_TEAM_ID` override config file when both are set.
|
|
21
17
|
|
|
@@ -27,7 +23,7 @@ Environment variables `CU_API_TOKEN` and `CU_TEAM_ID` override config file when
|
|
|
27
23
|
| Piped / non-TTY | Markdown tables | `--json` for JSON |
|
|
28
24
|
|
|
29
25
|
- Default piped output is **Markdown** - optimized for agent context windows
|
|
30
|
-
- `
|
|
26
|
+
- `cup task <id>` outputs a Markdown summary when piped; use `--json` for the full raw API object (custom fields, checklists, etc.)
|
|
31
27
|
- Set `CU_OUTPUT=json` to always get JSON when piped
|
|
32
28
|
- Set `NO_COLOR` to disable color (tables still render, just uncolored)
|
|
33
29
|
- Agents typically don't need `--json` unless parsing structured data with `jq`
|
|
@@ -38,184 +34,185 @@ All commands support `--help` for full flag details.
|
|
|
38
34
|
|
|
39
35
|
### Read
|
|
40
36
|
|
|
41
|
-
| Command
|
|
42
|
-
|
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
37
|
+
| Command | What it returns |
|
|
38
|
+
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
|
|
39
|
+
| `cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--include-closed] [--json]` | My tasks (all types, or filter with --type) |
|
|
40
|
+
| `cup assigned [--status s] [--include-closed] [--json]` | All my tasks grouped by status |
|
|
41
|
+
| `cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed] [--json]` | Tasks in active sprint (auto-detected) |
|
|
42
|
+
| `cup sprints [--space nameOrId] [--json]` | List all sprints (marks active with \*) |
|
|
43
|
+
| `cup search <query> [--status s] [--include-closed] [--json]` | Search my tasks by name (multi-word, fuzzy status) |
|
|
44
|
+
| `cup task <id> [--json]` | Single task details |
|
|
45
|
+
| `cup subtasks <id> [--status s] [--name q] [--include-closed] [--json]` | Subtasks of a task |
|
|
46
|
+
| `cup comments <id> [--json]` | Comments on a task |
|
|
47
|
+
| `cup activity <id> [--json]` | Task details + comment history combined |
|
|
48
|
+
| `cup inbox [--days n] [--include-closed] [--json]` | Tasks updated in last n days (default 30) |
|
|
49
|
+
| `cup summary [--hours n] [--json]` | Standup helper: completed, in-progress, overdue |
|
|
50
|
+
| `cup overdue [--include-closed] [--json]` | Tasks past their due date |
|
|
51
|
+
| `cup spaces [--name partial] [--my] [--json]` | List/filter workspace spaces |
|
|
52
|
+
| `cup lists <spaceId> [--name partial] [--json]` | Lists in a space (including folder lists) |
|
|
53
|
+
| `cup open <query> [--json]` | Open task in browser by ID or name |
|
|
54
|
+
| `cup auth [--json]` | Check authentication status |
|
|
59
55
|
|
|
60
56
|
### Write
|
|
61
57
|
|
|
62
|
-
| Command
|
|
63
|
-
|
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
58
|
+
| Command | What it does |
|
|
59
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
60
|
+
| `cup update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id\|me] [--parent id] [--json]` | Update task fields (desc supports markdown) |
|
|
61
|
+
| `cup create -n name [-l listId] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id\|me] [--tags t] [--custom-item-id n] [--json]` | Create task (desc supports markdown) |
|
|
62
|
+
| `cup comment <id> -m text [--notify-all] [--json]` | Post comment on task |
|
|
63
|
+
| `cup comment-edit <commentId> -m text [--resolved] [--unresolved] [--json]` | Edit an existing comment |
|
|
64
|
+
| `cup assign <id> [--to userId\|me] [--remove userId\|me] [--json]` | Assign/unassign users |
|
|
65
|
+
| `cup depend <id> [--on taskId] [--blocks taskId] [--remove] [--json]` | Add/remove task dependencies |
|
|
66
|
+
| `cup move <id> [--to listId] [--remove listId] [--json]` | Add/remove task from lists |
|
|
67
|
+
| `cup field <id> [--set "Name" value] [--remove "Name"] [--json]` | Set/remove custom field values |
|
|
68
|
+
| `cup delete <id> [--confirm] [--json]` | Delete a task (DESTRUCTIVE, irreversible) |
|
|
69
|
+
| `cup tag <id> [--add tags] [--remove tags] [--json]` | Add/remove tags on a task |
|
|
70
|
+
| `cup checklist view <id> [--json]` | View checklists on a task |
|
|
71
|
+
| `cup checklist create <id> <name> [--json]` | Create a checklist |
|
|
72
|
+
| `cup checklist delete <checklistId> [--json]` | Delete a checklist |
|
|
73
|
+
| `cup checklist add-item <checklistId> <name> [--json]` | Add item to a checklist |
|
|
74
|
+
| `cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--json]` | Edit a checklist item |
|
|
75
|
+
| `cup checklist delete-item <checklistId> <itemId> [--json]` | Delete a checklist item |
|
|
76
|
+
| `cup comment-delete <commentId> [--json]` | Delete a comment |
|
|
77
|
+
| `cup replies <commentId> [--json]` | List threaded replies on a comment |
|
|
78
|
+
| `cup reply <commentId> -m text [--notify-all] [--json]` | Reply to a comment |
|
|
79
|
+
| `cup link <taskId> <linksTo> [--remove] [--json]` | Add or remove link between tasks |
|
|
80
|
+
| `cup attach <taskId> <filePath> [--json]` | Upload file attachment to a task |
|
|
81
|
+
| `cup time start <taskId> [-d desc] [--json]` | Start tracking time on a task |
|
|
82
|
+
| `cup time stop [--json]` | Stop the running timer |
|
|
83
|
+
| `cup time status [--json]` | Show currently running timer |
|
|
84
|
+
| `cup time log <taskId> <duration> [-d desc] [--json]` | Log manual time entry (e.g. "2h", "30m") |
|
|
85
|
+
| `cup time list [--days n] [--task id] [--json]` | List recent time entries |
|
|
86
|
+
| `cup config get <key>` / `cup config set <key> <value>` / `cup config path` | Manage CLI config (keys: apiToken, teamId, sprintFolderId) |
|
|
87
|
+
| `cup completion <shell>` | Shell completions (bash/zsh/fish) |
|
|
92
88
|
|
|
93
89
|
## Quick Reference
|
|
94
90
|
|
|
95
|
-
| Topic
|
|
96
|
-
|
|
|
97
|
-
| Task IDs
|
|
98
|
-
| `--type`
|
|
99
|
-
| `--list` on create
|
|
100
|
-
| `--status`
|
|
101
|
-
| `--priority`
|
|
102
|
-
| `--due-date`
|
|
103
|
-
| `--assignee`
|
|
104
|
-
| `--tags`
|
|
105
|
-
| `--time-estimate`
|
|
106
|
-
| `--custom-item-id`
|
|
107
|
-
| `--on` / `--blocks`
|
|
108
|
-
| `--to` / `--remove`
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `--space`
|
|
114
|
-
| `--name`
|
|
115
|
-
| `--include-closed`
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| Custom task IDs
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| Errors
|
|
134
|
-
| Parsing
|
|
91
|
+
| Topic | Detail |
|
|
92
|
+
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| Task IDs | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format |
|
|
94
|
+
| `--type` | Filter by task type: `task` (regular), or custom type name/ID (e.g. `initiative`, `Bug`) |
|
|
95
|
+
| `--list` on create | Optional when `--parent` is given (auto-detected) |
|
|
96
|
+
| `--status` | Fuzzy matching: exact > starts-with > contains. Prints match to stderr. |
|
|
97
|
+
| `--priority` | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4) |
|
|
98
|
+
| `--due-date` | `YYYY-MM-DD` format |
|
|
99
|
+
| `--assignee` | User ID or `me` (on `cup create`, `cup update`, `cup assign`) |
|
|
100
|
+
| `--tags` | Comma-separated (e.g. `--tags "bug,frontend"`) |
|
|
101
|
+
| `--time-estimate` | Duration format: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds |
|
|
102
|
+
| `--custom-item-id` | Custom task type ID for `cup create` (e.g. `1` for initiative) |
|
|
103
|
+
| `--on` / `--blocks` | Task dependency direction (used with `cup depend`) |
|
|
104
|
+
| `--to` / `--remove` | List ID to add/remove task (used with `cup move`) |
|
|
105
|
+
| `cup field --set` | Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email |
|
|
106
|
+
| `cup field` | Field names resolved case-insensitively; errors list available fields/options |
|
|
107
|
+
| `cup delete` | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone |
|
|
108
|
+
| `cup tag --add/--remove` | Comma-separated tag names (e.g. `--add "bug,frontend"`) |
|
|
109
|
+
| `--space` | Partial name match or exact ID |
|
|
110
|
+
| `--name` | Partial match, case-insensitive |
|
|
111
|
+
| `--include-closed` | Include closed/done tasks (on `tasks`, `assigned`, `subtasks`, `sprint`, `search`, `inbox`, `overdue`) |
|
|
112
|
+
| `cup assign --to me` | Shorthand for your own user ID |
|
|
113
|
+
| `cup search` | Matches all query words against task name, case-insensitive |
|
|
114
|
+
| `cup sprint` | Auto-detects active sprint by searching for folders named sprint/iteration/cycle/scrum, parses multiple date formats (US, ISO, month-day, European), prompts in TTY when ambiguous. Override with `--folder <id>` or `cup config set sprintFolderId <id>` |
|
|
115
|
+
| `cup summary` | Categories: completed (done/complete/closed within N hours), in progress, overdue |
|
|
116
|
+
| `cup overdue` | Excludes closed tasks, sorted most overdue first |
|
|
117
|
+
| `cup open` | Tries task ID first, falls back to name search |
|
|
118
|
+
| `cup checklist` | Full CRUD for task checklists: view, create, delete, add-item, edit-item, delete-item |
|
|
119
|
+
| `cup time` | Track time: start/stop timer, log entries, list history. Duration format: "2h", "30m", "1h30m" |
|
|
120
|
+
| `cup comment-edit` | Edit comment text and resolution status |
|
|
121
|
+
| `cup comment-delete` | Delete a comment |
|
|
122
|
+
| `cup replies` / `cup reply` | View and post threaded comment replies |
|
|
123
|
+
| Custom task IDs | Auto-detected by format (`PROJ-123`). Uses `teamId` from config. All commands support them |
|
|
124
|
+
| `cup link` + custom IDs | Both IDs must be the same type (both custom or both native). Mixing may not work |
|
|
125
|
+
| `cup link` | Link/unlink tasks (different from dependencies) |
|
|
126
|
+
| `cup attach` | Upload files to tasks. Attachments shown in `cup task` detail view |
|
|
127
|
+
| `cup task` | Shows custom fields, checklists, attachments, dependencies, and linked tasks in detail view |
|
|
128
|
+
| `cup lists` | Discovers list IDs needed for `--list` and `cup create -l` |
|
|
129
|
+
| Errors | stderr with exit code 1 |
|
|
130
|
+
| Parsing | Strict - excess/unknown arguments rejected |
|
|
135
131
|
|
|
136
132
|
## Agent Workflow Examples
|
|
137
133
|
|
|
138
134
|
### Investigate a task
|
|
139
135
|
|
|
140
136
|
```bash
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
137
|
+
cup task abc123def # markdown summary
|
|
138
|
+
cup subtasks abc123def # child tasks (open only)
|
|
139
|
+
cup subtasks abc123def --include-closed # all child tasks
|
|
140
|
+
cup comments abc123def # discussion
|
|
141
|
+
cup activity abc123def # task + comments combined
|
|
146
142
|
```
|
|
147
143
|
|
|
148
144
|
### Find tasks
|
|
149
145
|
|
|
150
146
|
```bash
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
147
|
+
cup tasks --status "in progress" # by status
|
|
148
|
+
cup tasks --name "login" # by partial name
|
|
149
|
+
cup tasks --type initiative # initiatives only
|
|
150
|
+
cup tasks --type task # regular tasks only
|
|
151
|
+
cup search "payment flow" # multi-word search
|
|
152
|
+
cup search auth --status "prog" # fuzzy status match
|
|
153
|
+
cup sprint # current sprint
|
|
154
|
+
cup assigned # all my tasks by status
|
|
155
|
+
cup overdue # past due date
|
|
156
|
+
cup inbox --days 7 # recently updated
|
|
161
157
|
```
|
|
162
158
|
|
|
163
159
|
### Make changes
|
|
164
160
|
|
|
165
161
|
```bash
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
162
|
+
cup update abc123def -s "done"
|
|
163
|
+
cup update abc123def --priority high --due-date 2025-03-15
|
|
164
|
+
cup update abc123def --time-estimate 2h
|
|
165
|
+
cup update abc123def --parent parentId # make it a subtask
|
|
166
|
+
cup create -n "Fix the thing" -p abc123def
|
|
167
|
+
cup create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
|
|
168
|
+
cup create -n "Q3 Roadmap" -l <listId> --custom-item-id 1 # create initiative
|
|
169
|
+
cup comment abc123def -m "Completed in PR #42"
|
|
170
|
+
cup assign abc123def --to me
|
|
171
|
+
cup depend task3 --on task2 # task3 waits for task2
|
|
172
|
+
cup depend task1 --blocks task2 # task1 blocks task2
|
|
173
|
+
cup move task1 --to list2 --remove list1 # move between lists
|
|
174
|
+
cup field abc123def --set "Story Points" 5
|
|
175
|
+
cup field abc123def --set "Category" "Bug Fix"
|
|
176
|
+
cup field abc123def --remove "Old Field"
|
|
177
|
+
cup tag abc123def --add "bug,frontend"
|
|
178
|
+
cup tag abc123def --remove "triage"
|
|
179
|
+
cup checklist view abc123def # view checklists
|
|
180
|
+
cup checklist create abc123def "QA Steps" # add checklist
|
|
181
|
+
cup checklist add-item <clId> "Run unit tests" # add item
|
|
182
|
+
cup checklist edit-item <clId> <itemId> --resolved # check off item
|
|
183
|
+
cup comment-edit <commentId> -m "Updated findings" # edit a comment
|
|
184
|
+
cup comment-delete <commentId> # delete a comment
|
|
185
|
+
cup replies <commentId> # view threaded replies
|
|
186
|
+
cup reply <commentId> -m "Agreed, fixing" # reply to a comment
|
|
187
|
+
cup link abc123 def456 # link two tasks
|
|
188
|
+
cup link abc123 def456 --remove # unlink two tasks
|
|
189
|
+
cup attach abc123def ./screenshot.png # upload file to task
|
|
190
|
+
cup time start abc123def -d "Working on feature" # start timer
|
|
191
|
+
cup time status # check running timer
|
|
192
|
+
cup time stop # stop timer
|
|
193
|
+
cup time log abc123def 2h -d "Code review" # log manual entry
|
|
194
|
+
cup time list --days 7 # recent entries
|
|
195
|
+
cup delete abc123def --confirm # irreversible!
|
|
200
196
|
```
|
|
201
197
|
|
|
202
198
|
### Discover workspace structure
|
|
203
199
|
|
|
204
200
|
```bash
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
201
|
+
cup spaces # all spaces
|
|
202
|
+
cup spaces --name "Engineering" # find space ID by name
|
|
203
|
+
cup lists <spaceId> # lists in a space (needs ID from cup spaces)
|
|
204
|
+
cup sprints # all sprints across folders
|
|
205
|
+
cup auth # verify token works
|
|
206
|
+
cup config set sprintFolderId <id> # pin sprint detection to a folder
|
|
210
207
|
```
|
|
211
208
|
|
|
212
209
|
### Standup
|
|
213
210
|
|
|
214
211
|
```bash
|
|
215
|
-
|
|
216
|
-
|
|
212
|
+
cup summary # completed / in progress / overdue
|
|
213
|
+
cup summary --hours 48 # wider window
|
|
217
214
|
```
|
|
218
215
|
|
|
219
216
|
## DELETE SAFETY
|
|
220
217
|
|
|
221
|
-
IMPORTANT: Always confirm with the user before running `
|
|
218
|
+
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.
|