@krodak/clickup-cli 0.19.0 → 0.21.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 +117 -104
- package/dist/index.js +74 -32
- package/package.json +1 -2
- package/skills/clickup-cli/SKILL.md +150 -154
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "clickup-cli",
|
|
3
|
-
"description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the
|
|
4
|
-
"version": "0.
|
|
3
|
+
"description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cup command",
|
|
4
|
+
"version": "0.21.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Krzysztof Rodak"
|
|
7
7
|
},
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# cup - ClickUp CLI
|
|
2
2
|
|
|
3
3
|
> A ClickUp CLI built for AI agents that also works well for humans. Outputs Markdown when piped (optimized for AI context windows), interactive tables when run in a terminal.
|
|
4
4
|
|
|
@@ -8,10 +8,10 @@
|
|
|
8
8
|
[](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml)
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
|
-
npm install -g @krodak/clickup-cli &&
|
|
11
|
+
npm install -g @krodak/clickup-cli && cup init
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
`cup` is the binary name. The previous `cu` name was retired in v0.21.0 to avoid conflict with the Unix [cu(1)](<https://en.wikipedia.org/wiki/Cu_(Unix_utility)>) utility.
|
|
15
15
|
|
|
16
16
|
## Talk to your agent
|
|
17
17
|
|
|
@@ -27,7 +27,7 @@ Install the CLI, add the skill file to your agent, and it works with ClickUp. No
|
|
|
27
27
|
|
|
28
28
|
> **"Update the description with your findings and flag blockers in a comment."**
|
|
29
29
|
|
|
30
|
-
The agent reads the skill file, picks the right `
|
|
30
|
+
The agent reads the skill file, picks the right `cup` commands, and handles everything. You don't need to learn the CLI - the agent does.
|
|
31
31
|
|
|
32
32
|
## Install
|
|
33
33
|
|
|
@@ -38,7 +38,7 @@ You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Setti
|
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
40
|
npm install -g @krodak/clickup-cli
|
|
41
|
-
|
|
41
|
+
cup init
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
</details>
|
|
@@ -49,7 +49,7 @@ cu init
|
|
|
49
49
|
```bash
|
|
50
50
|
brew tap krodak/tap
|
|
51
51
|
brew install clickup-cli
|
|
52
|
-
|
|
52
|
+
cup init
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
</details>
|
|
@@ -130,148 +130,161 @@ Status: :white_check_mark: implemented | :construction: planned | :no_entry_sign
|
|
|
130
130
|
|
|
131
131
|
### Tasks
|
|
132
132
|
|
|
133
|
-
| Feature | Command
|
|
134
|
-
| -------------------- |
|
|
135
|
-
| List my tasks | `
|
|
136
|
-
| Get task details | `
|
|
137
|
-
| Create task | `
|
|
138
|
-
| Update task | `
|
|
139
|
-
| Delete task | `
|
|
140
|
-
| Search tasks | `
|
|
141
|
-
| Open in browser | `
|
|
142
|
-
| List subtasks | `
|
|
143
|
-
| Assign / unassign | `
|
|
144
|
-
| Duplicate task | `
|
|
145
|
-
| Create from template | `
|
|
146
|
-
| Bulk operations | `
|
|
133
|
+
| Feature | Command | Status |
|
|
134
|
+
| -------------------- | ----------------------- | ------------------ |
|
|
135
|
+
| List my tasks | `cup tasks` | :white_check_mark: |
|
|
136
|
+
| Get task details | `cup task <id>` | :white_check_mark: |
|
|
137
|
+
| Create task | `cup create` | :white_check_mark: |
|
|
138
|
+
| Update task | `cup update <id>` | :white_check_mark: |
|
|
139
|
+
| Delete task | `cup delete <id>` | :white_check_mark: |
|
|
140
|
+
| Search tasks | `cup search <query>` | :white_check_mark: |
|
|
141
|
+
| Open in browser | `cup open <query>` | :white_check_mark: |
|
|
142
|
+
| List subtasks | `cup subtasks <id>` | :white_check_mark: |
|
|
143
|
+
| Assign / unassign | `cup assign <id>` | :white_check_mark: |
|
|
144
|
+
| Duplicate task | `cup duplicate <id>` | :construction: |
|
|
145
|
+
| Create from template | `cup create --template` | :construction: |
|
|
146
|
+
| Bulk operations | `cup bulk` | :construction: |
|
|
147
147
|
|
|
148
148
|
### Dependencies & Relations
|
|
149
149
|
|
|
150
|
-
| Feature | Command
|
|
151
|
-
| -------------------- |
|
|
152
|
-
| Add dependency | `
|
|
153
|
-
| Remove dependency | `
|
|
154
|
-
| Add/remove task link | `
|
|
150
|
+
| Feature | Command | Status |
|
|
151
|
+
| -------------------- | -------------------------- | ------------------ |
|
|
152
|
+
| Add dependency | `cup depend <id>` | :white_check_mark: |
|
|
153
|
+
| Remove dependency | `cup depend <id> --remove` | :white_check_mark: |
|
|
154
|
+
| Add/remove task link | `cup link <id> <linksTo>` | :white_check_mark: |
|
|
155
155
|
|
|
156
156
|
### Multi-list
|
|
157
157
|
|
|
158
|
-
| Feature | Command
|
|
159
|
-
| ---------------- |
|
|
160
|
-
| Add task to list | `
|
|
161
|
-
| Remove from list | `
|
|
158
|
+
| Feature | Command | Status |
|
|
159
|
+
| ---------------- | ------------------------ | ------------------ |
|
|
160
|
+
| Add task to list | `cup move <id> --add` | :white_check_mark: |
|
|
161
|
+
| Remove from list | `cup move <id> --remove` | :white_check_mark: |
|
|
162
162
|
|
|
163
163
|
### Sprints & Planning
|
|
164
164
|
|
|
165
|
-
| Feature | Command
|
|
166
|
-
| ------------------------ |
|
|
167
|
-
| Active sprint tasks | `
|
|
168
|
-
| List all sprints | `
|
|
169
|
-
| Assigned tasks by status | `
|
|
170
|
-
| Standup summary | `
|
|
171
|
-
| Overdue tasks | `
|
|
172
|
-
| Recently updated | `
|
|
165
|
+
| Feature | Command | Status |
|
|
166
|
+
| ------------------------ | -------------- | ------------------ |
|
|
167
|
+
| Active sprint tasks | `cup sprint` | :white_check_mark: |
|
|
168
|
+
| List all sprints | `cup sprints` | :white_check_mark: |
|
|
169
|
+
| Assigned tasks by status | `cup assigned` | :white_check_mark: |
|
|
170
|
+
| Standup summary | `cup summary` | :white_check_mark: |
|
|
171
|
+
| Overdue tasks | `cup overdue` | :white_check_mark: |
|
|
172
|
+
| Recently updated | `cup inbox` | :white_check_mark: |
|
|
173
173
|
|
|
174
174
|
### Comments
|
|
175
175
|
|
|
176
|
-
| Feature | Command
|
|
177
|
-
| ------------------------ |
|
|
178
|
-
| List comments | `
|
|
179
|
-
| Post comment | `
|
|
180
|
-
| Edit comment | `
|
|
181
|
-
| Task + comments combined | `
|
|
182
|
-
| Delete comment | `
|
|
183
|
-
| Threaded replies | `
|
|
176
|
+
| Feature | Command | Status |
|
|
177
|
+
| ------------------------ | ------------------------------------- | ------------------ |
|
|
178
|
+
| List comments | `cup comments <id>` | :white_check_mark: |
|
|
179
|
+
| Post comment | `cup comment <id>` | :white_check_mark: |
|
|
180
|
+
| Edit comment | `cup comment-edit <id>` | :white_check_mark: |
|
|
181
|
+
| Task + comments combined | `cup activity <id>` | :white_check_mark: |
|
|
182
|
+
| Delete comment | `cup comment-delete <id>` | :white_check_mark: |
|
|
183
|
+
| Threaded replies | `cup replies <id>` / `cup reply <id>` | :white_check_mark: |
|
|
184
184
|
|
|
185
185
|
### Checklists
|
|
186
186
|
|
|
187
|
-
| Feature | Command
|
|
188
|
-
| ---------------- |
|
|
189
|
-
| View checklists | `
|
|
190
|
-
| Create checklist | `
|
|
191
|
-
| Delete checklist | `
|
|
192
|
-
| Add item | `
|
|
193
|
-
| Edit item | `
|
|
194
|
-
| Delete item | `
|
|
187
|
+
| Feature | Command | Status |
|
|
188
|
+
| ---------------- | ----------------------------------------- | ------------------ |
|
|
189
|
+
| View checklists | `cup checklist view <id>` | :white_check_mark: |
|
|
190
|
+
| Create checklist | `cup checklist create <id> <name>` | :white_check_mark: |
|
|
191
|
+
| Delete checklist | `cup checklist delete <id>` | :white_check_mark: |
|
|
192
|
+
| Add item | `cup checklist add-item <id> <name>` | :white_check_mark: |
|
|
193
|
+
| Edit item | `cup checklist edit-item <id> <itemId>` | :white_check_mark: |
|
|
194
|
+
| Delete item | `cup checklist delete-item <id> <itemId>` | :white_check_mark: |
|
|
195
195
|
|
|
196
196
|
### Custom Fields
|
|
197
197
|
|
|
198
|
-
| Feature | Command
|
|
199
|
-
| --------------------- |
|
|
200
|
-
| Set field value | `
|
|
201
|
-
| Remove field value | `
|
|
202
|
-
| List available fields | `
|
|
198
|
+
| Feature | Command | Status |
|
|
199
|
+
| --------------------- | ------------------------- | ------------------ |
|
|
200
|
+
| Set field value | `cup field <id> --set` | :white_check_mark: |
|
|
201
|
+
| Remove field value | `cup field <id> --remove` | :white_check_mark: |
|
|
202
|
+
| List available fields | `cup fields <listId>` | :construction: |
|
|
203
203
|
|
|
204
204
|
### Tags
|
|
205
205
|
|
|
206
|
-
| Feature | Command
|
|
207
|
-
| ----------------------- |
|
|
208
|
-
| Add/remove tag on task | `
|
|
209
|
-
| List space tags | `
|
|
210
|
-
| Create/delete space tag |
|
|
206
|
+
| Feature | Command | Status |
|
|
207
|
+
| ----------------------- | -------------------- | ------------------ |
|
|
208
|
+
| Add/remove tag on task | `cup tag <id>` | :white_check_mark: |
|
|
209
|
+
| List space tags | `cup tags <spaceId>` | :construction: |
|
|
210
|
+
| Create/delete space tag | | :construction: |
|
|
211
211
|
|
|
212
212
|
### Time Tracking
|
|
213
213
|
|
|
214
|
-
| Feature | Command
|
|
215
|
-
| -------------- |
|
|
216
|
-
| Start timer | `
|
|
217
|
-
| Stop timer | `
|
|
218
|
-
| Timer status | `
|
|
219
|
-
| Log time entry | `
|
|
220
|
-
| List entries | `
|
|
221
|
-
| Update entry | `
|
|
222
|
-
| Delete entry | `
|
|
214
|
+
| Feature | Command | Status |
|
|
215
|
+
| -------------- | ------------------------------ | ------------------ |
|
|
216
|
+
| Start timer | `cup time start <id>` | :white_check_mark: |
|
|
217
|
+
| Stop timer | `cup time stop` | :white_check_mark: |
|
|
218
|
+
| Timer status | `cup time status` | :white_check_mark: |
|
|
219
|
+
| Log time entry | `cup time log <id> <duration>` | :white_check_mark: |
|
|
220
|
+
| List entries | `cup time list` | :white_check_mark: |
|
|
221
|
+
| Update entry | `cup time update <id>` | :construction: |
|
|
222
|
+
| Delete entry | `cup time delete <id>` | :construction: |
|
|
223
223
|
|
|
224
224
|
### Workspace
|
|
225
225
|
|
|
226
|
-
| Feature | Command
|
|
227
|
-
| ------------ |
|
|
228
|
-
| List spaces | `
|
|
229
|
-
| List lists | `
|
|
230
|
-
| Check auth | `
|
|
231
|
-
| List folders | `
|
|
232
|
-
| List members | `
|
|
226
|
+
| Feature | Command | Status |
|
|
227
|
+
| ------------ | ----------------------- | ------------------ |
|
|
228
|
+
| List spaces | `cup spaces` | :white_check_mark: |
|
|
229
|
+
| List lists | `cup lists <spaceId>` | :white_check_mark: |
|
|
230
|
+
| Check auth | `cup auth` | :white_check_mark: |
|
|
231
|
+
| List folders | `cup folders <spaceId>` | :construction: |
|
|
232
|
+
| List members | `cup members` | :construction: |
|
|
233
233
|
|
|
234
234
|
### Goals & Key Results
|
|
235
235
|
|
|
236
|
-
| Feature | Command
|
|
237
|
-
| ------------------ |
|
|
238
|
-
| List goals | `
|
|
239
|
-
| Create/update goal |
|
|
240
|
-
| Key results CRUD |
|
|
236
|
+
| Feature | Command | Status |
|
|
237
|
+
| ------------------ | ----------- | -------------- |
|
|
238
|
+
| List goals | `cup goals` | :construction: |
|
|
239
|
+
| Create/update goal | | :construction: |
|
|
240
|
+
| Key results CRUD | | :construction: |
|
|
241
241
|
|
|
242
242
|
### Docs
|
|
243
243
|
|
|
244
|
-
| Feature | Command
|
|
245
|
-
| ----------------- |
|
|
246
|
-
| Search docs | `
|
|
247
|
-
| View page content | `
|
|
244
|
+
| Feature | Command | Status |
|
|
245
|
+
| ----------------- | ------------------ | -------------- |
|
|
246
|
+
| Search docs | `cup docs <query>` | :construction: |
|
|
247
|
+
| View page content | `cup doc <id>` | :construction: |
|
|
248
248
|
|
|
249
249
|
### Attachments
|
|
250
250
|
|
|
251
|
-
| Feature | Command
|
|
252
|
-
| ---------------- |
|
|
253
|
-
| Upload file | `
|
|
254
|
-
| List attachments | shown inline in `
|
|
251
|
+
| Feature | Command | Status |
|
|
252
|
+
| ---------------- | -------------------------- | ------------------ |
|
|
253
|
+
| Upload file | `cup attach <id> <file>` | :white_check_mark: |
|
|
254
|
+
| List attachments | shown inline in `cup task` | :white_check_mark: |
|
|
255
255
|
|
|
256
256
|
### :no_entry_sign: Won't add
|
|
257
257
|
|
|
258
258
|
| Feature | Why |
|
|
259
259
|
| --------------------- | --------------------------------------------------------------------------- |
|
|
260
260
|
| Webhooks | Server-side. A CLI can't listen for events. |
|
|
261
|
-
| OAuth flow | `
|
|
261
|
+
| OAuth flow | `cup init` already handles auth with API tokens. |
|
|
262
262
|
| Guest/ACL | Enterprise admin. Not what you reach for in a terminal. |
|
|
263
263
|
| Chat/DM | Use the ClickUp app. Chat doesn't belong in a CLI. |
|
|
264
264
|
| Audit logs | Enterprise admin. |
|
|
265
265
|
| User/group management | Too destructive for a CLI - removing someone from a workspace is permanent. |
|
|
266
266
|
| View CRUD | Views are visual layouts. Configure them in the UI. |
|
|
267
267
|
|
|
268
|
+
### API Limitations
|
|
269
|
+
|
|
270
|
+
These features exist in the ClickUp UI but aren't possible through the API:
|
|
271
|
+
|
|
272
|
+
| Feature | Limitation |
|
|
273
|
+
| ------------------------- | ---------------------------------------------------------------------------------- |
|
|
274
|
+
| Comment attachments | API only supports task-level attachments (`cup attach`), not files within comments |
|
|
275
|
+
| @mention individual users | API provides `--notify-all` but no way to target specific users via @syntax |
|
|
276
|
+
| Comment reactions | No API endpoint for adding or viewing reactions |
|
|
277
|
+
| ClickUp Brain / AI | No public API |
|
|
278
|
+
| In-comment checklists | Only task-level checklists are supported via API |
|
|
279
|
+
| Voice notes / Video | Recording is a UI-only feature |
|
|
280
|
+
|
|
268
281
|
### Setup
|
|
269
282
|
|
|
270
|
-
| Feature | Command
|
|
271
|
-
| ----------------- |
|
|
272
|
-
| First-time setup | `
|
|
273
|
-
| Get/set config | `
|
|
274
|
-
| Shell completions | `
|
|
283
|
+
| Feature | Command | Status |
|
|
284
|
+
| ----------------- | ------------------------ | ------------------ |
|
|
285
|
+
| First-time setup | `cup init` | :white_check_mark: |
|
|
286
|
+
| Get/set config | `cup config` | :white_check_mark: |
|
|
287
|
+
| Shell completions | `cup completion <shell>` | :white_check_mark: |
|
|
275
288
|
|
|
276
289
|
## Output Modes
|
|
277
290
|
|
|
@@ -314,15 +327,15 @@ ClickUp workspaces can configure custom task IDs with a prefix per space (e.g.,
|
|
|
314
327
|
All commands that accept task IDs work with both native IDs and custom IDs:
|
|
315
328
|
|
|
316
329
|
```bash
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
330
|
+
cup task PROJ-123
|
|
331
|
+
cup update DEV-42 --status done
|
|
332
|
+
cup comment PROJ-456 -m "Fixed in latest commit"
|
|
333
|
+
cup subtasks DEV-100
|
|
321
334
|
```
|
|
322
335
|
|
|
323
|
-
Custom ID resolution uses the `teamId` from your config, which is required (`
|
|
336
|
+
Custom ID resolution uses the `teamId` from your config, which is required (`cup init` sets it up).
|
|
324
337
|
|
|
325
|
-
**Task links with custom IDs:** The `
|
|
338
|
+
**Task links with custom IDs:** The `cup link` command passes both task IDs in a single API request. When both IDs are custom, this works correctly. However, mixing custom and native IDs in a single link command may not work as expected because the ClickUp API applies the `custom_task_ids` flag to all IDs in the request.
|
|
326
339
|
|
|
327
340
|
## Why a CLI and not MCP?
|
|
328
341
|
|
package/dist/index.js
CHANGED
|
@@ -106,10 +106,12 @@ var ClickUpClient = class {
|
|
|
106
106
|
body: JSON.stringify(options)
|
|
107
107
|
});
|
|
108
108
|
}
|
|
109
|
-
async postComment(taskId, commentText) {
|
|
109
|
+
async postComment(taskId, commentText, notifyAll) {
|
|
110
|
+
const body = { comment_text: commentText };
|
|
111
|
+
if (notifyAll) body.notify_all = true;
|
|
110
112
|
return this.request(this.taskPath(taskId, "/comment"), {
|
|
111
113
|
method: "POST",
|
|
112
|
-
body: JSON.stringify(
|
|
114
|
+
body: JSON.stringify(body)
|
|
113
115
|
});
|
|
114
116
|
}
|
|
115
117
|
async getTaskComments(taskId) {
|
|
@@ -235,10 +237,12 @@ var ClickUpClient = class {
|
|
|
235
237
|
const data = await this.request(`/comment/${commentId}/reply`);
|
|
236
238
|
return data.comments ?? [];
|
|
237
239
|
}
|
|
238
|
-
async createThreadedComment(commentId, text) {
|
|
240
|
+
async createThreadedComment(commentId, text, notifyAll) {
|
|
241
|
+
const body = { comment_text: text };
|
|
242
|
+
if (notifyAll) body.notify_all = true;
|
|
239
243
|
await this.request(`/comment/${commentId}/reply`, {
|
|
240
244
|
method: "POST",
|
|
241
|
-
body: JSON.stringify(
|
|
245
|
+
body: JSON.stringify(body)
|
|
242
246
|
});
|
|
243
247
|
}
|
|
244
248
|
async addTaskLink(taskId, linksTo) {
|
|
@@ -412,14 +416,14 @@ function loadConfig() {
|
|
|
412
416
|
}
|
|
413
417
|
const apiToken = envToken || fileToken;
|
|
414
418
|
if (!apiToken) {
|
|
415
|
-
throw new Error("Config missing required field: apiToken.\nSet CU_API_TOKEN or run:
|
|
419
|
+
throw new Error("Config missing required field: apiToken.\nSet CU_API_TOKEN or run: cup init");
|
|
416
420
|
}
|
|
417
421
|
if (!apiToken.startsWith("pk_")) {
|
|
418
422
|
throw new Error("Config apiToken must start with pk_. The configured token does not.");
|
|
419
423
|
}
|
|
420
424
|
const teamId = envTeamId || fileTeamId;
|
|
421
425
|
if (!teamId) {
|
|
422
|
-
throw new Error("Config missing required field: teamId.\nSet CU_TEAM_ID or run:
|
|
426
|
+
throw new Error("Config missing required field: teamId.\nSet CU_TEAM_ID or run: cup init");
|
|
423
427
|
}
|
|
424
428
|
return { apiToken, teamId };
|
|
425
429
|
}
|
|
@@ -617,6 +621,20 @@ function formatTaskDetailMarkdown(task) {
|
|
|
617
621
|
lines.push(`- [${att.title}](${att.url})`);
|
|
618
622
|
}
|
|
619
623
|
}
|
|
624
|
+
if (task.dependencies?.length) {
|
|
625
|
+
lines.push("", "## Dependencies", "");
|
|
626
|
+
for (const dep of task.dependencies) {
|
|
627
|
+
const direction = dep.depends_on === task.id ? "blocks" : "depends on";
|
|
628
|
+
const otherId = dep.depends_on === task.id ? dep.task_id : dep.depends_on;
|
|
629
|
+
lines.push(`- ${direction} ${otherId}`);
|
|
630
|
+
}
|
|
631
|
+
}
|
|
632
|
+
if (task.linked_tasks?.length) {
|
|
633
|
+
lines.push("", "## Linked Tasks", "");
|
|
634
|
+
for (const lt of task.linked_tasks) {
|
|
635
|
+
lines.push(`- ${lt.task_id}`);
|
|
636
|
+
}
|
|
637
|
+
}
|
|
620
638
|
return lines.join("\n");
|
|
621
639
|
}
|
|
622
640
|
function formatUpdateConfirmation(id, name) {
|
|
@@ -770,6 +788,22 @@ function formatTaskDetail(task) {
|
|
|
770
788
|
lines.push(` ${att.title} ${chalk2.dim(att.url)}`);
|
|
771
789
|
}
|
|
772
790
|
}
|
|
791
|
+
if (task.dependencies?.length) {
|
|
792
|
+
lines.push("");
|
|
793
|
+
lines.push(chalk2.bold("Dependencies"));
|
|
794
|
+
for (const dep of task.dependencies) {
|
|
795
|
+
const direction = dep.depends_on === task.id ? "blocks" : "depends on";
|
|
796
|
+
const otherId = dep.depends_on === task.id ? dep.task_id : dep.depends_on;
|
|
797
|
+
lines.push(` ${direction} ${chalk2.dim(otherId)}`);
|
|
798
|
+
}
|
|
799
|
+
}
|
|
800
|
+
if (task.linked_tasks?.length) {
|
|
801
|
+
lines.push("");
|
|
802
|
+
lines.push(chalk2.bold("Linked Tasks"));
|
|
803
|
+
for (const lt of task.linked_tasks) {
|
|
804
|
+
lines.push(` ${chalk2.dim(lt.task_id)}`);
|
|
805
|
+
}
|
|
806
|
+
}
|
|
773
807
|
if (task.text_content?.trim()) {
|
|
774
808
|
lines.push("");
|
|
775
809
|
lines.push(descriptionPreview(task.text_content));
|
|
@@ -1337,10 +1371,10 @@ async function fetchSubtasks(config, taskId, options = {}) {
|
|
|
1337
1371
|
}
|
|
1338
1372
|
|
|
1339
1373
|
// src/commands/comment.ts
|
|
1340
|
-
async function postComment(config, taskId, text) {
|
|
1374
|
+
async function postComment(config, taskId, text, notifyAll) {
|
|
1341
1375
|
if (!text.trim()) throw new Error("Comment text cannot be empty");
|
|
1342
1376
|
const client = new ClickUpClient(config);
|
|
1343
|
-
return client.postComment(taskId, text);
|
|
1377
|
+
return client.postComment(taskId, text, notifyAll);
|
|
1344
1378
|
}
|
|
1345
1379
|
|
|
1346
1380
|
// src/commands/comments.ts
|
|
@@ -1948,7 +1982,7 @@ function bashCompletion(name) {
|
|
|
1948
1982
|
COMPREPLY=($(compgen -W "--status --name --include-closed --json" -- "$cur"))
|
|
1949
1983
|
;;
|
|
1950
1984
|
comment)
|
|
1951
|
-
COMPREPLY=($(compgen -W "-m --message --json" -- "$cur"))
|
|
1985
|
+
COMPREPLY=($(compgen -W "-m --message --notify-all --json" -- "$cur"))
|
|
1952
1986
|
;;
|
|
1953
1987
|
comments)
|
|
1954
1988
|
COMPREPLY=($(compgen -W "--json" -- "$cur"))
|
|
@@ -2021,7 +2055,7 @@ function bashCompletion(name) {
|
|
|
2021
2055
|
COMPREPLY=($(compgen -W "--json" -- "$cur"))
|
|
2022
2056
|
;;
|
|
2023
2057
|
reply)
|
|
2024
|
-
COMPREPLY=($(compgen -W "-m --message --json" -- "$cur"))
|
|
2058
|
+
COMPREPLY=($(compgen -W "-m --message --notify-all --json" -- "$cur"))
|
|
2025
2059
|
;;
|
|
2026
2060
|
link)
|
|
2027
2061
|
COMPREPLY=($(compgen -W "--remove --json" -- "$cur"))
|
|
@@ -2172,6 +2206,7 @@ _${name}() {
|
|
|
2172
2206
|
_arguments \\
|
|
2173
2207
|
'1:task_id:' \\
|
|
2174
2208
|
'(-m --message)'{-m,--message}'[Comment text]:text:' \\
|
|
2209
|
+
'--notify-all[Notify all assignees]' \\
|
|
2175
2210
|
'--json[Force JSON output]'
|
|
2176
2211
|
;;
|
|
2177
2212
|
comments)
|
|
@@ -2393,6 +2428,7 @@ _${name}() {
|
|
|
2393
2428
|
_arguments \\
|
|
2394
2429
|
'1:comment_id:' \\
|
|
2395
2430
|
'(-m --message)'{-m,--message}'[Reply text]:text:' \\
|
|
2431
|
+
'--notify-all[Notify all assignees]' \\
|
|
2396
2432
|
'--json[Force JSON output]'
|
|
2397
2433
|
;;
|
|
2398
2434
|
link)
|
|
@@ -2534,6 +2570,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l include-closed
|
|
|
2534
2570
|
complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l json -d 'Force JSON output'
|
|
2535
2571
|
|
|
2536
2572
|
complete -c ${name} -n '__fish_seen_subcommand_from comment' -s m -l message -d 'Comment text'
|
|
2573
|
+
complete -c ${name} -n '__fish_seen_subcommand_from comment' -l notify-all -d 'Notify all assignees'
|
|
2537
2574
|
complete -c ${name} -n '__fish_seen_subcommand_from comment' -l json -d 'Force JSON output'
|
|
2538
2575
|
|
|
2539
2576
|
complete -c ${name} -n '__fish_seen_subcommand_from comments' -l json -d 'Force JSON output'
|
|
@@ -2619,6 +2656,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from comment-delete' -l json -d '
|
|
|
2619
2656
|
complete -c ${name} -n '__fish_seen_subcommand_from replies' -l json -d 'Force JSON output'
|
|
2620
2657
|
|
|
2621
2658
|
complete -c ${name} -n '__fish_seen_subcommand_from reply' -s m -l message -d 'Reply text'
|
|
2659
|
+
complete -c ${name} -n '__fish_seen_subcommand_from reply' -l notify-all -d 'Notify all assignees'
|
|
2622
2660
|
complete -c ${name} -n '__fish_seen_subcommand_from reply' -l json -d 'Force JSON output'
|
|
2623
2661
|
|
|
2624
2662
|
complete -c ${name} -n '__fish_seen_subcommand_from link' -l remove -d 'Remove the link'
|
|
@@ -2640,7 +2678,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from get set' -a 'apiToken teamId
|
|
|
2640
2678
|
complete -c ${name} -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d 'Shell type'
|
|
2641
2679
|
`;
|
|
2642
2680
|
}
|
|
2643
|
-
function generateCompletion(shell, name = "
|
|
2681
|
+
function generateCompletion(shell, name = "cup") {
|
|
2644
2682
|
switch (shell) {
|
|
2645
2683
|
case "bash":
|
|
2646
2684
|
return bashCompletion(name);
|
|
@@ -2951,10 +2989,10 @@ async function getReplies(config, commentId) {
|
|
|
2951
2989
|
const client = new ClickUpClient(config);
|
|
2952
2990
|
return client.getThreadedComments(commentId);
|
|
2953
2991
|
}
|
|
2954
|
-
async function createReply(config, commentId, text) {
|
|
2992
|
+
async function createReply(config, commentId, text, notifyAll) {
|
|
2955
2993
|
if (!text.trim()) throw new Error("Reply text cannot be empty");
|
|
2956
2994
|
const client = new ClickUpClient(config);
|
|
2957
|
-
await client.createThreadedComment(commentId, text);
|
|
2995
|
+
await client.createThreadedComment(commentId, text, notifyAll);
|
|
2958
2996
|
}
|
|
2959
2997
|
function formatReplies(replies) {
|
|
2960
2998
|
if (replies.length === 0) return "No replies";
|
|
@@ -3057,7 +3095,7 @@ function formatTimeEntries(entries) {
|
|
|
3057
3095
|
// src/index.ts
|
|
3058
3096
|
var require2 = createRequire(import.meta.url);
|
|
3059
3097
|
var { version } = require2("../package.json");
|
|
3060
|
-
var programName = basename(process.argv[1] ?? "
|
|
3098
|
+
var programName = basename(process.argv[1] ?? "cup");
|
|
3061
3099
|
function wrapAction(fn) {
|
|
3062
3100
|
return (...args) => {
|
|
3063
3101
|
fn(...args).catch((err) => {
|
|
@@ -3178,16 +3216,18 @@ program.command("subtasks <taskId>").description("List subtasks of a task or ini
|
|
|
3178
3216
|
}
|
|
3179
3217
|
)
|
|
3180
3218
|
);
|
|
3181
|
-
program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--json", "Force JSON output even in terminal").action(
|
|
3182
|
-
wrapAction(
|
|
3183
|
-
|
|
3184
|
-
|
|
3185
|
-
|
|
3186
|
-
|
|
3187
|
-
|
|
3188
|
-
|
|
3219
|
+
program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option("--json", "Force JSON output even in terminal").action(
|
|
3220
|
+
wrapAction(
|
|
3221
|
+
async (taskId, opts) => {
|
|
3222
|
+
const config = loadConfig();
|
|
3223
|
+
const result = await postComment(config, taskId, opts.message, opts.notifyAll);
|
|
3224
|
+
if (shouldOutputJson(opts.json ?? false)) {
|
|
3225
|
+
console.log(JSON.stringify(result, null, 2));
|
|
3226
|
+
} else {
|
|
3227
|
+
console.log(formatCommentConfirmation(result.id));
|
|
3228
|
+
}
|
|
3189
3229
|
}
|
|
3190
|
-
|
|
3230
|
+
)
|
|
3191
3231
|
);
|
|
3192
3232
|
program.command("comments <taskId>").description("List comments on a task").option("--json", "Force JSON output even in terminal").action(
|
|
3193
3233
|
wrapAction(async (taskId, opts) => {
|
|
@@ -3234,16 +3274,18 @@ program.command("replies <commentId>").description("List threaded replies on a c
|
|
|
3234
3274
|
}
|
|
3235
3275
|
})
|
|
3236
3276
|
);
|
|
3237
|
-
program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--json", "Force JSON output even in terminal").action(
|
|
3238
|
-
wrapAction(
|
|
3239
|
-
|
|
3240
|
-
|
|
3241
|
-
|
|
3242
|
-
|
|
3243
|
-
|
|
3244
|
-
|
|
3277
|
+
program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--notify-all", "Notify all assignees").option("--json", "Force JSON output even in terminal").action(
|
|
3278
|
+
wrapAction(
|
|
3279
|
+
async (commentId, opts) => {
|
|
3280
|
+
const config = loadConfig();
|
|
3281
|
+
await createReply(config, commentId, opts.message, opts.notifyAll);
|
|
3282
|
+
if (shouldOutputJson(opts.json ?? false)) {
|
|
3283
|
+
console.log(JSON.stringify({ success: true, commentId }, null, 2));
|
|
3284
|
+
} else {
|
|
3285
|
+
console.log(`Replied to comment ${commentId}`);
|
|
3286
|
+
}
|
|
3245
3287
|
}
|
|
3246
|
-
|
|
3288
|
+
)
|
|
3247
3289
|
);
|
|
3248
3290
|
program.command("activity <taskId>").description("Show task details and comments combined").option("--json", "Force JSON output even in terminal").action(
|
|
3249
3291
|
wrapAction(async (taskId, opts) => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@krodak/clickup-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.21.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": [
|
|
@@ -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/cu/config.json` with `apiToken` and `teamId`. Run `
|
|
14
|
+
Config at `~/.config/cu/config.json` with `apiToken` and `teamId`. 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,184 @@ 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] [--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 |
|
|
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 via view API and date range parsing |
|
|
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
|
|
210
206
|
```
|
|
211
207
|
|
|
212
208
|
### Standup
|
|
213
209
|
|
|
214
210
|
```bash
|
|
215
|
-
|
|
216
|
-
|
|
211
|
+
cup summary # completed / in progress / overdue
|
|
212
|
+
cup summary --hours 48 # wider window
|
|
217
213
|
```
|
|
218
214
|
|
|
219
215
|
## DELETE SAFETY
|
|
220
216
|
|
|
221
|
-
IMPORTANT: Always confirm with the user before running `
|
|
217
|
+
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.
|