@krodak/clickup-cli 1.21.0 → 1.22.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.21.0",
+  "version": "1.22.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/dist/index.js

@@ -286,8 +286,10 @@ var ClickUpClient = class {
       body: JSON.stringify({ name, multiple_assignees: true })
     });
   }
-  async getSpaces(teamId) {
-    const data = await this.request(`/team/${teamId}/space?archived=false`);
+  async getSpaces(teamId, archived = false) {
+    const data = await this.request(
+      `/team/${teamId}/space?archived=${archived ? "true" : "false"}`
+    );
     return readCollectionField(data, "spaces", "spaces");
   }
   async getCustomTaskTypes(teamId) {
@@ -324,18 +326,22 @@ var ClickUpClient = class {
       body: JSON.stringify({ name })
     });
   }
-  async getLists(spaceId) {
-    const data = await this.request(`/space/${spaceId}/list?archived=false`);
+  async getLists(spaceId, archived = false) {
+    const data = await this.request(
+      `/space/${spaceId}/list?archived=${archived ? "true" : "false"}`
+    );
     return readCollectionField(data, "lists", "space lists");
   }
-  async getFolders(spaceId) {
+  async getFolders(spaceId, archived = false) {
     const data = await this.request(
-      `/space/${spaceId}/folder?archived=false`
+      `/space/${spaceId}/folder?archived=${archived ? "true" : "false"}`
     );
     return readCollectionField(data, "folders", "space folders");
   }
-  async getFolderLists(folderId) {
-    const data = await this.request(`/folder/${folderId}/list?archived=false`);
+  async getFolderLists(folderId, archived = false) {
+    const data = await this.request(
+      `/folder/${folderId}/list?archived=${archived ? "true" : "false"}`
+    );
     return readCollectionField(data, "lists", "folder lists");
   }
   async getListViews(listId) {
@@ -1945,10 +1951,16 @@ function buildUpdatePayload(opts, timezone) {
   }
   if (opts.archive) payload.archived = true;
   if (opts.unarchive) payload.archived = false;
+  if (opts.type !== void 0) {
+    const num = Number(opts.type);
+    if (Number.isInteger(num) && num >= 0) {
+      payload.custom_item_id = num;
+    }
+  }
   return payload;
 }
 function hasUpdateFields(options) {
-  return options.name !== void 0 || options.description !== void 0 || options.markdown_content !== void 0 || options.status !== void 0 || options.priority !== void 0 || options.due_date !== void 0 || options.start_date !== void 0 || options.time_estimate !== void 0 || options.assignees !== void 0 || options.parent !== void 0 || options.archived !== void 0;
+  return options.name !== void 0 || options.description !== void 0 || options.markdown_content !== void 0 || options.status !== void 0 || options.priority !== void 0 || options.due_date !== void 0 || options.start_date !== void 0 || options.time_estimate !== void 0 || options.assignees !== void 0 || options.parent !== void 0 || options.archived !== void 0 || options.custom_item_id !== void 0;
 }
 async function resolveStatus(client, taskId, statusInput) {
   const task = await client.getTask(taskId);
@@ -1964,16 +1976,29 @@ async function resolveStatus(client, taskId, statusInput) {
   }
   return matched;
 }
-async function updateTask(config, taskId, options) {
-  if (!hasUpdateFields(options))
+async function resolveTaskType2(client, teamId, typeInput) {
+  const types = await client.getCustomTaskTypes(teamId);
+  const lower = typeInput.toLowerCase();
+  const match = types.find((t) => t.name.toLowerCase() === lower);
+  if (!match) {
+    const available = types.map((t) => `${t.name} (${String(t.id)})`).join(", ");
+    throw new Error(`No matching task type for "${typeInput}". Available: ${available}`);
+  }
+  return match.id;
+}
+async function updateTask(config, taskId, options, typeInput) {
+  if (!hasUpdateFields(options) && typeInput === void 0)
     throw new Error(
-      "Provide at least one of: --name, --description, --status, --priority, --due-date, --start-date, --time-estimate, --assignee, --remove-assignee, --parent, --detach, --archive, --unarchive"
+      "Provide at least one of: --name, --description, --status, --priority, --due-date, --start-date, --time-estimate, --assignee, --remove-assignee, --parent, --detach, --archive, --unarchive, --type"
     );
   const client = new ClickUpClient(config);
   const resolved = { ...options };
   if (resolved.status !== void 0) {
     resolved.status = await resolveStatus(client, taskId, resolved.status);
   }
+  if (resolved.custom_item_id === void 0 && typeInput !== void 0) {
+    resolved.custom_item_id = await resolveTaskType2(client, config.teamId, typeInput);
+  }
   const task = await client.updateTask(taskId, resolved);
   return { id: task.id, name: task.name };
 }
@@ -2502,12 +2527,14 @@ function printComments(comments, forceJson) {
 async function fetchLists(config, spaceId, opts = {}) {
   const client = new ClickUpClient(config);
   const results = [];
-  const folderlessLists = await client.getLists(spaceId);
+  const folderlessLists = await client.getLists(spaceId, opts.archived);
   for (const list of folderlessLists) {
     results.push({ id: list.id, name: list.name, folder: "(none)" });
   }
-  const folders = await client.getFolders(spaceId);
-  const folderListArrays = await Promise.all(folders.map((f) => client.getFolderLists(f.id)));
+  const folders = await client.getFolders(spaceId, opts.archived);
+  const folderListArrays = await Promise.all(
+    folders.map((f) => client.getFolderLists(f.id, opts.archived))
+  );
   for (let i = 0; i < folders.length; i++) {
     const folder = folders[i];
     for (const list of folderListArrays[i]) {
@@ -2637,7 +2664,7 @@ async function printInbox(tasks, forceJson, config) {
 // src/commands/spaces.ts
 async function listSpaces(config, opts) {
   const client = new ClickUpClient(config);
-  let spaces = await client.getSpaces(config.teamId);
+  let spaces = await client.getSpaces(config.teamId, opts.archived);
   if (opts.name) {
     const lower = opts.name.toLowerCase();
     spaces = spaces.filter((s) => s.name.toLowerCase().includes(lower));
@@ -2949,6 +2976,9 @@ function configPath2() {
 }
 
 // src/commands/assign.ts
+function parseIdList(value) {
+  return value.split(",").map((v) => v.trim()).filter((v) => v.length > 0);
+}
 async function assignTask(config, taskId, opts) {
   if (!opts.to && !opts.remove) {
     throw new Error("Provide at least one of: --to, --remove");
@@ -2957,10 +2987,14 @@ async function assignTask(config, taskId, opts) {
   const add = [];
   const rem = [];
   if (opts.to) {
-    add.push(await resolveAssigneeId(client, opts.to));
+    for (const value of parseIdList(opts.to)) {
+      add.push(await resolveAssigneeId(client, value));
+    }
   }
   if (opts.remove) {
-    rem.push(await resolveAssigneeId(client, opts.remove));
+    for (const value of parseIdList(opts.remove)) {
+      rem.push(await resolveAssigneeId(client, value));
+    }
   }
   return client.updateTask(taskId, {
     assignees: {
@@ -3164,6 +3198,7 @@ var commandMetadata = [
       "--detach",
       "--archive",
       "--unarchive",
+      "--type",
       "--field",
       "--json"
     ],
@@ -3294,7 +3329,7 @@ var commandMetadata = [
   {
     name: "lists",
     description: "List all lists in a space (including lists inside folders)",
-    flags: ["--name", "--json"],
+    flags: ["--name", "--archived", "--json"],
     quickReference: [
       { section: "read", usage: "lists <spaceId>", description: "List all lists in a space" }
     ]
@@ -3302,7 +3337,7 @@ var commandMetadata = [
   {
     name: "spaces",
     description: "List spaces in your workspace",
-    flags: ["--name", "--my", "--json"],
+    flags: ["--name", "--my", "--archived", "--json"],
     quickReference: [{ section: "read", usage: "spaces", description: "List spaces in workspace" }]
   },
   {
@@ -3627,7 +3662,7 @@ var commandMetadata = [
   {
     name: "folders",
     description: "List folders in a space (with their lists)",
-    flags: ["--name", "--json"],
+    flags: ["--name", "--archived", "--json"],
     quickReference: [
       { section: "read", usage: "folders <spaceId>", description: "List folders in a space" }
     ]
@@ -3733,6 +3768,16 @@ var commandMetadata = [
         section: "write",
         usage: "bulk tag <tagName> <taskIds...>",
         description: "Bulk add/remove tag"
+      },
+      {
+        section: "write",
+        usage: "bulk priority <taskIds...>",
+        description: "Bulk set priority on tasks"
+      },
+      {
+        section: "write",
+        usage: "bulk field <taskIds...>",
+        description: "Bulk set a custom field value on tasks"
       }
     ]
   },
@@ -5219,7 +5264,11 @@ var SUPPORTED_TYPES = /* @__PURE__ */ new Set([
   "checkbox",
   "date",
   "url",
-  "email"
+  "email",
+  "emoji",
+  "manual_progress",
+  "tasks",
+  "users"
 ]);
 function findFieldByName(fields, name) {
   const lower = name.toLowerCase();
@@ -5284,6 +5333,30 @@ function parseFieldValue(field, rawValue) {
         throw new Error(`Value "${rawValue}" is not a valid date (use YYYY-MM-DD)`);
       return ms;
     }
+    case "emoji": {
+      const n = Number(rawValue);
+      if (!Number.isFinite(n) || n < 0 || n > 5) {
+        throw new Error("Rating value must be a number between 0 and 5");
+      }
+      return n;
+    }
+    case "manual_progress": {
+      const n = Number(rawValue);
+      if (!Number.isFinite(n) || n < 0 || n > 100) {
+        throw new Error("Progress value must be a number between 0 and 100");
+      }
+      return { current: n };
+    }
+    case "tasks": {
+      const ids = rawValue.split(",").map((s) => s.trim()).filter(Boolean);
+      if (ids.length === 0) throw new Error("Provide at least one task ID (comma-separated)");
+      return { add: ids };
+    }
+    case "users": {
+      const ids = rawValue.split(",").map((s) => s.trim()).filter(Boolean);
+      if (ids.length === 0) throw new Error("Provide at least one user ID (comma-separated)");
+      return { add: ids.map(Number) };
+    }
     default:
       return rawValue;
   }
@@ -5668,9 +5741,9 @@ async function deleteDocPage(config, docId, pageId) {
 
 // src/commands/folders.ts
 import chalk12 from "chalk";
-async function listFolders(config, spaceId, nameFilter) {
+async function listFolders(config, spaceId, nameFilter, archived) {
   const client = new ClickUpClient(config);
-  const folders = await client.getFolders(spaceId);
+  const folders = await client.getFolders(spaceId, archived);
   let filtered = folders;
   if (nameFilter) {
     const lower = nameFilter.toLowerCase();
@@ -5932,66 +6005,98 @@ async function duplicateTask(config, taskId) {
 }
 
 // src/commands/bulk.ts
-async function bulkUpdateStatus(config, taskIds, status) {
-  const client = new ClickUpClient(config);
+var BULK_CONCURRENCY = 5;
+async function runInBatches(items, concurrency, fn) {
+  const results = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency);
+    const batchResults = await Promise.allSettled(batch.map(fn));
+    batchResults.forEach((res, idx) => {
+      const item = batch[idx];
+      if (res.status === "fulfilled") {
+        results.push({ item, result: res.value });
+      } else {
+        results.push({
+          item,
+          error: res.reason instanceof Error ? res.reason : new Error(String(res.reason))
+        });
+      }
+    });
+  }
+  return results;
+}
+function toBulkResult(outcomes) {
   const failed = [];
-  for (const id of taskIds) {
-    try {
-      await client.updateTask(id, { status });
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      failed.push({ id, reason });
+  for (const outcome of outcomes) {
+    if (outcome.error) {
+      failed.push({ id: outcome.item, reason: outcome.error.message });
     }
   }
-  return { updated: taskIds.length - failed.length, failed };
+  return { updated: outcomes.length - failed.length, failed };
+}
+async function bulkUpdateStatus(config, taskIds, status) {
+  const client = new ClickUpClient(config);
+  const outcomes = await runInBatches(
+    taskIds,
+    BULK_CONCURRENCY,
+    (id) => client.updateTask(id, { status })
+  );
+  return toBulkResult(outcomes);
 }
 async function bulkAssign(config, userIdOrMe, taskIds, action) {
   const client = new ClickUpClient(config);
   const numericId = await resolveAssigneeId(client, userIdOrMe);
-  const failed = [];
-  for (const id of taskIds) {
-    try {
-      await client.updateTask(id, {
-        assignees: action === "add" ? { add: [numericId] } : { rem: [numericId] }
-      });
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      failed.push({ id, reason });
-    }
-  }
-  return { updated: taskIds.length - failed.length, failed };
+  const payload = action === "add" ? { assignees: { add: [numericId] } } : { assignees: { rem: [numericId] } };
+  const outcomes = await runInBatches(
+    taskIds,
+    BULK_CONCURRENCY,
+    (id) => client.updateTask(id, payload)
+  );
+  return toBulkResult(outcomes);
 }
 async function bulkDueDate(config, date, taskIds) {
   const client = new ClickUpClient(config);
   const timezone = await client.getUserTimezone();
   const payload = date === "none" || date === "clear" ? { due_date: null } : { due_date: parseDueDate(date, timezone), due_date_time: false };
-  const failed = [];
-  for (const id of taskIds) {
-    try {
-      await client.updateTask(id, payload);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      failed.push({ id, reason });
-    }
-  }
-  return { updated: taskIds.length - failed.length, failed };
+  const outcomes = await runInBatches(
+    taskIds,
+    BULK_CONCURRENCY,
+    (id) => client.updateTask(id, payload)
+  );
+  return toBulkResult(outcomes);
 }
 async function bulkTag(config, tagName, taskIds, action) {
   const client = new ClickUpClient(config);
-  const failed = [];
-  for (const id of taskIds) {
-    try {
-      if (action === "add") {
-        await client.addTagToTask(id, tagName);
-      } else {
-        await client.removeTagFromTask(id, tagName);
-      }
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      failed.push({ id, reason });
-    }
-  }
-  return { updated: taskIds.length - failed.length, failed };
+  const outcomes = await runInBatches(
+    taskIds,
+    BULK_CONCURRENCY,
+    (id) => action === "add" ? client.addTagToTask(id, tagName) : client.removeTagFromTask(id, tagName)
+  );
+  return toBulkResult(outcomes);
+}
+async function bulkPriority(config, priorityValue, taskIds) {
+  const priority = parsePriority(priorityValue);
+  const client = new ClickUpClient(config);
+  const outcomes = await runInBatches(
+    taskIds,
+    BULK_CONCURRENCY,
+    (id) => client.updateTask(id, { priority })
+  );
+  return toBulkResult(outcomes);
+}
+async function bulkField(config, fieldName, rawValue, taskIds) {
+  if (taskIds.length === 0) return { updated: 0, failed: [] };
+  const client = new ClickUpClient(config);
+  const firstTask = await client.getTask(taskIds[0]);
+  const fields = firstTask.custom_fields ?? [];
+  const field = findFieldByName(fields, fieldName);
+  const parsed = parseFieldValue(field, rawValue);
+  const outcomes = await runInBatches(
+    taskIds,
+    BULK_CONCURRENCY,
+    (id) => client.setCustomFieldValue(id, field.id, parsed)
+  );
+  return toBulkResult(outcomes);
 }
 
 // src/commands/goals.ts
@@ -6596,7 +6701,7 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   ).option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", 'Due date (YYYY-MM-DD, or "none"/"clear" to remove)').option("--start-date <date>", "Start date (YYYY-MM-DD)").option(
     "--time-estimate <duration>",
     'Time estimate (e.g. "2h", "30m", "1h30m", "0" or "none" to clear)'
-  ).option("--assignee <userId>", 'Add assignee by user ID or "me"').option("--remove-assignee <userId>", 'Remove assignee by user ID or "me"').option("--parent <taskId>", "Set parent task (makes this a subtask)").option("--detach", "Remove parent task (promote subtask to top-level)").option("--archive", "Archive the task").option("--unarchive", "Unarchive the task").option("--field <nameAndValue...>", 'Set custom field: --field "Name" value').option("--json", "Force JSON output even in terminal").action(
+  ).option("--assignee <userId>", 'Add assignee by user ID or "me"').option("--remove-assignee <userId>", 'Remove assignee by user ID or "me"').option("--parent <taskId>", "Set parent task (makes this a subtask)").option("--detach", "Remove parent task (promote subtask to top-level)").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) => {
         const config = loadConfig(getProfileName());
@@ -6612,14 +6717,15 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
         ]);
         const payload = buildUpdatePayload(opts, timezone);
         const hasFields = (opts.field?.length ?? 0) > 0;
-        if (!hasFields && Object.keys(payload).length === 0) {
+        const hasTypeName = opts.type !== void 0;
+        if (!hasFields && !hasTypeName && Object.keys(payload).length === 0) {
           throw new Error(
-            "Provide at least one of: --name, --description, --status, --priority, --due-date, --time-estimate, --assignee, --remove-assignee, --parent, --archive, --unarchive, --field"
+            "Provide at least one of: --name, --description, --status, --priority, --due-date, --time-estimate, --assignee, --remove-assignee, --parent, --archive, --unarchive, --type, --field"
           );
         }
         let result;
-        if (Object.keys(payload).length > 0) {
-          result = await updateTask(config, taskId, payload);
+        if (Object.keys(payload).length > 0 || hasTypeName) {
+          result = await updateTask(config, taskId, payload, opts.type);
         }
         if (hasFields) {
           if ((opts.field?.length ?? 0) % 2 !== 0) {
@@ -6804,18 +6910,25 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       printTimeInStatus(result, opts.json ?? false);
     })
   );
-  program.command("lists <spaceId>").description("List all lists in a space (including lists inside folders)").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--json", "Force JSON output even in terminal").action(
-    wrapAction(async (spaceId, opts) => {
-      const config = loadConfig(getProfileName());
-      const lists = await fetchLists(config, spaceId, { name: opts.name });
-      printLists(lists, opts.json ?? false);
-    })
+  program.command("lists <spaceId>").description("List all lists in a space (including lists inside folders)").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--archived", "Include only archived items (default: active items)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (spaceId, opts) => {
+        const config = loadConfig(getProfileName());
+        const lists = await fetchLists(config, spaceId, {
+          name: opts.name,
+          archived: opts.archived
+        });
+        printLists(lists, opts.json ?? false);
+      }
+    )
   );
-  program.command("spaces").description("List spaces in your workspace").option("--name <partial>", "Filter spaces by name (case-insensitive contains)").option("--my", "Show only spaces where I have assigned tasks").option("--json", "Force JSON output even in terminal").action(
-    wrapAction(async (opts) => {
-      const config = loadConfig(getProfileName());
-      await listSpaces(config, opts);
-    })
+  program.command("spaces").description("List spaces in your workspace").option("--name <partial>", "Filter spaces by name (case-insensitive contains)").option("--my", "Show only spaces where I have assigned tasks").option("--archived", "Include only archived items (default: active items)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (opts) => {
+        const config = loadConfig(getProfileName());
+        await listSpaces(config, opts);
+      }
+    )
   );
   program.command("inbox").description("Recently updated tasks grouped by time period").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").option("--days <n>", "Lookback period in days", "30").action(
     wrapAction(async (opts) => {
@@ -7433,6 +7546,23 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     )
   );
+  bulkCmd.command("priority <taskIds...>").description("Bulk set priority on tasks (urgent/high/normal/low or 1-4)").requiredOption("--to <priority>", "Priority to set (urgent, high, normal, low, or 1-4)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskIds, opts) => {
+      const config = loadConfig(getProfileName());
+      const result = await bulkPriority(config, opts.to, taskIds);
+      outputBulkResult(result, opts.json ?? false, `priority ${opts.to}`);
+    })
+  );
+  bulkCmd.command("field <taskIds...>").description("Bulk set the same custom field value on tasks").requiredOption("--set <nameAndValue...>", 'Set field: --set "Field Name" value').option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskIds, opts) => {
+      if (opts.set.length !== 2) {
+        throw new Error("--set requires exactly two arguments: field name and value");
+      }
+      const config = loadConfig(getProfileName());
+      const result = await bulkField(config, opts.set[0], opts.set[1], taskIds);
+      outputBulkResult(result, opts.json ?? false, `field "${opts.set[0]}"`);
+    })
+  );
   program.command("goals").description("List goals in your workspace").option("--json", "Force JSON output even in terminal").action(
     wrapAction(async (opts) => {
       const config = loadConfig(getProfileName());
@@ -7602,18 +7732,20 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     })
   );
-  program.command("folders <spaceId>").description("List folders in a space (with their lists)").option("--name <partial>", "Filter folders by partial name match").option("--json", "Force JSON output even in terminal").action(
-    wrapAction(async (spaceId, opts) => {
-      const config = loadConfig(getProfileName());
-      const folders = await listFolders(config, spaceId, opts.name);
-      if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(folders, null, 2));
-      } else if (isTTY()) {
-        console.log(formatFolders(folders));
-      } else {
-        console.log(formatFoldersMarkdown(folders));
+  program.command("folders <spaceId>").description("List folders in a space (with their lists)").option("--name <partial>", "Filter folders by partial name match").option("--archived", "Include only archived items (default: active items)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (spaceId, opts) => {
+        const config = loadConfig(getProfileName());
+        const folders = await listFolders(config, spaceId, opts.name, opts.archived);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(folders, null, 2));
+        } else if (isTTY()) {
+          console.log(formatFolders(folders));
+        } else {
+          console.log(formatFoldersMarkdown(folders));
+        }
       }
-    })
+    )
   );
   program.command("space-create <name>").description("Create a new space in your workspace").option("--json", "Force JSON output even in terminal").action(
     wrapAction(async (name, opts) => {

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -152,7 +152,7 @@ All commands support `--help` for full flag details. All commands support `--jso
 | `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                                           |
-| `cup assign <id> [--to userId\|me] [--remove userId\|me]`                                                                                                                                                                                         | Assign/unassign users                                        |
+| `cup assign <id> [--to ids\|me] [--remove ids\|me]`                                                                                                                                                                                               | Assign/unassign users (`--to`/`--remove` accept comma-separated IDs) |
 | `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` accepts `sprint:current`) |
 | `cup field <id> [--set "Name" value] [--remove "Name"]`                                                                                                                                                                                           | Set/remove custom field values                               |
@@ -219,32 +219,32 @@ All commands support `--help` for full flag details. All commands support `--jso
 
 ## Flags & Conventions
 
-| Topic                    | Detail                                                                                                                                                                                                        |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Task IDs                 | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format                                                                                                               |
-| `--status`               | Fuzzy matching: exact > starts-with > contains. Prints match to stderr                                                                                                                                        |
-| `--priority`             | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4)                                                                                                                                                    |
-| `--due-date`             | `YYYY-MM-DD` format                                                                                                                                                                                           |
-| `--assignee`             | User ID or `me`                                                                                                                                                                                               |
-| `--tags`                 | Comma-separated (e.g. `--tags "bug,frontend"`)                                                                                                                                                                |
-| `--time-estimate`        | Duration: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds                                                                                                                                                     |
-| `--type`                 | `task` (regular) or custom type name/ID (e.g. `initiative`, `Bug`)                                                                                                                                            |
-| `--custom-item-id`       | Custom task type ID for `cup create` (find with `cup task-types`)                                                                                                                                             |
-| `--space`                | Partial name match or exact ID                                                                                                                                                                                |
-| `--name`                 | Partial match, case-insensitive                                                                                                                                                                               |
-| `--all`                  | Show all tasks in workspace, not just assigned to me. Available on `tasks`, `search`, `overdue`. Default: my tasks only (smaller output for agent context windows)                                            |
-| `--include-closed`       | Include closed/done tasks                                                                                                                                                                                     |
-| `--list` on create       | Optional when `--parent` is given (auto-detected). Accepts `sprint:current` pseudo-ID                                                                                                                         |
-| `cup field --set`        | Supports: text, number, checkbox (true/false), dropdown (option name), labels (comma-separated names), date (YYYY-MM-DD), url, email. Names resolved case-insensitively; errors list available fields/options |
-| `cup field-create`       | Use `--options "a,b,c"` for `drop_down` and `labels` types (required). Other types don't need `--options`                                                                                                     |
-| `--field` filter         | `--field "Name" value` on `tasks` and `search` requires `--list` to resolve field names to IDs                                                                                                                |
-| `--due-before/after`     | `YYYY-MM-DD` date filters for due date range                                                                                                                                                                  |
-| `--created-before/after` | `YYYY-MM-DD` date filters for creation date range                                                                                                                                                             |
-| `cup sprint`             | Auto-detects active sprint by folder name (sprint/iteration/cycle/scrum), parses multiple date formats. Override with `--folder <id>`, `cup config set sprintFolderId <id>`, or favorite a sprint folder      |
-| `cup favorite`           | Local-only favorites (not synced to ClickUp). Types: sprint-folder, space, list, folder, view, task. Favorited sprint-folders auto-used by sprint commands                                                    |
-| `cup link`               | Both IDs must be the same type (both custom or both native)                                                                                                                                                   |
-| `cup delete`             | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone                                                                                                                                   |
-| Errors                   | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected                                                                                                                                   |
+| Topic                    | Detail                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Task IDs                 | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format                                                                                                                                                                                                                                                    |
+| `--status`               | Fuzzy matching: exact > starts-with > contains. Prints match to stderr                                                                                                                                                                                                                                                                             |
+| `--priority`             | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4)                                                                                                                                                                                                                                                                                         |
+| `--due-date`             | `YYYY-MM-DD` format                                                                                                                                                                                                                                                                                                                                |
+| `--assignee`             | User ID or `me`                                                                                                                                                                                                                                                                                                                                    |
+| `--tags`                 | Comma-separated (e.g. `--tags "bug,frontend"`)                                                                                                                                                                                                                                                                                                     |
+| `--time-estimate`        | Duration: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds                                                                                                                                                                                                                                                                                          |
+| `--type`                 | `task` (regular) or custom type name/ID (e.g. `initiative`, `Bug`)                                                                                                                                                                                                                                                                                 |
+| `--custom-item-id`       | Custom task type ID for `cup create` (find with `cup task-types`)                                                                                                                                                                                                                                                                                  |
+| `--space`                | Partial name match or exact ID                                                                                                                                                                                                                                                                                                                     |
+| `--name`                 | Partial match, case-insensitive                                                                                                                                                                                                                                                                                                                    |
+| `--all`                  | Show all tasks in workspace, not just assigned to me. Available on `tasks`, `search`, `overdue`. Default: my tasks only (smaller output for agent context windows)                                                                                                                                                                                 |
+| `--include-closed`       | Include closed/done tasks                                                                                                                                                                                                                                                                                                                          |
+| `--list` on create       | Optional when `--parent` is given (auto-detected). Accepts `sprint:current` pseudo-ID                                                                                                                                                                                                                                                              |
+| `cup field --set`        | Supports: text, number, checkbox (true/false), dropdown (option name), labels (comma-separated names), date (YYYY-MM-DD), url, email, emoji/rating (0-5), manual_progress (0-100), tasks/relationship (comma-separated task IDs), users/people (comma-separated user IDs). Names resolved case-insensitively; errors list available fields/options |
+| `cup field-create`       | Use `--options "a,b,c"` for `drop_down` and `labels` types (required). Other types don't need `--options`                                                                                                                                                                                                                                          |
+| `--field` filter         | `--field "Name" value` on `tasks` and `search` requires `--list` to resolve field names to IDs                                                                                                                                                                                                                                                     |
+| `--due-before/after`     | `YYYY-MM-DD` date filters for due date range                                                                                                                                                                                                                                                                                                       |
+| `--created-before/after` | `YYYY-MM-DD` date filters for creation date range                                                                                                                                                                                                                                                                                                  |
+| `cup sprint`             | Auto-detects active sprint by folder name (sprint/iteration/cycle/scrum), parses multiple date formats. Override with `--folder <id>`, `cup config set sprintFolderId <id>`, or favorite a sprint folder                                                                                                                                           |
+| `cup favorite`           | Local-only favorites (not synced to ClickUp). Types: sprint-folder, space, list, folder, view, task. Favorited sprint-folders auto-used by sprint commands                                                                                                                                                                                         |
+| `cup link`               | Both IDs must be the same type (both custom or both native)                                                                                                                                                                                                                                                                                        |
+| `cup delete`             | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone                                                                                                                                                                                                                                                                        |
+| Errors                   | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected                                                                                                                                                                                                                                                                        |
 
 ## Agent Workflow Examples
 
@@ -289,6 +289,7 @@ cup create -n "Bug fix" -l sprint:current         # create in active sprint
 cup create -n "Q3 Roadmap" -l <listId> --custom-item-id 1
 cup comment abc123def -m "Completed in PR #42"
 cup assign abc123def --to me
+cup assign abc123def --to 12345,67890        # assign multiple users at once
 cup depend task3 --on task2            # task3 waits for task2
 cup move task1 --to list2 --remove list1
 cup move task1 --to sprint:current               # move to active sprint