@krodak/clickup-cli 1.32.0 → 1.33.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.32.0",
+  "version": "1.33.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -171,23 +171,23 @@ npx skills add https://github.com/krodak/clickup-cli
 
 Full CRUD for the core ClickUp workflow:
 
-| Area                 | Capabilities                                                                                                                                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ✅ **Tasks**         | Create, read, update, delete, duplicate, merge, search, subtasks, assign (users and groups), dependencies, links, multi-list, bulk operations (status, assign, due-date, tag, priority, field, move) |
-| 💬 **Comments**      | Post, edit, delete by ID or by task scope for your own comments, threaded replies, notify all, list and view comments                                                                                |
-| 🗨️ **Chat**          | List channels, send messages, replies, reactions, channel management                                                                                                                                 |
-| 📄 **Docs**          | List, read, create, edit, delete (v3 API)                                                                                                                                                            |
-| ⏱️ **Time Tracking** | Start/stop timer, log entries, list/update/delete history, per-user time estimates                                                                                                                   |
-| ☑️ **Checklists**    | View, create, delete, add/edit/delete items                                                                                                                                                          |
-| 🔧 **Custom Fields** | List, create, set, remove values (text, number, dropdown, labels, date, checkbox, url, email, rating, progress, relationship, people)                                                                |
-| 🏷️ **Tags**          | Add/remove on tasks, space-level create/update/delete                                                                                                                                                |
-| 🎯 **Goals & OKRs**  | Goals CRUD, key results CRUD                                                                                                                                                                         |
-| 🏃 **Sprints**       | Auto-detect active sprint, `sprint:current` pseudo-ID for move/create, flexible date parsing, config override, favorite sprint folders                                                               |
-| ⭐ **Favorites**     | Local favorites for quick access to sprint folders, spaces, lists, folders, views, tasks                                                                                                             |
-| 👁️ **Views**         | List, get, create, update, delete views on lists                                                                                                                                                     |
-| 🔗 **Webhooks**      | List, create, update, delete webhooks; scope to space, folder, list, or task                                                                                                                         |
-| 🏢 **Workspace**     | Spaces, folders, lists (full CRUD + rename + from template), members, user groups, task types, templates, plan, shared hierarchy                                                                     |
-| 📎 **Attachments**   | Upload files to tasks, list task attachments, shown in detail views                                                                                                                                  |
+| Area                 | Capabilities                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ✅ **Tasks**         | Create, read, update, delete, duplicate, merge, search, subtasks, assign (users and groups), dependencies, links, multi-list, bulk operations (status, assign, due-date, tag, priority, field, move)          |
+| 💬 **Comments**      | Post, edit, delete by ID or by task scope for your own comments, threaded replies, notify all, real @mentions (flag or inline `<@id>` token, notifies the user), clickable rich links, list and view comments |
+| 🗨️ **Chat**          | List channels, send messages, replies, reactions, channel management                                                                                                                                          |
+| 📄 **Docs**          | List, read, create, edit, delete (v3 API)                                                                                                                                                                     |
+| ⏱️ **Time Tracking** | Start/stop timer, log entries, list/update/delete history, per-user time estimates                                                                                                                            |
+| ☑️ **Checklists**    | View, create, delete, add/edit/delete items                                                                                                                                                                   |
+| 🔧 **Custom Fields** | List, create, set, remove values (text, number, dropdown, labels, date, checkbox, url, email, rating, progress, relationship, people)                                                                         |
+| 🏷️ **Tags**          | Add/remove on tasks, space-level create/update/delete                                                                                                                                                         |
+| 🎯 **Goals & OKRs**  | Goals CRUD, key results CRUD                                                                                                                                                                                  |
+| 🏃 **Sprints**       | Auto-detect active sprint, `sprint:current` pseudo-ID for move/create, flexible date parsing, config override, favorite sprint folders                                                                        |
+| ⭐ **Favorites**     | Local favorites for quick access to sprint folders, spaces, lists, folders, views, tasks                                                                                                                      |
+| 👁️ **Views**         | List, get, create, update, delete views on lists                                                                                                                                                              |
+| 🔗 **Webhooks**      | List, create, update, delete webhooks; scope to space, folder, list, or task                                                                                                                                  |
+| 🏢 **Workspace**     | Spaces, folders, lists (full CRUD + rename + from template), members, user groups, task types, templates, plan, shared hierarchy                                                                              |
+| 📎 **Attachments**   | Upload files to tasks, list task attachments, shown in detail views                                                                                                                                           |
 
 [Full API coverage details](docs/api-coverage.md) | [Command reference](docs/commands.md)
 

