@krodak/clickup-cli 0.18.0 → 0.19.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.19.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,19 @@ 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`, {
+    return this.request(this.taskPath(taskId, "/comment"), {
       method: "POST",
       body: JSON.stringify({ comment_text: commentText })
     });
   }
   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 +125,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 +182,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 +216,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"
     });
   }
@@ -219,17 +242,21 @@ var ClickUpClient = class {
     });
   }
   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 +292,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 +321,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 +355,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,
@@ -1598,7 +1631,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);

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -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,6 +124,8 @@ 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                                        |