@krodak/clickup-cli 0.18.0 → 0.20.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup-cli",
   "description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cu/cup command",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -307,6 +307,23 @@ Environment variables override config file values:
 
 When both are set, the config file is not required. Useful for CI/CD and containerized agents.
 
+## Custom Task IDs
+
+ClickUp workspaces can configure custom task IDs with a prefix per space (e.g., `PROJ-123`, `DEV-42`). The CLI detects these automatically - any ID matching the `PREFIX-DIGITS` format (uppercase letters, hyphen, digits) is treated as a custom task ID.
+
+All commands that accept task IDs work with both native IDs and custom IDs:
+
+```bash
+cu task PROJ-123
+cu update DEV-42 --status done
+cu comment PROJ-456 -m "Fixed in latest commit"
+cu subtasks DEV-100
+```
+
+Custom ID resolution uses the `teamId` from your config, which is required (`cu init` sets it up).
+
+**Task links with custom IDs:** The `cu 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.
+
 ## Why a CLI and not MCP?
 
 A CLI + skill file has fewer moving parts. No server process, no protocol layer. The agent already knows how to run shell commands - the skill file teaches it which ones exist. For tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.

package/dist/index.js

@@ -8,11 +8,30 @@ import { createRequire } from "module";
 // src/api.ts
 var BASE_URL = "https://api.clickup.com/api/v2";
 var MAX_PAGES = 100;
+function isCustomTaskId(id) {
+  return /^[A-Z]+-\d+$/i.test(id);
+}
 var ClickUpClient = class {
   apiToken;
+  teamId;
   meCache = null;
   constructor(config) {
     this.apiToken = config.apiToken;
+    this.teamId = config.teamId;
+  }
+  taskPath(taskId, suffix = "") {
+    const base = `/task/${taskId}${suffix}`;
+    if (isCustomTaskId(taskId) && this.teamId) {
+      const sep = base.includes("?") ? "&" : "?";
+      return `${base}${sep}custom_task_ids=true&team_id=${this.teamId}`;
+    }
+    return base;
+  }
+  customIdQueryParams(taskId) {
+    if (isCustomTaskId(taskId) && this.teamId) {
+      return `?custom_task_ids=true&team_id=${this.teamId}`;
+    }
+    return "";
   }
   async request(path, options = {}) {
     const res = await fetch(`${BASE_URL}${path}`, {
@@ -82,19 +101,21 @@ var ClickUpClient = class {
     });
   }
   async updateTask(taskId, options) {
-    return this.request(`/task/${taskId}`, {
+    return this.request(this.taskPath(taskId), {
       method: "PUT",
       body: JSON.stringify(options)
     });
   }
-  async postComment(taskId, commentText) {
-    return this.request(`/task/${taskId}/comment`, {
+  async postComment(taskId, commentText, notifyAll) {
+    const body = { comment_text: commentText };
+    if (notifyAll) body.notify_all = true;
+    return this.request(this.taskPath(taskId, "/comment"), {
       method: "POST",
-      body: JSON.stringify({ comment_text: commentText })
+      body: JSON.stringify(body)
     });
   }
   async getTaskComments(taskId) {
-    const data = await this.request(`/task/${taskId}/comment`);
+    const data = await this.request(this.taskPath(taskId, "/comment"));
     return data.comments ?? [];
   }
   async getTasksFromList(listId, params = {}, options = {}) {
@@ -106,7 +127,7 @@ var ClickUpClient = class {
     });
   }
   async getTask(taskId) {
-    return this.request(`/task/${taskId}?include_markdown_description=true`);
+    return this.request(this.taskPath(taskId, "?include_markdown_description=true"));
   }
   async createTask(listId, options) {
     return this.request(`/list/${listId}/task`, {
@@ -163,28 +184,32 @@ var ClickUpClient = class {
     await this.request(`/list/${listId}/task/${taskId}`, { method: "DELETE" });
   }
   async setCustomFieldValue(taskId, fieldId, value) {
-    await this.request(`/task/${taskId}/field/${fieldId}`, {
+    await this.request(this.taskPath(taskId, `/field/${fieldId}`), {
       method: "POST",
       body: JSON.stringify({ value })
     });
   }
   async removeCustomFieldValue(taskId, fieldId) {
-    await this.request(`/task/${taskId}/field/${fieldId}`, { method: "DELETE" });
+    await this.request(this.taskPath(taskId, `/field/${fieldId}`), { method: "DELETE" });
   }
   async deleteTask(taskId) {
-    await this.request(`/task/${taskId}`, { method: "DELETE" });
+    await this.request(this.taskPath(taskId), { method: "DELETE" });
   }
   async addTagToTask(taskId, tagName) {
-    await this.request(`/task/${taskId}/tag/${encodeURIComponent(tagName)}`, { method: "POST" });
+    await this.request(this.taskPath(taskId, `/tag/${encodeURIComponent(tagName)}`), {
+      method: "POST"
+    });
   }
   async removeTagFromTask(taskId, tagName) {
-    await this.request(`/task/${taskId}/tag/${encodeURIComponent(tagName)}`, { method: "DELETE" });
+    await this.request(this.taskPath(taskId, `/tag/${encodeURIComponent(tagName)}`), {
+      method: "DELETE"
+    });
   }
   async addDependency(taskId, opts) {
     const body = {};
     if (opts.dependsOn) body.depends_on = opts.dependsOn;
     if (opts.dependencyOf) body.dependency_of = opts.dependencyOf;
-    await this.request(`/task/${taskId}/dependency`, {
+    await this.request(this.taskPath(taskId, "/dependency"), {
       method: "POST",
       body: JSON.stringify(body)
     });
@@ -193,7 +218,7 @@ var ClickUpClient = class {
     const params = new URLSearchParams();
     if (opts.dependsOn) params.set("depends_on", opts.dependsOn);
     if (opts.dependencyOf) params.set("dependency_of", opts.dependencyOf);
-    await this.request(`/task/${taskId}/dependency?${params.toString()}`, {
+    await this.request(this.taskPath(taskId, `/dependency?${params.toString()}`), {
       method: "DELETE"
     });
   }
@@ -212,24 +237,30 @@ var ClickUpClient = class {
     const data = await this.request(`/comment/${commentId}/reply`);
     return data.comments ?? [];
   }
-  async createThreadedComment(commentId, text) {
+  async createThreadedComment(commentId, text, notifyAll) {
+    const body = { comment_text: text };
+    if (notifyAll) body.notify_all = true;
     await this.request(`/comment/${commentId}/reply`, {
       method: "POST",
-      body: JSON.stringify({ comment_text: text })
+      body: JSON.stringify(body)
     });
   }
   async addTaskLink(taskId, linksTo) {
-    await this.request(`/task/${taskId}/link/${linksTo}`, { method: "POST" });
+    await this.request(this.taskPath(taskId, `/link/${linksTo}`), {
+      method: "POST"
+    });
   }
   async deleteTaskLink(taskId, linksTo) {
-    await this.request(`/task/${taskId}/link/${linksTo}`, { method: "DELETE" });
+    await this.request(this.taskPath(taskId, `/link/${linksTo}`), {
+      method: "DELETE"
+    });
   }
   async getListCustomFields(listId) {
     const data = await this.request(`/list/${listId}/field`);
     return data.fields ?? [];
   }
   async createChecklist(taskId, name) {
-    const data = await this.request(`/task/${taskId}/checklist`, {
+    const data = await this.request(this.taskPath(taskId, "/checklist"), {
       method: "POST",
       body: JSON.stringify({ name })
     });
@@ -265,10 +296,13 @@ var ClickUpClient = class {
       duration: -1
     };
     if (description) body.description = description;
-    const data = await this.request(`/team/${teamId}/time_entries/start`, {
-      method: "POST",
-      body: JSON.stringify(body)
-    });
+    const data = await this.request(
+      `/team/${teamId}/time_entries/start${this.customIdQueryParams(taskId)}`,
+      {
+        method: "POST",
+        body: JSON.stringify(body)
+      }
+    );
     return data.data;
   }
   async stopTimeEntry(teamId) {
@@ -291,10 +325,13 @@ var ClickUpClient = class {
       duration
     };
     if (opts?.description) body.description = opts.description;
-    const data = await this.request(`/team/${teamId}/time_entries`, {
-      method: "POST",
-      body: JSON.stringify(body)
-    });
+    const data = await this.request(
+      `/team/${teamId}/time_entries${this.customIdQueryParams(taskId)}`,
+      {
+        method: "POST",
+        body: JSON.stringify(body)
+      }
+    );
     return data.data;
   }
   async getTimeEntries(teamId, opts) {
@@ -322,7 +359,7 @@ var ClickUpClient = class {
     const fileName = basename2(filePath);
     const formData = new FormData();
     formData.append("attachment", new Blob([fileBuffer]), fileName);
-    const res = await fetch(`${BASE_URL}/task/${taskId}/attachment`, {
+    const res = await fetch(`${BASE_URL}${this.taskPath(taskId, "/attachment")}`, {
       method: "POST",
       headers: { Authorization: this.apiToken },
       body: formData,
@@ -584,6 +621,20 @@ function formatTaskDetailMarkdown(task) {
       lines.push(`- [${att.title}](${att.url})`);
     }
   }
+  if (task.dependencies?.length) {
+    lines.push("", "## Dependencies", "");
+    for (const dep of task.dependencies) {
+      const direction = dep.depends_on === task.id ? "blocks" : "depends on";
+      const otherId = dep.depends_on === task.id ? dep.task_id : dep.depends_on;
+      lines.push(`- ${direction} ${otherId}`);
+    }
+  }
+  if (task.linked_tasks?.length) {
+    lines.push("", "## Linked Tasks", "");
+    for (const lt of task.linked_tasks) {
+      lines.push(`- ${lt.task_id}`);
+    }
+  }
   return lines.join("\n");
 }
 function formatUpdateConfirmation(id, name) {
@@ -737,6 +788,22 @@ function formatTaskDetail(task) {
       lines.push(`  ${att.title} ${chalk2.dim(att.url)}`);
     }
   }
+  if (task.dependencies?.length) {
+    lines.push("");
+    lines.push(chalk2.bold("Dependencies"));
+    for (const dep of task.dependencies) {
+      const direction = dep.depends_on === task.id ? "blocks" : "depends on";
+      const otherId = dep.depends_on === task.id ? dep.task_id : dep.depends_on;
+      lines.push(`  ${direction} ${chalk2.dim(otherId)}`);
+    }
+  }
+  if (task.linked_tasks?.length) {
+    lines.push("");
+    lines.push(chalk2.bold("Linked Tasks"));
+    for (const lt of task.linked_tasks) {
+      lines.push(`  ${chalk2.dim(lt.task_id)}`);
+    }
+  }
   if (task.text_content?.trim()) {
     lines.push("");
     lines.push(descriptionPreview(task.text_content));
@@ -1304,10 +1371,10 @@ async function fetchSubtasks(config, taskId, options = {}) {
 }
 
 // src/commands/comment.ts
-async function postComment(config, taskId, text) {
+async function postComment(config, taskId, text, notifyAll) {
   if (!text.trim()) throw new Error("Comment text cannot be empty");
   const client = new ClickUpClient(config);
-  return client.postComment(taskId, text);
+  return client.postComment(taskId, text, notifyAll);
 }
 
 // src/commands/comments.ts
@@ -1598,7 +1665,7 @@ async function runAssignedCommand(config, opts) {
 
 // src/commands/open.ts
 function looksLikeTaskId(query) {
-  return /^[a-z0-9]+$/i.test(query) && query.length <= 12;
+  return /^[a-z0-9]+$/i.test(query) && query.length <= 12 || isCustomTaskId(query);
 }
 async function openTask(config, query, opts = {}) {
   const client = new ClickUpClient(config);
@@ -1915,7 +1982,7 @@ function bashCompletion(name) {
       COMPREPLY=($(compgen -W "--status --name --include-closed --json" -- "$cur"))
       ;;
     comment)
-      COMPREPLY=($(compgen -W "-m --message --json" -- "$cur"))
+      COMPREPLY=($(compgen -W "-m --message --notify-all --json" -- "$cur"))
       ;;
     comments)
       COMPREPLY=($(compgen -W "--json" -- "$cur"))
@@ -1988,7 +2055,7 @@ function bashCompletion(name) {
       COMPREPLY=($(compgen -W "--json" -- "$cur"))
       ;;
     reply)
-      COMPREPLY=($(compgen -W "-m --message --json" -- "$cur"))
+      COMPREPLY=($(compgen -W "-m --message --notify-all --json" -- "$cur"))
       ;;
     link)
       COMPREPLY=($(compgen -W "--remove --json" -- "$cur"))
@@ -2139,6 +2206,7 @@ _${name}() {
           _arguments \\
             '1:task_id:' \\
             '(-m --message)'{-m,--message}'[Comment text]:text:' \\
+            '--notify-all[Notify all assignees]' \\
             '--json[Force JSON output]'
           ;;
         comments)
@@ -2360,6 +2428,7 @@ _${name}() {
           _arguments \\
             '1:comment_id:' \\
             '(-m --message)'{-m,--message}'[Reply text]:text:' \\
+            '--notify-all[Notify all assignees]' \\
             '--json[Force JSON output]'
           ;;
         link)
@@ -2501,6 +2570,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l include-closed
 complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l json -d 'Force JSON output'
 
 complete -c ${name} -n '__fish_seen_subcommand_from comment' -s m -l message -d 'Comment text'
+complete -c ${name} -n '__fish_seen_subcommand_from comment' -l notify-all -d 'Notify all assignees'
 complete -c ${name} -n '__fish_seen_subcommand_from comment' -l json -d 'Force JSON output'
 
 complete -c ${name} -n '__fish_seen_subcommand_from comments' -l json -d 'Force JSON output'
@@ -2586,6 +2656,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from comment-delete' -l json -d '
 complete -c ${name} -n '__fish_seen_subcommand_from replies' -l json -d 'Force JSON output'
 
 complete -c ${name} -n '__fish_seen_subcommand_from reply' -s m -l message -d 'Reply text'
+complete -c ${name} -n '__fish_seen_subcommand_from reply' -l notify-all -d 'Notify all assignees'
 complete -c ${name} -n '__fish_seen_subcommand_from reply' -l json -d 'Force JSON output'
 
 complete -c ${name} -n '__fish_seen_subcommand_from link' -l remove -d 'Remove the link'
@@ -2918,10 +2989,10 @@ async function getReplies(config, commentId) {
   const client = new ClickUpClient(config);
   return client.getThreadedComments(commentId);
 }
-async function createReply(config, commentId, text) {
+async function createReply(config, commentId, text, notifyAll) {
   if (!text.trim()) throw new Error("Reply text cannot be empty");
   const client = new ClickUpClient(config);
-  await client.createThreadedComment(commentId, text);
+  await client.createThreadedComment(commentId, text, notifyAll);
 }
 function formatReplies(replies) {
   if (replies.length === 0) return "No replies";
@@ -3145,16 +3216,18 @@ program.command("subtasks <taskId>").description("List subtasks of a task or ini
     }
   )
 );
-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(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await postComment(config, taskId, opts.message);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(formatCommentConfirmation(result.id));
+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(
+  wrapAction(
+    async (taskId, opts) => {
+      const config = loadConfig();
+      const result = await postComment(config, taskId, opts.message, opts.notifyAll);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatCommentConfirmation(result.id));
+      }
     }
-  })
+  )
 );
 program.command("comments <taskId>").description("List comments on a task").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
@@ -3201,16 +3274,18 @@ program.command("replies <commentId>").description("List threaded replies on a c
     }
   })
 );
-program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (commentId, opts) => {
-    const config = loadConfig();
-    await createReply(config, commentId, opts.message);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, commentId }, null, 2));
-    } else {
-      console.log(`Replied to comment ${commentId}`);
+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(
+  wrapAction(
+    async (commentId, opts) => {
+      const config = loadConfig();
+      await createReply(config, commentId, opts.message, opts.notifyAll);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify({ success: true, commentId }, null, 2));
+      } else {
+        console.log(`Replied to comment ${commentId}`);
+      }
     }
-  })
+  )
 );
 program.command("activity <taskId>").description("Show task details and comments combined").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krodak/clickup-cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "ClickUp CLI for AI agents and humans",
   "type": "module",
   "license": "MIT",

package/skills/clickup-cli/SKILL.md

@@ -63,7 +63,7 @@ All commands support `--help` for full flag details.
 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
 | `cu 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) |
 | `cu 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)        |
-| `cu comment <id> -m text [--json]`                                                                                                                                                 | Post comment on task                        |
+| `cu comment <id> -m text [--notify-all] [--json]`                                                                                                                                  | Post comment on task                        |
 | `cu comment-edit <commentId> -m text [--resolved] [--unresolved] [--json]`                                                                                                         | Edit an existing comment                    |
 | `cu assign <id> [--to userId\|me] [--remove userId\|me] [--json]`                                                                                                                  | Assign/unassign users                       |
 | `cu depend <id> [--on taskId] [--blocks taskId] [--remove] [--json]`                                                                                                               | Add/remove task dependencies                |
@@ -79,7 +79,7 @@ All commands support `--help` for full flag details.
 | `cu checklist delete-item <checklistId> <itemId> [--json]`                                                                                                                         | Delete a checklist item                     |
 | `cu comment-delete <commentId> [--json]`                                                                                                                                           | Delete a comment                            |
 | `cu replies <commentId> [--json]`                                                                                                                                                  | List threaded replies on a comment          |
-| `cu reply <commentId> -m text [--json]`                                                                                                                                            | Reply to a comment                          |
+| `cu reply <commentId> -m text [--notify-all] [--json]`                                                                                                                             | Reply to a comment                          |
 | `cu link <taskId> <linksTo> [--remove] [--json]`                                                                                                                                   | Add or remove link between tasks            |
 | `cu attach <taskId> <filePath> [--json]`                                                                                                                                           | Upload file attachment to a task            |
 | `cu time start <taskId> [-d desc] [--json]`                                                                                                                                        | Start tracking time on a task               |
@@ -94,7 +94,7 @@ All commands support `--help` for full flag details.
 
 | Topic                     | Detail                                                                                                 |
 | ------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Task IDs                  | Stable alphanumeric strings (e.g. `abc123def`)                                                         |
+| Task IDs                  | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format        |
 | `--type`                  | Filter by task type: `task` (regular), or custom type name/ID (e.g. `initiative`, `Bug`)               |
 | `--list` on create        | Optional when `--parent` is given (auto-detected)                                                      |
 | `--status`                | Fuzzy matching: exact > starts-with > contains. Prints match to stderr.                                |
@@ -124,9 +124,11 @@ All commands support `--help` for full flag details.
 | `cu comment-edit`         | Edit comment text and resolution status                                                                |
 | `cu comment-delete`       | Delete a comment                                                                                       |
 | `cu replies` / `cu reply` | View and post threaded comment replies                                                                 |
+| Custom task IDs           | Auto-detected by format (`PROJ-123`). Uses `teamId` from config. All commands support them             |
+| `cu link` + custom IDs    | Both IDs must be the same type (both custom or both native). Mixing may not work                       |
 | `cu link`                 | Link/unlink tasks (different from dependencies)                                                        |
 | `cu attach`               | Upload files to tasks. Attachments shown in `cu task` detail view                                      |
-| `cu task`                 | Shows custom fields, checklists, and attachments in detail view                                        |
+| `cu task`                 | Shows custom fields, checklists, attachments, dependencies, and linked tasks in detail view            |
 | `cu lists`                | Discovers list IDs needed for `--list` and `cu create -l`                                              |
 | Errors                    | stderr with exit code 1                                                                                |
 | Parsing                   | Strict - excess/unknown arguments rejected                                                             |