package/dist/index.js

@@ -1066,8 +1066,8 @@ var ClickUpClient = class {
     const data = await this.request(`/list/${listId}/comment`);
     return readCollectionField(data, "comments", "list comments");
   }
-  async postListComment(listId, commentText, notifyAll) {
-    const body = { comment_text: commentText };
+  async postListComment(listId, commentText, notifyAll, richBlocks) {
+    const body = richBlocks ? { comment: richBlocks } : { comment_text: commentText };
     if (notifyAll) body.notify_all = true;
     return this.request(`/list/${listId}/comment`, {
       method: "POST",
@@ -1078,8 +1078,8 @@ var ClickUpClient = class {
     const data = await this.request(`/view/${viewId}/comment`);
     return readCollectionField(data, "comments", "view comments");
   }
-  async postViewComment(viewId, commentText, notifyAll) {
-    const body = { comment_text: commentText };
+  async postViewComment(viewId, commentText, notifyAll, richBlocks) {
+    const body = richBlocks ? { comment: richBlocks } : { comment_text: commentText };
     if (notifyAll) body.notify_all = true;
     return this.request(`/view/${viewId}/comment`, {
       method: "POST",
@@ -2865,7 +2865,9 @@ function processInlineFormatting(text, lineAttrs) {
       { type: "bold", re: /\*{2}([^*]+)\*{2}/ },
       { type: "italic", re: /(?<!\*)\*(?!\*)([^*]+)(?<!\*)\*(?!\*)/ },
       { type: "strike", re: /~~([^~]+)~~/ },
-      { type: "link", re: /\[([^\]]+)\]\(([^)]+)\)/ }
+      { type: "mention", re: /<@(\d+)>/ },
+      { type: "link", re: /\[([^\]]+)\]\(([^)]+)\)/ },
+      { type: "autolink", re: /(?<![([])(https?:\/\/[^\s<>]+)/ }
     ];
     for (const { type, re } of patterns) {
       const m = re.exec(remaining);
@@ -2913,6 +2915,15 @@ function processInlineFormatting(text, lineAttrs) {
           attributes: { ...lineAttrs, link: matchResult[2] }
         });
         break;
+      case "autolink":
+        blocks.push({
+          text: innerText,
+          attributes: { ...lineAttrs, link: innerText }
+        });
+        break;
+      case "mention":
+        blocks.push({ type: "tag", user: { id: Number(innerText) } });
+        break;
     }
     remaining = remaining.slice(earliestIndex + matchResult[0].length);
   }
@@ -3015,10 +3026,42 @@ function markdownToCommentBlocks(markdown) {
 }
 
 // src/commands/comment.ts
-async function postComment(config, taskId, text, notifyAll) {
+async function resolveMemberId(client, teamId, value) {
+  if (/^\d+$/.test(value)) return Number(value);
+  if (value === "me") return (await client.getMe()).id;
+  const members = await client.getWorkspaceMembers(teamId);
+  const match = members.find(
+    (m) => m.email?.toLowerCase() === value.toLowerCase() || m.username?.toLowerCase() === value.toLowerCase()
+  );
+  if (match) return match.id;
+  const available = members.map((m) => `${m.username} (${m.email})`).join(", ");
+  throw new Error(`Member "${value}" not found. Available: ${available}`);
+}
+function createCachedMemberResolver(client, teamId) {
+  let membersCache = null;
+  const cachingClient = {
+    getMe: () => client.getMe(),
+    getWorkspaceMembers: async () => {
+      if (membersCache === null) membersCache = await client.getWorkspaceMembers(teamId);
+      return membersCache;
+    }
+  };
+  return (value) => resolveMemberId(cachingClient, teamId, value);
+}
+function buildCommentBlocks(message, mentionIds) {
+  const messageBlocks = markdownToCommentBlocks(message);
+  if (mentionIds.length === 0) return messageBlocks;
+  const mentionBlocks = [];
+  for (const id of mentionIds) {
+    mentionBlocks.push({ type: "tag", user: { id } });
+    mentionBlocks.push({ text: " " });
+  }
+  return [...mentionBlocks, ...messageBlocks];
+}
+async function postComment(config, taskId, text, notifyAll, mentionIds) {
   if (!text.trim()) throw new Error("Comment text cannot be empty");
   const client = new ClickUpClient(config);
-  const blocks = markdownToCommentBlocks(text);
+  const blocks = buildCommentBlocks(text, mentionIds ?? []);
   return client.postComment(taskId, text, notifyAll, blocks);
 }
 
@@ -3832,7 +3875,7 @@ var commandMetadata = [
   {
     name: "comment",
     description: "Post a comment on a task",
-    flags: ["-m", "--message", "--notify-all", "--json"],
+    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
     quickReference: [
       { section: "write", usage: "comment <taskId>", description: "Post a comment on a task" }
     ]
@@ -3840,7 +3883,7 @@ var commandMetadata = [
   {
     name: "comment-edit",
     description: "Edit an existing comment",
-    flags: ["-m", "--message", "--resolved", "--unresolved", "--json"],
+    flags: ["-m", "--message", "--resolved", "--unresolved", "--mention", "--json"],
     quickReference: [
       {
         section: "write",
@@ -3884,7 +3927,7 @@ var commandMetadata = [
   {
     name: "reply",
     description: "Reply to a comment",
-    flags: ["-m", "--message", "--notify-all", "--json"],
+    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
     quickReference: [
       { section: "write", usage: "reply <commentId>", description: "Reply to a comment" }
     ]
@@ -4689,7 +4732,7 @@ var commandMetadata = [
   {
     name: "list-comment",
     description: "Post a comment on a list",
-    flags: ["-m", "--message", "--notify-all", "--json"],
+    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
     quickReference: [
       {
         section: "write",
@@ -4713,7 +4756,7 @@ var commandMetadata = [
   {
     name: "view-comment",
     description: "Post a comment on a view",
-    flags: ["-m", "--message", "--notify-all", "--json"],
+    flags: ["-m", "--message", "--notify-all", "--mention", "--json"],
     quickReference: [
       {
         section: "write",
@@ -5156,6 +5199,7 @@ ${renderZshTopLevelCommands(name)}
             '1:task_id:' \\
             '(-m --message)'{-m,--message}'[Comment text]:text:' \\
             '--notify-all[Notify all assignees]' \\
+            '--mention[Mention a user (ID, email, username, or me)]:user:' \\
             '--json[Force JSON output]'
           ;;
         comments)
@@ -5390,6 +5434,7 @@ ${renderZshTopLevelCommands(name)}
             '(-m --message)'{-m,--message}'[New comment text]:text:' \\
             '--resolved[Mark comment as resolved]' \\
             '--unresolved[Mark comment as unresolved]' \\
+            '--mention[Mention a user (ID, email, username, or me)]:user:' \\
             '--json[Force JSON output]'
           ;;
         comment-delete)
@@ -5410,6 +5455,7 @@ ${renderZshTopLevelCommands(name)}
             '1:comment_id:' \\
             '(-m --message)'{-m,--message}'[Reply text]:text:' \\
             '--notify-all[Notify all assignees]' \\
+            '--mention[Mention a user (ID, email, username, or me)]:user:' \\
             '--json[Force JSON output]'
           ;;
         link)
@@ -6780,13 +6826,13 @@ function formatChecklistsMarkdown(checklists) {
 }
 
 // src/commands/comment-edit.ts
-async function editComment(config, commentId, text, resolved) {
+async function editComment(config, commentId, text, resolved, mentionIds) {
   if (text === void 0 && resolved === void 0) {
     throw new Error("Provide at least one of: --message, --resolved, --unresolved");
   }
   if (text !== void 0 && !text.trim()) throw new Error("Comment text cannot be empty");
   const client = new ClickUpClient(config);
-  const blocks = text !== void 0 ? markdownToCommentBlocks(text) : void 0;
+  const blocks = text !== void 0 ? buildCommentBlocks(text, mentionIds ?? []) : void 0;
   await client.updateComment(commentId, text ?? "", resolved, blocks);
 }
 
@@ -6827,10 +6873,10 @@ async function getReplies(config, commentId) {
   const client = new ClickUpClient(config);
   return client.getThreadedComments(commentId);
 }
-async function createReply(config, commentId, text, notifyAll) {
+async function createReply(config, commentId, text, notifyAll, mentionIds) {
   if (!text.trim()) throw new Error("Reply text cannot be empty");
   const client = new ClickUpClient(config);
-  const blocks = markdownToCommentBlocks(text);
+  const blocks = buildCommentBlocks(text, mentionIds ?? []);
   await client.createThreadedComment(commentId, text, notifyAll, blocks);
 }
 function formatReplies(replies) {
@@ -8272,10 +8318,11 @@ async function fetchListComments(config, listId) {
     text: c.comment_text
   }));
 }
-async function postListCommentCommand(config, listId, text, notifyAll) {
+async function postListCommentCommand(config, listId, text, notifyAll, mentionIds) {
   if (!text.trim()) throw new Error("Comment text cannot be empty");
   const client = new ClickUpClient(config);
-  return client.postListComment(listId, text, notifyAll);
+  const blocks = buildCommentBlocks(text, mentionIds ?? []);
+  return client.postListComment(listId, text, notifyAll, blocks);
 }
 
 // src/commands/view-comments.ts
@@ -8289,10 +8336,11 @@ async function fetchViewComments(config, viewId) {
     text: c.comment_text
   }));
 }
-async function postViewCommentCommand(config, viewId, text, notifyAll) {
+async function postViewCommentCommand(config, viewId, text, notifyAll, mentionIds) {
   if (!text.trim()) throw new Error("Comment text cannot be empty");
   const client = new ClickUpClient(config);
-  return client.postViewComment(viewId, text, notifyAll);
+  const blocks = buildCommentBlocks(text, mentionIds ?? []);
+  return client.postViewComment(viewId, text, notifyAll, blocks);
 }
 
 // src/index.ts
@@ -8316,6 +8364,18 @@ function parseOptionalNumberOption(value, optionName) {
 function splitCommaList(value) {
   return value.split(",").map((v) => v.trim()).filter((v) => v.length > 0);
 }
+function collect(value, previous) {
+  return [...previous, value];
+}
+async function resolveMentions(client, teamId, mentions) {
+  if (mentions.length === 0) return [];
+  const resolve2 = createCachedMemberResolver(client, teamId);
+  const ids = [];
+  for (const mention of mentions) {
+    ids.push(await resolve2(mention));
+  }
+  return ids;
+}
 function createCachedGroupResolver(client) {
   let cache = null;
   const cachingClient = {
@@ -8606,11 +8666,18 @@ 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("--json", "Force JSON output even in terminal").action(
+  program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option(
+    "--mention <user>",
+    'Mention a user (ID, email, username, or "me"). Repeatable.',
+    collect,
+    []
+  ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (taskId, opts) => {
         const config = loadConfig(getProfileName());
-        const result = await postComment(config, taskId, opts.message, opts.notifyAll);
+        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);
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify(result, null, 2));
         } else {
@@ -8626,14 +8693,21 @@ 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("--json", "Force JSON output even in terminal").action(
+  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(
+    "--mention <user>",
+    'Mention a user (ID, email, username, or "me"). Repeatable.',
+    collect,
+    []
+  ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (commentId, opts) => {
         const config = loadConfig(getProfileName());
         let resolved;
         if (opts.resolved) resolved = true;
         if (opts.unresolved) resolved = false;
-        await editComment(config, commentId, opts.message, resolved);
+        const client = new ClickUpClient(config);
+        const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
+        await editComment(config, commentId, opts.message, resolved, mentionIds);
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify({ success: true, commentId }, null, 2));
         } else {
@@ -8692,11 +8766,18 @@ 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("--json", "Force JSON output even in terminal").action(
+  program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--notify-all", "Notify all assignees").option(
+    "--mention <user>",
+    'Mention a user (ID, email, username, or "me"). Repeatable.',
+    collect,
+    []
+  ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (commentId, opts) => {
         const config = loadConfig(getProfileName());
-        await createReply(config, commentId, opts.message, opts.notifyAll);
+        const client = new ClickUpClient(config);
+        const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
+        await createReply(config, commentId, opts.message, opts.notifyAll, mentionIds);
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify({ success: true, commentId }, null, 2));
         } else {
@@ -10497,11 +10578,24 @@ 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("--json", "Force JSON output even in terminal").action(
+  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(
+    "--mention <user>",
+    'Mention a user (ID, email, username, or "me"). Repeatable.',
+    collect,
+    []
+  ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (listId, opts) => {
         const config = loadConfig(getProfileName());
-        const result = await postListCommentCommand(config, listId, opts.message, opts.notifyAll);
+        const client = new ClickUpClient(config);
+        const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
+        const result = await postListCommentCommand(
+          config,
+          listId,
+          opts.message,
+          opts.notifyAll,
+          mentionIds
+        );
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify(result, null, 2));
         } else {
@@ -10517,11 +10611,24 @@ 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("--json", "Force JSON output even in terminal").action(
+  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(
+    "--mention <user>",
+    'Mention a user (ID, email, username, or "me"). Repeatable.',
+    collect,
+    []
+  ).option("--json", "Force JSON output even in terminal").action(
     wrapAction(
       async (viewId, opts) => {
         const config = loadConfig(getProfileName());
-        const result = await postViewCommentCommand(config, viewId, opts.message, opts.notifyAll);
+        const client = new ClickUpClient(config);
+        const mentionIds = await resolveMentions(client, config.teamId, opts.mention);
+        const result = await postViewCommentCommand(
+          config,
+          viewId,
+          opts.message,
+          opts.notifyAll,
+          mentionIds
+        );
         if (shouldOutputJson(opts.json ?? false)) {
           console.log(JSON.stringify(result, null, 2));
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krodak/clickup-cli",
-  "version": "1.32.0",
+  "version": "1.33.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.32.0
+# ClickUp CLI (`cup`) - skill version 1.33.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.32.0, 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.33.0, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
 
 ## Install & Configure
 
@@ -163,11 +163,11 @@ All commands support `--help` for full flag details. All commands support `--jso
 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `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] [--detach] [--archive] [--unarchive] [--type type] [--field "Name" val]` | Update task fields (including custom fields and group assignees)                                                                                                                                                               |
-| `cup comment <id> -m text [--notify-all]`                                                                                                                                                                                                                                                                                                | Post comment (markdown auto-converted to rich text)                                                                                                                                                                            |
-| `cup comment-edit <commentId> -m text [--resolved] [--unresolved]`                                                                                                                                                                                                                                                                       | Edit a comment (markdown auto-converted to rich text)                                                                                                                                                                          |
+| `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 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]`                                                                                                                                                                                                                                                                                           | Reply to a comment (markdown auto-converted to rich text)                                                                                                                                                                      |
+| `cup reply <commentId> -m text [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                          | Reply to a comment (markdown auto-converted to rich text; `--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`. |
@@ -225,8 +225,8 @@ All commands support `--help` for full flag details. All commands support `--jso
 | `cup view-create <listId> <name> -t <type> [--group-by field]`                                                                                                                                                                                                                                                                           | Create a view on a list                                                                                                                                                                                                        |
 | `cup view-update <viewId> [-n name] [--group-by field]`                                                                                                                                                                                                                                                                                  | Update a view                                                                                                                                                                                                                  |
 | `cup view-delete <viewId> [--confirm]`                                                                                                                                                                                                                                                                                                   | Delete a view (DESTRUCTIVE)                                                                                                                                                                                                    |
-| `cup list-comment <listId> -m text [--notify-all]`                                                                                                                                                                                                                                                                                       | Post comment on a list                                                                                                                                                                                                         |
-| `cup view-comment <viewId> -m text [--notify-all]`                                                                                                                                                                                                                                                                                       | Post comment on a view                                                                                                                                                                                                         |
+| `cup list-comment <listId> -m text [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                      | Post comment on a list (`--mention` for real @mentions)                                                                                                                                                                        |
+| `cup view-comment <viewId> -m text [--notify-all] [--mention user]`                                                                                                                                                                                                                                                                      | Post comment on a view (`--mention` for real @mentions)                                                                                                                                                                        |
 | `cup webhook create --url <url> --events <events> [--space\|--folder\|--list\|--task <id>]`                                                                                                                                                                                                                                              | Create a webhook                                                                                                                                                                                                               |
 | `cup webhook update <webhookId> [--url u] [--events e] [--status s]`                                                                                                                                                                                                                                                                     | Update a webhook                                                                                                                                                                                                               |
 | `cup webhook delete <webhookId> [--confirm]`                                                                                                                                                                                                                                                                                             | Delete a webhook (DESTRUCTIVE)                                                                                                                                                                                                 |
@@ -289,6 +289,8 @@ 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                                                                                                                                                                                                                                                                        |
 | 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                                                                                                                                                                                |
+| `--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)                                                                                                                                                                           |
 
 > **Note:** `cup search`, `cup tasks`, `cup overdue`, and `cup assigned` default to tasks assigned to the current user. Use `--all` to include tasks assigned to others. This matters when searching for parent initiatives or team-wide items.