@krodak/clickup-cli 1.38.2 → 1.39.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 cup command",
-  "version": "1.38.2",
+  "version": "1.39.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/dist/index.js

@@ -291,6 +291,24 @@ var ClickUpClient = class {
   async getTask(taskId) {
     return this.request(this.taskPath(taskId, "?include_markdown_description=true"));
   }
+  /**
+   * Resolve any accepted task-id form to a native ClickUp task id.
+   * - Task URLs are reduced to their id segment.
+   * - Workspace custom ids (e.g. PROD-811) are resolved to the native id via GET.
+   * - Native ids pass through without an API call.
+   *
+   * Use this for task ids that appear in request bodies, query params, or
+   * secondary path segments, where ClickUp's custom_task_ids handling
+   * (applied by taskPath to the primary path id) does not reach.
+   */
+  async resolveTaskId(input) {
+    const normalized = normalizeTaskId(input);
+    if (isCustomTaskId(normalized) && this.teamId) {
+      const task = await this.getTask(normalized);
+      return task.id;
+    }
+    return normalized;
+  }
   async getTimeInStatus(taskId) {
     return this.request(this.taskPath(taskId, "/time_in_status"));
   }
@@ -522,19 +540,21 @@ var ClickUpClient = class {
     });
   }
   async addDependency(taskId, opts) {
+    const primary = await this.resolveTaskId(taskId);
     const body = {};
-    if (opts.dependsOn) body.depends_on = opts.dependsOn;
-    if (opts.dependencyOf) body.dependency_of = opts.dependencyOf;
-    await this.request(this.taskPath(taskId, "/dependency"), {
+    if (opts.dependsOn) body.depends_on = await this.resolveTaskId(opts.dependsOn);
+    if (opts.dependencyOf) body.dependency_of = await this.resolveTaskId(opts.dependencyOf);
+    await this.request(`/task/${primary}/dependency`, {
       method: "POST",
       body: JSON.stringify(body)
     });
   }
   async deleteDependency(taskId, opts) {
+    const primary = await this.resolveTaskId(taskId);
     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(this.taskPath(taskId, `/dependency?${params.toString()}`), {
+    if (opts.dependsOn) params.set("depends_on", await this.resolveTaskId(opts.dependsOn));
+    if (opts.dependencyOf) params.set("dependency_of", await this.resolveTaskId(opts.dependencyOf));
+    await this.request(`/task/${primary}/dependency?${params.toString()}`, {
       method: "DELETE"
     });
   }
@@ -562,16 +582,12 @@ var ClickUpClient = class {
     });
   }
   async addTaskLink(taskId, linksTo) {
-    await this.request(
-      this.taskPath(taskId, `/link/${normalizeTaskId(linksTo)}`),
-      { method: "POST" }
-    );
+    const [a, b] = await Promise.all([this.resolveTaskId(taskId), this.resolveTaskId(linksTo)]);
+    await this.request(`/task/${a}/link/${b}`, { method: "POST" });
   }
   async deleteTaskLink(taskId, linksTo) {
-    await this.request(
-      this.taskPath(taskId, `/link/${normalizeTaskId(linksTo)}`),
-      { method: "DELETE" }
-    );
+    const [a, b] = await Promise.all([this.resolveTaskId(taskId), this.resolveTaskId(linksTo)]);
+    await this.request(`/task/${a}/link/${b}`, { method: "DELETE" });
   }
   async getListCustomFields(listId) {
     const data = await this.request(`/list/${listId}/field`);
@@ -1062,9 +1078,11 @@ var ClickUpClient = class {
     );
   }
   async mergeTasks(taskId, mergeWithTaskIds) {
-    await this.request(this.taskPath(taskId, "/merge"), {
+    const primary = await this.resolveTaskId(taskId);
+    const mergeWith = await Promise.all(mergeWithTaskIds.map((id) => this.resolveTaskId(id)));
+    await this.request(`/task/${primary}/merge`, {
       method: "POST",
-      body: JSON.stringify({ merge_with: mergeWithTaskIds.map(normalizeTaskId) })
+      body: JSON.stringify({ merge_with: mergeWith })
     });
   }
   async updateTimeEstimatesByUser(taskId, estimates) {
@@ -2355,6 +2373,9 @@ async function updateTask(config, taskId, options, typeInput) {
   if (resolved.status !== void 0) {
     resolved.status = await resolveStatus(client, taskId, resolved.status);
   }
+  if (typeof resolved.parent === "string") {
+    resolved.parent = await client.resolveTaskId(resolved.parent);
+  }
   if (resolved.custom_item_id === void 0 && typeInput !== void 0) {
     resolved.custom_item_id = await resolveTaskType2(client, config.teamId, typeInput);
   }
@@ -2367,9 +2388,15 @@ async function createTask(config, options) {
   if (!options.name.trim()) throw new Error("Task name cannot be empty");
   const client = new ClickUpClient(config);
   let listId = options.list;
-  if (!listId && options.parent) {
-    const parentTask = await client.getTask(options.parent);
-    listId = parentTask.list.id;
+  let parentId = options.parent;
+  if (options.parent) {
+    if (!listId) {
+      const parentTask = await client.getTask(options.parent);
+      parentId = parentTask.id;
+      listId = parentTask.list.id;
+    } else {
+      parentId = await client.resolveTaskId(options.parent);
+    }
   }
   if (!listId) {
     throw new Error("Provide --list or --parent (list is auto-detected from parent task)");
@@ -2382,7 +2409,7 @@ async function createTask(config, options) {
   const payload = {
     name: options.name,
     ...options.description !== void 0 ? { markdown_content: options.description } : {},
-    ...options.parent !== void 0 ? { parent: options.parent } : {},
+    ...parentId !== void 0 ? { parent: parentId } : {},
     ...options.status !== void 0 ? { status: options.status } : {}
   };
   if (options.priority !== void 0) {
@@ -2423,6 +2450,34 @@ async function createTask(config, options) {
   return { id: task.id, name: task.name, url: task.url };
 }
 
+// src/text-input.ts
+import { readFileSync } from "fs";
+function resolveTextInput(args) {
+  const { inline, file, inlineFlag, fileFlag } = args;
+  if (inline !== void 0 && file !== void 0) {
+    throw new Error(`Cannot use ${inlineFlag} and ${fileFlag} together`);
+  }
+  if (file === void 0) return inline;
+  const raw = file === "-" ? readStdin(fileFlag) : readTextFile(file, fileFlag);
+  return raw.replace(/\r?\n$/, "");
+}
+function readTextFile(path, fileFlag) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    throw new Error(`Cannot read ${fileFlag} "${path}": ${err.message}`, { cause: err });
+  }
+}
+function readStdin(fileFlag) {
+  try {
+    return readFileSync(0, "utf8");
+  } catch (err) {
+    throw new Error(`Failed to read ${fileFlag} from stdin: ${err.message}`, {
+      cause: err
+    });
+  }
+}
+
 // src/commands/get.ts
 async function getTask(config, taskId) {
   const client = new ClickUpClient(config);
@@ -3843,6 +3898,7 @@ var commandMetadata = [
       "--name",
       "-d",
       "--description",
+      "--description-file",
       "-s",
       "--status",
       "--priority",
@@ -3872,6 +3928,7 @@ var commandMetadata = [
       "--name",
       "-d",
       "--description",
+      "--description-file",
       "-p",
       "--parent",
       "-s",
@@ -3917,7 +3974,7 @@ var commandMetadata = [
   {
     name: "comment",
     description: "Post a comment on a task",
-    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
+    flags: ["-m", "--message", "--message-file", "--notify-all", "--mention", "--json"],
     quickReference: [
       { section: "write", usage: "comment <taskId>", description: "Post a comment on a task" }
     ]
@@ -3925,7 +3982,7 @@ var commandMetadata = [
   {
     name: "comment-edit",
     description: "Edit an existing comment",
-    flags: ["-m", "--message", "--resolved", "--unresolved", "--mention", "--json"],
+    flags: ["-m", "--message", "--message-file", "--resolved", "--unresolved", "--mention", "--json"],
     quickReference: [
       {
         section: "write",
@@ -3969,7 +4026,7 @@ var commandMetadata = [
   {
     name: "reply",
     description: "Reply to a comment",
-    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
+    flags: ["-m", "--message", "--message-file", "--notify-all", "--mention", "--json"],
     quickReference: [
       { section: "write", usage: "reply <commentId>", description: "Reply to a comment" }
     ]
@@ -4804,7 +4861,7 @@ var commandMetadata = [
   {
     name: "list-comment",
     description: "Post a comment on a list",
-    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
+    flags: ["-m", "--message", "--message-file", "--notify-all", "--mention", "--json"],
     quickReference: [
       {
         section: "write",
@@ -4828,7 +4885,7 @@ var commandMetadata = [
   {
     name: "view-comment",
     description: "Post a comment on a view",
-    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
+    flags: ["-m", "--message", "--message-file", "--notify-all", "--mention", "--json"],
     quickReference: [
       {
         section: "write",
@@ -5215,6 +5272,7 @@ ${renderZshTopLevelCommands(name)}
             '1:task_id:' \\
             '(-n --name)'{-n,--name}'[New task name]:text:' \\
             '(-d --description)'{-d,--description}'[New description]:text:' \\
+            '--description-file[Read description from a file (- for stdin)]:path:_files' \\
             '(-s --status)'{-s,--status}'[New status]:status:(open "in progress" "in review" done closed)' \\
             '--priority[Priority level]:priority:(urgent high normal low)' \\
             '--due-date[Due date (YYYY-MM-DD or "none" to clear)]:date:' \\
@@ -5233,6 +5291,7 @@ ${renderZshTopLevelCommands(name)}
             '(-l --list)'{-l,--list}'[Target list ID]:list_id:' \\
             '(-n --name)'{-n,--name}'[Task name]:name:' \\
             '(-d --description)'{-d,--description}'[Task description]:text:' \\
+            '--description-file[Read description from a file (- for stdin)]:path:_files' \\
             '(-p --parent)'{-p,--parent}'[Parent task ID]:task_id:' \\
             '(-s --status)'{-s,--status}'[Initial status]:status:(open "in progress" "in review" done closed)' \\
             '--priority[Priority level]:priority:(urgent high normal low)' \\
@@ -5269,6 +5328,7 @@ ${renderZshTopLevelCommands(name)}
           _arguments \\
             '1:task_id:' \\
             '(-m --message)'{-m,--message}'[Comment text]:text:' \\
+            '--message-file[Read comment from a file (- for stdin)]:path:_files' \\
             '--notify-all[Notify all assignees]' \\
             '--mention[Mention a user (ID, email, username, or me)]:user:' \\
             '--json[Force JSON output]'
@@ -5503,6 +5563,7 @@ ${renderZshTopLevelCommands(name)}
           _arguments \\
             '1:comment_id:' \\
             '(-m --message)'{-m,--message}'[New comment text]:text:' \\
+            '--message-file[Read comment from a file (- for stdin)]:path:_files' \\
             '--resolved[Mark comment as resolved]' \\
             '--unresolved[Mark comment as unresolved]' \\
             '--mention[Mention a user (ID, email, username, or me)]:user:' \\
@@ -5525,6 +5586,7 @@ ${renderZshTopLevelCommands(name)}
           _arguments \\
             '1:comment_id:' \\
             '(-m --message)'{-m,--message}'[Reply text]:text:' \\
+            '--message-file[Read reply from a file (- for stdin)]:path:_files' \\
             '--notify-all[Notify all assignees]' \\
             '--mention[Mention a user (ID, email, username, or me)]:user:' \\
             '--json[Force JSON output]'
@@ -5992,6 +6054,7 @@ ${renderZshTopLevelCommands(name)}
                   _arguments \\
                     '1:channel_id:' \\
                     '(-m --message)'{-m,--message}'[Message content]:text:' \\
+                    '--message-file[Read message from a file (- for stdin)]:path:_files' \\
                     '--post[Send as a post]' \\
                     '--title[Post title]:text:' \\
                     '--json[Force JSON output]'
@@ -6006,6 +6069,7 @@ ${renderZshTopLevelCommands(name)}
                   _arguments \\
                     '1:message_id:' \\
                     '(-m --message)'{-m,--message}'[Reply content]:text:' \\
+                    '--message-file[Read reply from a file (- for stdin)]:path:_files' \\
                     '--json[Force JSON output]'
                   ;;
                 replies)
@@ -6064,6 +6128,7 @@ ${renderZshTopLevelCommands(name)}
                   _arguments \\
                     '1:message_id:' \\
                     '(-m --message)'{-m,--message}'[New message content]:text:' \\
+                    '--message-file[Read message from a file (- for stdin)]:path:_files' \\
                     '--json[Force JSON output]'
                   ;;
                 message-delete)
@@ -6229,7 +6294,7 @@ function generateCompletion(shell, name = "cup") {
 }
 
 // src/commands/skill.ts
-import { readFileSync, realpathSync, mkdirSync, copyFileSync, existsSync } from "fs";
+import { readFileSync as readFileSync2, realpathSync, mkdirSync, copyFileSync, existsSync } from "fs";
 import { join as join2, dirname } from "path";
 import { homedir as homedir2 } from "os";
 import chalk8 from "chalk";
@@ -6246,7 +6311,7 @@ function skillPath() {
   throw new Error("SKILL.md not found. Reinstall with: npm install -g @krodak/clickup-cli");
 }
 function printSkill() {
-  return readFileSync(skillPath(), "utf-8");
+  return readFileSync2(skillPath(), "utf-8");
 }
 function getAgentTargets() {
   const home = homedir2();
@@ -8578,6 +8643,18 @@ function splitCommaList(value) {
 function collect(value, previous) {
   return [...previous, value];
 }
+function resolveRequiredMessage(opts) {
+  const message = resolveTextInput({
+    inline: opts.message,
+    file: opts.messageFile,
+    inlineFlag: "-m",
+    fileFlag: "--message-file"
+  });
+  if (message === void 0) {
+    throw new Error("Provide a message with -m/--message or --message-file");
+  }
+  return message;
+}
 async function resolveMentions(client, teamId, mentions) {
   if (mentions.length === 0) return [];
   const resolve2 = createCachedMemberResolver(client, teamId);
@@ -8706,6 +8783,9 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
     })
   );
   program.command("update <taskId>").description("Update a task").option("-n, --name <text>", "New task name").option("-d, --description <text>", "New description (markdown supported)").option(
+    "--description-file <path>",
+    'Read description from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -d'
+  ).option(
     "-s, --status <status>",
     'New status (fuzzy matched, e.g. "prog" matches "in progress")'
   ).option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option(
@@ -8723,9 +8803,18 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option(
     "--remove-group-assignee <groupIds...>",
     "Remove group assignee (UUID or @handle, can repeat or comma-separated)"
-  ).option("--parent <taskId>", "Set parent task (makes this a subtask)").option("--archive", "Archive the task").option("--unarchive", "Unarchive the task").option("--type <type>", "Change task type (name or custom_item_id)").option("--field <nameAndValue...>", 'Set custom field: --field "Name" value').option("--json", "Force JSON output even in terminal").action(
+  ).option(
+    "--parent <taskId>",
+    "Set parent task (makes this a subtask): native id, custom id, or task URL"
+  ).option("--archive", "Archive the task").option("--unarchive", "Unarchive the task").option("--type <type>", "Change task type (name or custom_item_id)").option("--field <nameAndValue...>", 'Set custom field: --field "Name" value').option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (taskId, opts) => {
+        opts.description = resolveTextInput({
+          inline: opts.description,
+          file: opts.descriptionFile,
+          inlineFlag: "-d",
+          fileFlag: "--description-file"
+        });
         const config = loadConfig(getProfileName());
         const client = new ClickUpClient(config);
         const [timezone] = await Promise.all([
@@ -8783,7 +8872,13 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     )
   );
-  program.command("create").description("Create a new task").option("-l, --list <listId>", 'Target list ID or "sprint:current" for active sprint').requiredOption("-n, --name <name>", "Task name").option("-d, --description <text>", "Task description (markdown supported)").option("-p, --parent <taskId>", "Parent task ID (list auto-detected from parent)").option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option(
+  program.command("create").description("Create a new task").option("-l, --list <listId>", 'Target list ID or "sprint:current" for active sprint').requiredOption("-n, --name <name>", "Task name").option("-d, --description <text>", "Task description (markdown supported)").option(
+    "--description-file <path>",
+    'Read description from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -d'
+  ).option(
+    "-p, --parent <taskId>",
+    "Parent task: native id, custom id (e.g. PROD-811), or task URL (list auto-detected)"
+  ).option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option(
     "--due-date <date>",
     "Due date (YYYY-MM-DD, YYYY-MM-DDTHH:MM[:SS], or full ISO 8601 with offset)"
   ).option(
@@ -8792,6 +8887,12 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--assignee <userId>", 'Assignee user ID or "me"').option("--group-assignee <groupIds>", "Group assignees (UUID or @handle, comma-separated)").option("--tags <tags>", "Comma-separated tag names").option("--custom-item-id <id>", "Custom task type ID (use to create initiatives)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--template <id>", "Create from a task template (find IDs with cup templates)").option("--field <nameAndValue...>", 'Set custom field: --field "Name" value (can repeat)').option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (opts) => {
+        opts.description = resolveTextInput({
+          inline: opts.description,
+          file: opts.descriptionFile,
+          inlineFlag: "-d",
+          fileFlag: "--description-file"
+        });
         const config = loadConfig(getProfileName());
         if (opts.list === "sprint:current") {
           opts.list = await resolveActiveSprintListId(config);
@@ -8877,7 +8978,10 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     )
   );
-  program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option(
+  program.command("comment <taskId>").description("Post a comment on a task").option("-m, --message <text>", "Comment text").option(
+    "--message-file <path>",
+    'Read comment from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--notify-all", "Notify all assignees").option(
     "--mention <user>",
     'Prepend an @mention (ID, email, username, or "me"), repeatable. For a mid-sentence mention, put a <@userId> token in -m instead; bare @Name is not parsed.',
     collect,
@@ -8885,10 +8989,11 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (taskId, opts) => {
+        const message = resolveRequiredMessage(opts);
         const config = loadConfig(getProfileName());
         const client = new ClickUpClient(config);
         const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
-        const result = await postComment(config, taskId, opts.message, opts.notifyAll, mentionIds);
+        const result = await postComment(config, taskId, message, opts.notifyAll, mentionIds);
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify(result, null, 2));
         } else {
@@ -8904,7 +9009,10 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       printComments(comments, opts.json ?? false);
     })
   );
-  program.command("comment-edit <commentId>").description("Edit an existing comment").option("-m, --message <text>", "New comment text").option("--resolved", "Mark comment as resolved").option("--unresolved", "Mark comment as unresolved").option(
+  program.command("comment-edit <commentId>").description("Edit an existing comment").option("-m, --message <text>", "New comment text").option(
+    "--message-file <path>",
+    'Read comment from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--resolved", "Mark comment as resolved").option("--unresolved", "Mark comment as unresolved").option(
     "--mention <user>",
     'Prepend an @mention (ID, email, username, or "me"), repeatable. For a mid-sentence mention, put a <@userId> token in -m instead; bare @Name is not parsed.',
     collect,
@@ -8912,13 +9020,19 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (commentId, opts) => {
+        const message = resolveTextInput({
+          inline: opts.message,
+          file: opts.messageFile,
+          inlineFlag: "-m",
+          fileFlag: "--message-file"
+        });
         const config = loadConfig(getProfileName());
         let resolved;
         if (opts.resolved) resolved = true;
         if (opts.unresolved) resolved = false;
         const client = new ClickUpClient(config);
         const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
-        await editComment(config, commentId, opts.message, resolved, mentionIds);
+        await editComment(config, commentId, message, resolved, mentionIds);
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify({ success: true, commentId }, null, 2));
         } else {
@@ -8977,7 +9091,10 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     })
   );
-  program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--notify-all", "Notify all assignees").option(
+  program.command("reply <commentId>").description("Reply to a comment").option("-m, --message <text>", "Reply text").option(
+    "--message-file <path>",
+    'Read reply from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--notify-all", "Notify all assignees").option(
     "--mention <user>",
     'Prepend an @mention (ID, email, username, or "me"), repeatable. For a mid-sentence mention, put a <@userId> token in -m instead; bare @Name is not parsed.',
     collect,
@@ -8985,10 +9102,11 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (commentId, opts) => {
+        const message = resolveRequiredMessage(opts);
         const config = loadConfig(getProfileName());
         const client = new ClickUpClient(config);
         const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
-        await createReply(config, commentId, opts.message, opts.notifyAll, mentionIds);
+        await createReply(config, commentId, message, opts.notifyAll, mentionIds);
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify({ success: true, commentId }, null, 2));
         } else {
@@ -10516,15 +10634,19 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     })
   );
-  chatCmd.command("send <channelId>").description("Send a message to a channel").requiredOption("-m, --message <text>", "Message content (markdown supported)").option("--post", "Send as a post instead of a message").option("--title <title>", "Post title (requires --post)").option("--json", "Force JSON output even in terminal").action(
+  chatCmd.command("send <channelId>").description("Send a message to a channel").option("-m, --message <text>", "Message content (markdown supported)").option(
+    "--message-file <path>",
+    'Read message from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--post", "Send as a post instead of a message").option("--title <title>", "Post title (requires --post)").option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (channelId, opts) => {
+        const message = resolveRequiredMessage(opts);
         if (opts.title && !opts.post) {
           throw new Error("--title requires --post");
         }
         const config = loadConfig(getProfileName());
         const client = new ClickUpClient(config);
-        const result = await client.sendChatMessage(channelId, opts.message, {
+        const result = await client.sendChatMessage(channelId, message, {
           type: opts.post ? "post" : "message",
           postTitle: opts.title
         });
@@ -10664,17 +10786,23 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     })
   );
-  chatCmd.command("reply <messageId>").description("Reply to a message").requiredOption("-m, --message <text>", "Reply content (markdown supported)").option("--json", "Force JSON output even in terminal").action(
-    wrapAction(async (messageId, opts) => {
-      const config = loadConfig(getProfileName());
-      const client = new ClickUpClient(config);
-      const result = await client.createChatMessageReply(messageId, opts.message);
-      if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        console.log(`Reply sent (id: ${result.id})`);
+  chatCmd.command("reply <messageId>").description("Reply to a message").option("-m, --message <text>", "Reply content (markdown supported)").option(
+    "--message-file <path>",
+    'Read reply from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (messageId, opts) => {
+        const message = resolveRequiredMessage(opts);
+        const config = loadConfig(getProfileName());
+        const client = new ClickUpClient(config);
+        const result = await client.createChatMessageReply(messageId, message);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`Reply sent (id: ${result.id})`);
+        }
       }
-    })
+    )
   );
   chatCmd.command("replies <messageId>").description("List replies to a message").option("--limit <n>", "Max replies (default: 50)").option("--json", "Force JSON output even in terminal").action(
     wrapAction(async (messageId, opts) => {
@@ -10732,17 +10860,23 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     })
   );
-  chatCmd.command("message-update <messageId>").description("Edit a message").requiredOption("-m, --message <text>", "New message content").option("--json", "Force JSON output even in terminal").action(
-    wrapAction(async (messageId, opts) => {
-      const config = loadConfig(getProfileName());
-      const client = new ClickUpClient(config);
-      const result = await client.updateChatMessage(messageId, opts.message);
-      if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        console.log(`Message ${messageId} updated`);
+  chatCmd.command("message-update <messageId>").description("Edit a message").option("-m, --message <text>", "New message content").option(
+    "--message-file <path>",
+    'Read message from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (messageId, opts) => {
+        const message = resolveRequiredMessage(opts);
+        const config = loadConfig(getProfileName());
+        const client = new ClickUpClient(config);
+        const result = await client.updateChatMessage(messageId, message);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`Message ${messageId} updated`);
+        }
       }
-    })
+    )
   );
   chatCmd.command("message-delete <messageId>").description("Delete a message").option("--confirm", "Skip confirmation prompt").option("--json", "Force JSON output even in terminal").action(
     wrapAction(async (messageId, opts) => {
@@ -10817,7 +10951,10 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       printComments(comments, opts.json ?? false);
     })
   );
-  program.command("list-comment <listId>").description("Post a comment on a list").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option(
+  program.command("list-comment <listId>").description("Post a comment on a list").option("-m, --message <text>", "Comment text").option(
+    "--message-file <path>",
+    'Read comment from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--notify-all", "Notify all assignees").option(
     "--mention <user>",
     'Prepend an @mention (ID, email, username, or "me"), repeatable. For a mid-sentence mention, put a <@userId> token in -m instead; bare @Name is not parsed.',
     collect,
@@ -10825,13 +10962,14 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (listId, opts) => {
+        const message = resolveRequiredMessage(opts);
         const config = loadConfig(getProfileName());
         const client = new ClickUpClient(config);
         const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
         const result = await postListCommentCommand(
           config,
           listId,
-          opts.message,
+          message,
           opts.notifyAll,
           mentionIds
         );
@@ -10850,7 +10988,10 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       printComments(comments, opts.json ?? false);
     })
   );
-  program.command("view-comment <viewId>").description("Post a comment on a view").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option(
+  program.command("view-comment <viewId>").description("Post a comment on a view").option("-m, --message <text>", "Comment text").option(
+    "--message-file <path>",
+    'Read comment from a file ("-" for stdin); avoids shell quoting. Mutually exclusive with -m'
+  ).option("--notify-all", "Notify all assignees").option(
     "--mention <user>",
     'Prepend an @mention (ID, email, username, or "me"), repeatable. For a mid-sentence mention, put a <@userId> token in -m instead; bare @Name is not parsed.',
     collect,
@@ -10858,13 +10999,14 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (viewId, opts) => {
+        const message = resolveRequiredMessage(opts);
         const config = loadConfig(getProfileName());
         const client = new ClickUpClient(config);
         const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
         const result = await postViewCommentCommand(
           config,
           viewId,
-          opts.message,
+          message,
           opts.notifyAll,
           mentionIds
         );

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -3,11 +3,11 @@ name: clickup
 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, listing members, listing fields, duplicating tasks, bulk operations, goals, key results, saved filters, favorites.'
 ---
 
-# ClickUp CLI (`cup`) - skill version 1.38.2
+# ClickUp CLI (`cup`) - skill version 1.39.0
 
 Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, time tracking, custom fields, goals, docs, and project workflows.
 
-> **Version check:** Run `cup --version`. If your installed version is older than 1.38.2, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
+> **Version check:** Run `cup --version`. If your installed version is older than 1.39.0, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
 
 ## Install & Configure
 
@@ -163,13 +163,13 @@ All commands support `--help` for full flag details. All commands support `--jso
 
 | Command                                                                                                                                                                                                                                                                                                                                  | What it does                                                                                                                                                                                                                   |
 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `cup create -n name [-l listId\|sprint:current] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--start-date d] [--time-estimate t] [--assignee id\|me] [--group-assignee uuid\|@handle,...] [--tags t] [--custom-item-id n] [--template id] [--field "Name" val]`                                                    | Create task (`--list` accepts `sprint:current`, `--field` sets custom fields inline)                                                                                                                                           |
-| `cup update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d\|none] [--start-date d] [--time-estimate t] [--assignee id\|me] [--remove-assignee id\|me] [--group-assignee uuid\|@handle] [--remove-group-assignee uuid\|@handle] [--parent id] [--archive] [--unarchive] [--type type] [--field "Name" val]` | Update task fields (including custom fields and group assignees)                                                                                                                                                               |
-| `cup comment <id> -m text [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                               | Post comment (markdown auto-converted to rich text; `--mention` for real @mentions, repeatable)                                                                                                                                |
-| `cup comment-edit <commentId> -m text [--resolved] [--unresolved] [--mention user]`                                                                                                                                                                                                                                                      | Edit a comment (markdown auto-converted to rich text; `--mention` for real @mentions)                                                                                                                                          |
+| `cup create -n name [-l listId\|sprint:current] [-p parentId] [-d desc\|--description-file path] [-s status] [--priority p] [--due-date d] [--start-date d] [--time-estimate t] [--assignee id\|me] [--group-assignee uuid\|@handle,...] [--tags t] [--custom-item-id n] [--template id] [--field "Name" val]`                                                    | Create task (`--list` accepts `sprint:current`, `--field` sets custom fields inline; `--description-file` reads markdown from a file or `-` for stdin)                                                                                                                                           |
+| `cup update <id> [-n name] [-d desc\|--description-file path] [-s status] [--priority p] [--due-date d\|none] [--start-date d] [--time-estimate t] [--assignee id\|me] [--remove-assignee id\|me] [--group-assignee uuid\|@handle] [--remove-group-assignee uuid\|@handle] [--parent id] [--archive] [--unarchive] [--type type] [--field "Name" val]` | Update task fields (`--description-file` reads markdown from a file or `-` for stdin)                                                                                                                                                               |
+| `cup comment <id> -m text\|--message-file path [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                               | Post comment (markdown auto-converted to rich text; `--message-file` reads from a file or `-` for stdin; `--mention` for real @mentions, repeatable)                                                                                                                                |
+| `cup comment-edit <commentId> -m text\|--message-file path [--resolved] [--unresolved] [--mention user]`                                                                                                                                                                                                                                                      | Edit a comment (markdown auto-converted to rich text; `--mention` for real @mentions)                                                                                                                                          |
 | `cup comment-delete <commentId>` or `cup comment-delete --task <taskId> --mine [--match text]`                                                                                                                                                                                                                                           | Delete a comment by ID or delete one of your task comments                                                                                                                                                                     |
 | `cup replies <commentId>`                                                                                                                                                                                                                                                                                                                | List threaded replies                                                                                                                                                                                                          |
-| `cup reply <commentId> -m text [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                          | Reply to a comment (markdown auto-converted to rich text; `--mention` for real @mentions)                                                                                                                                      |
+| `cup reply <commentId> -m text\|--message-file path [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                          | Reply to a comment (markdown auto-converted to rich text; `--message-file` reads from a file or `-` for stdin; `--mention` for real @mentions)                                                                                                                                      |
 | `cup assign <id> [--to ids\|me] [--remove ids\|me] [--group uuid\|@handle,...] [--remove-group uuid\|@handle,...]`                                                                                                                                                                                                                       | Assign/unassign users and groups (all flags accept comma-separated values)                                                                                                                                                     |
 | `cup depend <id> [--on taskId] [--blocks taskId] [--remove]`                                                                                                                                                                                                                                                                             | Add/remove dependencies                                                                                                                                                                                                        |
 | `cup move <id> [--to listId\|sprint:current] [--remove listId]`                                                                                                                                                                                                                                                                          | Add/remove task from lists. **`--to` + `--remove` together changes the task's _home_ list** (uses v3 `home_list` endpoint with auto status mapping). `--to` alone adds multi-list membership. `--to` accepts `sprint:current`. |
@@ -292,7 +292,7 @@ All commands support `--help` for full flag details. All commands support `--jso
 | `cup delete`             | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone                                                                                                                                                                                                                                                                        |
 | Errors                   | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected                                                                                                                                                                                                                                                                        |
 | Rate limiting            | The client auto-retries on HTTP 429 and transient 5xx (502/503/504) with `Retry-After`-aware backoff (up to 3 retries). Retry warnings go to stderr. No action needed by callers                                                                                                                                                                   |
-| Description quoting      | Use `$'...'` quoting for `-d` / `-m` values containing backticks or newlines: `-d $'Use \`init()\` first.\n\n- Step 1'`. Heredocs and double quotes strip backticks                                                                                                                                                                                |
+| Multiline markdown (`-d` / `-m`) | **Best for agents:** use `--description-file <path>` / `--message-file <path>` (or `-` for stdin) to bypass shell quoting entirely — see the multiline example below. For inline multiline, use a **quoted heredoc** `"$(cat <<'EOF' … EOF)"` — it preserves backticks, newlines, and apostrophes. **Footgun:** never split a `$'...'` string with `'\''` for an apostrophe — the tail drops back to normal single quotes and `\n` becomes literal text (e.g. `$'…team'\''s…\n## Goals'` breaks). Plain double quotes execute backticks as commands. |
 | `--mention <user>`       | Real ClickUp @mention (notifies the user). Accepts ID, email, username, or `me`. Repeatable. Also: `<@userId>` inline token in `-m` for mid-sentence mentions. Bare `@Name` is NOT parsed (ambiguous). On `comment`, `reply`, `comment-edit`, `list-comment`, `view-comment`                                                                       |
 | Comment links            | In comment messages, bare URLs (`https://...`) and markdown links (`[text](url)`) both render as clickable links. Unfurled preview cards are not supported (web-UI only)                                                                                                                                                                           |
 
@@ -382,6 +382,34 @@ cup time log abc123def 2h -d "Code review"
 cup delete abc123def --confirm          # irreversible!
 ```
 
+### Multiline markdown descriptions and comments
+
+Agents produce structured markdown (headings, bullets, code, apostrophes). Shell quoting is the main failure point. Two robust patterns:
+
+```bash
+# 1. Best for agents: write markdown to a file, then reference it (no shell quoting at all)
+cup create -n "Improve onboarding" -l <listId> --description-file /tmp/desc.md
+cup update <taskId> --description-file /tmp/desc.md
+cup comment <taskId> --message-file /tmp/comment.md
+# "-" reads stdin:
+printf '## Notes\n\nTeam'\''s update with `code`.' | cup update <taskId> --description-file -
+
+# 2. Inline multiline: quoted heredoc preserves backticks, newlines, AND apostrophes
+cup create -n "Improve onboarding" -l <listId> -d "$(cat <<'EOF'
+## Overview
+
+Refresh the team's onboarding docs. Use `init()` first.
+
+## Goals
+
+- Goal one
+- Goal two
+EOF
+)"
+```
+
+Do **not** use `$'…team'\''s…\n\n## Goals'` — after the `'\''` apostrophe break the string is in normal single quotes, so `\n` is passed literally and headings/bullets render as `\n\n` text in ClickUp.
+
 ### Docs
 
 ```bash