@krodak/clickup-cli 1.21.1 → 1.22.1

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.1",
+  "version": "1.22.1",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -16,13 +16,24 @@ npm install -g @krodak/clickup-cli && cup init
 
 ## For AI Agents
 
-Paste this into any AI agent to get started immediately:
+Paste this into any AI agent (Claude Code, Codex, Cursor, OpenCode, etc.):
 
 ```
-Fetch and follow instructions from https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md
+Install and configure the ClickUp CLI for me. Fetch the setup guide from:
+https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md
+
+Then walk me through installing the CLI, getting a ClickUp API token,
+and running cup init. Finally, install the skill with `cup skill` so
+you have persistent access to the full command reference.
 ```
 
-Or install the skill permanently with `cup skill` (see [Set up your agent](#set-up-your-agent) below).
+The fetched SKILL.md contains everything the agent needs: install commands,
+where to get a ClickUp API token, non-interactive setup with `cup init --token --team`,
+and the complete command reference. After setup, the agent can run any `cup` command
+to manage your tasks, sprints, comments, time tracking, and more.
+
+**Already have the CLI installed?** Just run `cup skill` to install the agent skill to
+all detected locations (see [Set up your agent](#set-up-your-agent) below).
 
 ## Talk to your agent
 

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) {
@@ -1015,7 +1021,9 @@ function loadConfig(profileName) {
     if (envToken || envTeamId) {
       throw new Error("Both CU_API_TOKEN and CU_TEAM_ID must be set, or run: cup init");
     }
-    throw new Error("Config missing required field: apiToken.\nSet CU_API_TOKEN or run: cup init");
+    throw new Error(
+      "No ClickUp CLI configuration found.\n\nTo get started:\n  cup init\n\nFor scripts or AI agents:\n  cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID\n\nGet your API token: https://app.clickup.com/settings/apps"
+    );
   }
   const { parsed } = parseRawConfig(path);
   if (isOldFormat(parsed)) {
@@ -1945,10 +1953,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 +1978,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 };
 }
@@ -2040,31 +2067,75 @@ async function getTask(config, taskId) {
 // src/commands/init.ts
 import { password, select, confirm as confirm2 } from "@inquirer/prompts";
 import fs2 from "fs";
+var TOKEN_URL = "https://app.clickup.com/settings/apps";
+var TOKEN_HELP = `
+How to get a ClickUp API token:
+  1. Open ${TOKEN_URL}
+  2. Find the "API Token" section, click "Generate" (or copy the existing one)
+  3. The token starts with "pk_"
+`;
+var NON_TTY_HELP = `cup init requires an interactive terminal.
+
+For scripts, CI, or AI agents, use flags:
+  cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID
+
+Or set environment variables:
+  export CU_API_TOKEN=pk_YOUR_TOKEN
+  export CU_TEAM_ID=YOUR_TEAM_ID
+${TOKEN_HELP}`;
+var NEXT_STEPS = `
+Next steps:
+  cup auth      # verify setup
+  cup tasks     # list your assigned tasks
+  cup sprint    # show current sprint
+  cup --help    # see all commands
+`;
+function validateTokenFormat(token) {
+  if (!token.startsWith("pk_")) {
+    throw new Error(
+      `Invalid token format. Personal API tokens start with "pk_".
+${TOKEN_HELP}`
+    );
+  }
+}
+async function verifyToken(apiToken) {
+  const client = new ClickUpClient({ apiToken });
+  try {
+    const me = await client.getMe();
+    return me.username;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Token verification failed: ${msg}
+
+Check the token is correct and not expired.
+${TOKEN_HELP}`,
+      { cause: err }
+    );
+  }
+}
 async function runInitCommand(opts) {
   if (opts?.token && opts?.team) {
     const apiToken2 = opts.token.trim();
-    if (!apiToken2.startsWith("pk_")) throw new Error("Token must start with pk_");
-    const client2 = new ClickUpClient({ apiToken: apiToken2 });
-    let username2;
-    try {
-      const me = await client2.getMe();
-      username2 = me.username;
-    } catch (err) {
-      throw new Error(`Invalid token: ${err instanceof Error ? err.message : String(err)}`, {
-        cause: err
-      });
-    }
+    validateTokenFormat(apiToken2);
+    const username2 = await verifyToken(apiToken2);
     process.stdout.write(`Authenticated as @${username2}
 `);
     writeConfig({ apiToken: apiToken2, teamId: opts.team });
     process.stdout.write(`Config written to ${getConfigPath()}
-`);
+${NEXT_STEPS}`);
     return;
   }
   if (opts?.token || opts?.team) {
     throw new Error("Both --token and --team are required for non-interactive setup");
   }
+  if (!process.stdin.isTTY) {
+    throw new Error(NON_TTY_HELP);
+  }
   const configPath3 = getConfigPath();
+  process.stdout.write("\nWelcome to ClickUp CLI!\n");
+  process.stdout.write(TOKEN_HELP);
+  process.stdout.write("\n");
   if (fs2.existsSync(configPath3)) {
     const overwrite = await confirm2({
       message: `Config already exists at ${configPath3}. Overwrite?`,
@@ -2075,20 +2146,14 @@ async function runInitCommand(opts) {
       return;
     }
   }
-  const apiToken = (await password({ message: "ClickUp API token (pk_...):" })).trim();
-  if (!apiToken.startsWith("pk_")) throw new Error("Token must start with pk_");
-  const client = new ClickUpClient({ apiToken });
-  let username;
-  try {
-    const me = await client.getMe();
-    username = me.username;
-  } catch (err) {
-    throw new Error(`Invalid token: ${err instanceof Error ? err.message : String(err)}`, {
-      cause: err
-    });
-  }
+  const apiToken = (await password({
+    message: "Paste your ClickUp API token (starts with pk_):"
+  })).trim();
+  validateTokenFormat(apiToken);
+  const username = await verifyToken(apiToken);
   process.stdout.write(`Authenticated as @${username}
 `);
+  const client = new ClickUpClient({ apiToken });
   const teams = await client.getTeams();
   if (teams.length === 0) throw new Error("No workspaces found for this token.");
   let teamId;
@@ -2105,8 +2170,9 @@ async function runInitCommand(opts) {
     });
   }
   writeConfig({ apiToken, teamId });
-  process.stdout.write(`Config written to ${configPath3}
-`);
+  process.stdout.write(`
+Config written to ${configPath3}
+${NEXT_STEPS}`);
 }
 
 // src/commands/sprint.ts
@@ -2502,12 +2568,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 +2705,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 +3017,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 +3028,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: {
@@ -3102,9 +3177,15 @@ function printTimeInStatus(result, forceJson) {
 var commandMetadata = [
   {
     name: "init",
-    description: "Set up cup for the first time",
+    description: "Set up cup (interactive). Use --token and --team for non-interactive/agent setup",
     flags: ["--token", "--team"],
-    quickReference: [{ section: "setup", usage: "init", description: "First-time setup wizard" }]
+    quickReference: [
+      {
+        section: "setup",
+        usage: "init",
+        description: "First-time setup (interactive, or use --token --team for agents)"
+      }
+    ]
   },
   {
     name: "auth",
@@ -3164,6 +3245,7 @@ var commandMetadata = [
       "--detach",
       "--archive",
       "--unarchive",
+      "--type",
       "--field",
       "--json"
     ],
@@ -3294,7 +3376,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 +3384,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 +3709,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 +3815,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"
       }
     ]
   },
@@ -3981,7 +4073,7 @@ function parseCommandFlags(flags = []) {
 }
 function commandDescription(command, programName = "cup") {
   if (command.name === "init") {
-    return `Set up ${programName} for the first time`;
+    return `Set up ${programName} (interactive). Use --token and --team for non-interactive/agent setup`;
   }
   return command.description;
 }
@@ -5219,7 +5311,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 +5380,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 +5788,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 +6052,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
@@ -6494,7 +6646,9 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   function getProfileName() {
     return program.opts().profile;
   }
-  program.command("init").description(`Set up ${programName} for the first time`).option("--token <token>", "API token (pk_...) for non-interactive setup").option("--team <teamId>", "Workspace/team ID for non-interactive setup").action(
+  program.command("init").description(
+    `Set up ${programName} (interactive). Use --token and --team for non-interactive/agent setup`
+  ).option("--token <token>", "API token (pk_...) for non-interactive setup").option("--team <teamId>", "Workspace/team ID for non-interactive setup").action(
     wrapAction(async (opts) => {
       await runInitCommand(opts);
     })
@@ -6596,7 +6750,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 +6766,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 +6959,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 +7595,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 +7781,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.1",
+  "version": "1.22.1",
   "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.17.0
+# ClickUp CLI (`cup`) - skill version 1.22.0
 
-Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, and project workflows.
+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.18.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.22.0, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
 
 ## Install & Configure
 
@@ -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