@krodak/clickup-cli 0.7.0 → 0.9.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "clickup-cli",
+  "description": "Claude Code skills for the cu (ClickUp CLI) tool - manage tasks, sprints, initiatives, and comments",
+  "version": "0.6.1",
+  "author": {
+    "name": "Krzysztof Rodak"
+  },
+  "homepage": "https://github.com/krodak/clickup-cli",
+  "repository": "https://github.com/krodak/clickup-cli",
+  "license": "MIT"
+}

package/README.md

@@ -20,13 +20,21 @@ This is the primary use case. Install the tool, install the skill file, and your
 
 ### 1. Install the skill
 
-The repo includes a skill file at `skill/SKILL.md` that teaches agents all available commands and when to use them.
+The repo includes a skill file at `skills/clickup-cli/SKILL.md` that teaches agents all available commands and when to use them. It's also packaged as a Claude Code plugin.
 
-**Claude Code:**
+**Claude Code (plugin - recommended):**
+
+The repo ships as a Claude Code plugin. Point Claude Code at the repo or installed npm package:
+
+```bash
+claude --plugin-dir ./node_modules/@krodak/clickup-cli
+```
+
+Or copy the skill manually:
 
 ```bash
 mkdir -p ~/.claude/skills/clickup
-cp skill/SKILL.md ~/.claude/skills/clickup/SKILL.md
+cp skills/clickup-cli/SKILL.md ~/.claude/skills/clickup/SKILL.md
 ```
 
 Then reference it in your `CLAUDE.md` or project instructions.
@@ -35,12 +43,12 @@ Then reference it in your `CLAUDE.md` or project instructions.
 
 ```bash
 mkdir -p ~/.config/opencode/skills/clickup
-cp skill/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
+cp skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
 ```
 
 **Codex / other agents:**
 
-Copy the contents of `skill/SKILL.md` into your system prompt or project instructions. It's a standalone markdown document.
+Copy the contents of `skills/clickup-cli/SKILL.md` into your system prompt or project instructions. It's a standalone markdown document.
 
 ### 2. Talk to your agent
 
@@ -90,7 +98,7 @@ When output is piped (no TTY), all commands output **Markdown** by default - opt
 
 ## Commands
 
-20 commands total. All support `--help` for full flag details.
+24 commands total. All support `--help` for full flag details.
 
 ### `cu init`
 
@@ -136,6 +144,15 @@ cu sprint --status "in progress"
 cu sprint --json
 ```
 
+### `cu sprints`
+
+List all sprints across sprint folders. Marks the currently active sprint.
+
+```bash
+cu sprints
+cu sprints --json
+```
+
 ### `cu assigned`
 
 All tasks assigned to me, grouped by pipeline stage (code review, in progress, to do, etc.).
@@ -158,7 +175,7 @@ cu inbox --json
 
 ### `cu task <id>`
 
-Get task details. Pretty summary in terminal, JSON when piped.
+Get task details including custom fields. Pretty summary in terminal, JSON when piped.
 
 ```bash
 cu task abc123
@@ -188,16 +205,18 @@ cu update abc123 --priority high
 cu update abc123 --due-date 2025-03-15
 cu update abc123 --assignee 12345
 cu update abc123 -n "New name" -s "done" --priority urgent
+cu update abc123 -s "in progress" --json
 ```
 
-| Flag                       | Description                                          |
-| -------------------------- | ---------------------------------------------------- |
-| `-n, --name <text>`        | New task name                                        |
-| `-d, --description <text>` | New description (markdown supported)                 |
-| `-s, --status <status>`    | New status (e.g. `"in progress"`, `"done"`)          |
-| `--priority <level>`       | Priority: `urgent`, `high`, `normal`, `low` (or 1-4) |
-| `--due-date <date>`        | Due date (`YYYY-MM-DD`)                              |
-| `--assignee <userId>`      | Add assignee by numeric user ID                      |
+| Flag                       | Description                                                                 |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `-n, --name <text>`        | New task name                                                               |
+| `-d, --description <text>` | New description (markdown supported)                                        |
+| `-s, --status <status>`    | New status, supports fuzzy matching (e.g. `"prog"` matches `"in progress"`) |
+| `--priority <level>`       | Priority: `urgent`, `high`, `normal`, `low` (or 1-4)                        |
+| `--due-date <date>`        | Due date (`YYYY-MM-DD`)                                                     |
+| `--assignee <userId>`      | Add assignee by numeric user ID                                             |
+| `--json`                   | Force JSON output even in terminal                                          |
 
 ### `cu create`
 
@@ -209,6 +228,7 @@ cu create -n "Subtask name" -p <parentTaskId>    # --list auto-detected
 cu create -n "Task" -l <listId> -d "desc" -s "open"
 cu create -n "Task" -l <listId> --priority high --due-date 2025-06-01
 cu create -n "Task" -l <listId> --assignee 12345 --tags "bug,frontend"
+cu create -n "Fix bug" -l <listId> --json
 ```
 
 | Flag                       | Required         | Description                                          |
@@ -222,6 +242,7 @@ cu create -n "Task" -l <listId> --assignee 12345 --tags "bug,frontend"
 | `--due-date <date>`        | no               | Due date (`YYYY-MM-DD`)                              |
 | `--assignee <userId>`      | no               | Assignee by numeric user ID                          |
 | `--tags <tags>`            | no               | Comma-separated tag names                            |
+| `--json`                   | no               | Force JSON output even in terminal                   |
 
 ### `cu comment <id>`
 
@@ -240,6 +261,15 @@ cu comments abc123
 cu comments abc123 --json
 ```
 
+### `cu activity <id>`
+
+View task details and comment history together. Combines `cu task` and `cu comments` into a single view.
+
+```bash
+cu activity abc123
+cu activity abc123 --json
+```
+
 ### `cu lists <spaceId>`
 
 List all lists in a space, including lists inside folders. Useful for discovering list IDs needed by `--list` filter and `cu create -l`.
@@ -284,6 +314,17 @@ cu open abc123 --json
 
 If the query matches multiple tasks by name, all matches are listed and the first is opened.
 
+### `cu search <query>`
+
+Search my tasks by name. Supports multi-word queries with case-insensitive matching. Status filter supports fuzzy matching.
+
+```bash
+cu search "login bug"
+cu search auth
+cu search "payment flow" --json
+cu search auth --status "prog"     # fuzzy matches "in progress"
+```
+
 ### `cu summary`
 
 Daily standup helper. Shows tasks grouped into: recently completed, in progress, and overdue.
@@ -326,6 +367,15 @@ cu assign abc123 --to me --json
 | `--remove <userId>` | Remove assignee (user ID or `me`) |
 | `--json`            | Force JSON output                 |
 
+### `cu auth`
+
+Check authentication status. Validates your API token and shows your user info.
+
+```bash
+cu auth
+cu auth --json
+```
+
 ### `cu config`
 
 Manage CLI configuration.

package/dist/index.js

@@ -61,9 +61,13 @@ function getConfigPath() {
 function writeConfig(config) {
   const dir = configDir();
   if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(dir, { recursive: true, mode: 448 });
   }
-  fs.writeFileSync(join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
+  const filePath = join(dir, "config.json");
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n", {
+    encoding: "utf-8",
+    mode: 384
+  });
 }
 
 // src/api.ts
@@ -187,6 +191,9 @@ var ClickUpClient = class {
     const data = await this.request("/team");
     return data.teams ?? [];
   }
+  async getSpaceWithStatuses(spaceId) {
+    return this.request(`/space/${spaceId}`);
+  }
   async getSpaces(teamId) {
     const data = await this.request(`/team/${teamId}/space?archived=false`);
     return data.spaces ?? [];
@@ -422,6 +429,40 @@ function descriptionPreview(text, maxLines = 3) {
   ${chalk2.dim(`... (${lines.length - maxLines} more lines)`)}`;
   return result;
 }
+function stringifyFieldValue(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+function formatCustomFieldValue(field) {
+  if (field.value === null || field.value === void 0) return null;
+  const options = field.type_config?.options;
+  switch (field.type) {
+    case "drop_down": {
+      if (!options) return stringifyFieldValue(field.value);
+      const match = options.find((o) => o.id === Number(field.value));
+      return match?.name ?? stringifyFieldValue(field.value);
+    }
+    case "labels": {
+      if (!Array.isArray(field.value) || !options) return stringifyFieldValue(field.value);
+      const names = field.value.map((id) => options.find((o) => o.id === id)?.name).filter((n) => n !== void 0);
+      return names.length > 0 ? names.join(", ") : null;
+    }
+    case "date": {
+      const ts = Number(field.value);
+      if (!Number.isFinite(ts)) return stringifyFieldValue(field.value);
+      return new Date(ts).toLocaleDateString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric"
+      });
+    }
+    case "checkbox":
+      return field.value === true || field.value === "true" ? "Yes" : "No";
+    default:
+      return stringifyFieldValue(field.value);
+  }
+}
 function formatTaskDetail(task) {
   const lines = [];
   const isInitiative2 = (task.custom_item_id ?? 0) !== 0;
@@ -451,6 +492,16 @@ function formatTaskDetail(task) {
     if (!value) continue;
     lines.push(`  ${chalk2.bold(label.padEnd(maxLabel + 1))} ${value}`);
   }
+  if (task.custom_fields?.length) {
+    const formatted = task.custom_fields.map((f) => [f.name, formatCustomFieldValue(f)]).filter((pair) => pair[1] !== null);
+    if (formatted.length > 0) {
+      lines.push("");
+      lines.push(chalk2.bold("Custom Fields"));
+      for (const [name, value] of formatted) {
+        lines.push(`  ${chalk2.bold(name)}  ${value}`);
+      }
+    }
+  }
   if (task.text_content?.trim()) {
     lines.push("");
     lines.push(descriptionPreview(task.text_content));
@@ -586,6 +637,19 @@ async function printTasks(tasks, forceJson, config) {
   await showDetailsAndOpen(selected, fetchTask);
 }
 
+// src/status.ts
+function matchStatus(input, statuses) {
+  if (!input) return null;
+  const lower = input.toLowerCase();
+  const exact = statuses.find((s) => s.toLowerCase() === lower);
+  if (exact) return exact;
+  const startsWith = statuses.find((s) => s.toLowerCase().startsWith(lower));
+  if (startsWith) return startsWith;
+  const contains = statuses.find((s) => s.toLowerCase().includes(lower));
+  if (contains) return contains;
+  return null;
+}
+
 // src/commands/update.ts
 var PRIORITY_MAP = {
   urgent: 1,
@@ -631,12 +695,30 @@ function buildUpdatePayload(opts) {
 function hasUpdateFields(options) {
   return options.name !== void 0 || options.description !== void 0 || options.status !== void 0 || options.priority !== void 0 || options.due_date !== void 0 || options.assignees !== void 0;
 }
+async function resolveStatus(client, taskId, statusInput) {
+  const task = await client.getTask(taskId);
+  if (!task.space) return statusInput;
+  const space = await client.getSpaceWithStatuses(task.space.id);
+  const available = space.statuses.map((s) => s.status);
+  const matched = matchStatus(statusInput, available);
+  if (!matched) {
+    throw new Error(`No matching status for "${statusInput}". Available: ${available.join(", ")}`);
+  }
+  if (matched.toLowerCase() !== statusInput.toLowerCase()) {
+    process.stderr.write(`Status matched: "${statusInput}" -> "${matched}"
+`);
+  }
+  return matched;
+}
 async function updateTask(config, taskId, options) {
   if (!hasUpdateFields(options))
     throw new Error(
       "Provide at least one of: --name, --description, --status, --priority, --due-date, --assignee"
     );
   const client = new ClickUpClient(config);
+  if (options.status !== void 0) {
+    options.status = await resolveStatus(client, taskId, options.status);
+  }
   const task = await client.updateTask(taskId, options);
   return { id: task.id, name: task.name };
 }
@@ -814,6 +896,83 @@ async function runSprintCommand(config, opts) {
   await printTasks(summaries, opts.json ?? false, config);
 }
 
+// src/commands/sprints.ts
+var SPRINT_COLUMNS = [
+  { key: "id", label: "ID" },
+  { key: "sprint", label: "SPRINT", maxWidth: 60 },
+  { key: "dates", label: "DATES" }
+];
+function formatDate2(d) {
+  return `${d.getMonth() + 1}/${d.getDate()}`;
+}
+function buildSprintInfos(lists, folderName, today) {
+  return lists.map((list) => {
+    const dates = parseSprintDates(list.name);
+    const active = dates !== null && today >= dates.start && today <= dates.end;
+    return {
+      id: list.id,
+      name: list.name,
+      folder: folderName,
+      start: dates ? dates.start.toISOString() : null,
+      end: dates ? dates.end.toISOString() : null,
+      active
+    };
+  });
+}
+async function listSprints(config, opts = {}) {
+  const client = new ClickUpClient(config);
+  const [myTasks, allSpaces] = await Promise.all([
+    client.getMyTasks(config.teamId),
+    client.getSpaces(config.teamId)
+  ]);
+  let spaces;
+  if (opts.space) {
+    spaces = allSpaces.filter(
+      (s) => s.name.toLowerCase().includes(opts.space.toLowerCase()) || s.id === opts.space
+    );
+    if (spaces.length === 0) {
+      throw new Error(
+        `No space matching "${opts.space}" found. Use \`cu spaces\` to list available spaces.`
+      );
+    }
+  } else {
+    const mySpaceIds = new Set(
+      myTasks.map((t) => t.space?.id).filter((id) => Boolean(id))
+    );
+    spaces = findRelatedSpaces(mySpaceIds, allSpaces);
+  }
+  const foldersBySpace = await Promise.all(spaces.map((space) => client.getFolders(space.id)));
+  const sprintFolders = foldersBySpace.flat().filter((f) => f.name.toLowerCase().includes("sprint"));
+  const today = /* @__PURE__ */ new Date();
+  const allSprints = [];
+  const listsByFolder = await Promise.all(
+    sprintFolders.map((folder) => client.getFolderLists(folder.id))
+  );
+  for (let i = 0; i < sprintFolders.length; i++) {
+    const folder = sprintFolders[i];
+    const lists = listsByFolder[i];
+    allSprints.push(...buildSprintInfos(lists, folder.name, today));
+  }
+  if (opts.json || !isTTY()) {
+    console.log(JSON.stringify(allSprints, null, 2));
+    return;
+  }
+  if (allSprints.length === 0) {
+    console.log("No sprints found.");
+    return;
+  }
+  const rows = allSprints.map((s) => {
+    const dates = parseSprintDates(s.name);
+    const dateStr = dates ? `${formatDate2(dates.start)} - ${formatDate2(dates.end)}` : "";
+    return {
+      id: s.id,
+      sprint: s.active ? `* ${s.name}` : s.name,
+      dates: dateStr
+    };
+  });
+  console.log(formatTable(rows, SPRINT_COLUMNS));
+}
+
 // src/commands/subtasks.ts
 async function fetchSubtasks(config, taskId) {
   const client = new ClickUpClient(config);
@@ -831,7 +990,7 @@ async function postComment(config, taskId, text) {
 
 // src/commands/comments.ts
 import chalk3 from "chalk";
-function formatDate2(timestamp) {
+function formatDate3(timestamp) {
   return new Date(Number(timestamp)).toLocaleString("en-US", {
     month: "short",
     day: "numeric",
@@ -867,7 +1026,7 @@ function printComments(comments, forceJson) {
   for (let i = 0; i < comments.length; i++) {
     const c = comments[i];
     if (i > 0) console.log(separator);
-    console.log(`${chalk3.bold(c.user)}  ${chalk3.dim(formatDate2(c.date))}`);
+    console.log(`${chalk3.bold(c.user)}  ${chalk3.dim(formatDate3(c.date))}`);
     console.log(c.text);
     if (i < comments.length - 1) console.log("");
   }
@@ -1317,6 +1476,55 @@ async function assignTask(config, taskId, opts) {
   });
 }
 
+// src/commands/activity.ts
+import chalk4 from "chalk";
+function formatDate4(timestamp) {
+  return new Date(Number(timestamp)).toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit"
+  });
+}
+async function fetchActivity(config, taskId) {
+  const client = new ClickUpClient(config);
+  const [task, rawComments] = await Promise.all([
+    client.getTask(taskId),
+    client.getTaskComments(taskId)
+  ]);
+  const comments = rawComments.map((c) => ({
+    id: c.id,
+    user: c.user.username,
+    date: c.date,
+    text: c.comment_text
+  }));
+  return { task, comments };
+}
+function printActivity(result, forceJson) {
+  if (forceJson || !isTTY()) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatTaskDetail(result.task));
+  console.log("");
+  console.log(chalk4.bold("Comments"));
+  console.log(chalk4.dim("-".repeat(60)));
+  if (result.comments.length === 0) {
+    console.log("No comments.");
+    return;
+  }
+  for (let i = 0; i < result.comments.length; i++) {
+    const c = result.comments[i];
+    if (i > 0) {
+      console.log("");
+      console.log(chalk4.dim("-".repeat(60)));
+    }
+    console.log(`${chalk4.bold(c.user)}  ${chalk4.dim(formatDate4(c.date))}`);
+    console.log(c.text);
+  }
+}
+
 // src/commands/completion.ts
 function bashCompletion() {
   return `_cu_completions() {
@@ -1721,6 +1929,47 @@ function generateCompletion(shell) {
   }
 }
 
+// src/commands/auth.ts
+async function checkAuth(config) {
+  const client = new ClickUpClient(config);
+  try {
+    const user = await client.getMe();
+    return { authenticated: true, user };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { authenticated: false, error: message };
+  }
+}
+
+// src/commands/search.ts
+async function searchTasks(config, query, opts = {}) {
+  const trimmed = query.trim();
+  if (!trimmed) {
+    throw new Error("Search query cannot be empty");
+  }
+  const client = new ClickUpClient(config);
+  const allTasks = await client.getMyTasks(config.teamId);
+  const words = trimmed.toLowerCase().split(/\s+/);
+  let matched = allTasks.filter((task) => {
+    const name = task.name.toLowerCase();
+    return words.every((word) => name.includes(word));
+  });
+  if (opts.status) {
+    const availableStatuses = [...new Set(allTasks.map((t) => t.status.status))];
+    const resolved = matchStatus(opts.status, availableStatuses);
+    if (resolved) {
+      if (resolved.toLowerCase() !== opts.status.toLowerCase()) {
+        process.stderr.write(`Status matched: "${opts.status}" -> "${resolved}"
+`);
+      }
+      matched = matched.filter((t) => t.status.status.toLowerCase() === resolved.toLowerCase());
+    } else {
+      matched = matched.filter((t) => t.status.status.toLowerCase() === opts.status.toLowerCase());
+    }
+  }
+  return matched.map(summarize);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1739,6 +1988,20 @@ program.command("init").description("Set up cu for the first time").action(
     await runInitCommand();
   })
 );
+program.command("auth").description("Validate API token and show current user").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (opts) => {
+    const config = loadConfig();
+    const result = await checkAuth(config);
+    if (opts.json || !isTTY()) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.authenticated && result.user) {
+      console.log(`Authenticated as @${result.user.username} (id: ${result.user.id})`);
+    } else {
+      console.error(`Authentication failed: ${result.error ?? "unknown error"}`);
+      process.exit(1);
+    }
+  })
+);
 program.command("tasks").description("List tasks assigned to me").option("--status <status>", 'Filter by status (e.g. "in progress")').option("--list <listId>", "Filter by list ID").option("--space <spaceId>", "Filter by space ID").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
@@ -1774,21 +2037,11 @@ program.command("task <taskId>").description("Get task details").option("--json"
     } else if (!isTTY()) {
       console.log(formatTaskDetailMarkdown(result));
     } else {
-      const lines = [
-        `ID:          ${result.id}`,
-        `Name:        ${result.name}`,
-        `Status:      ${result.status?.status ?? "unknown"}`,
-        `Type:        ${(result.custom_item_id ?? 0) !== 0 ? "initiative" : "task"}`,
-        `List:        ${result.list?.name ?? "unknown"}`,
-        `URL:         ${result.url}`,
-        ...result.parent ? [`Parent:      ${result.parent}`] : [],
-        ...result.description ? ["", result.description] : []
-      ];
-      console.log(lines.join("\n"));
+      console.log(formatTaskDetail(result));
     }
   })
 );
-program.command("update <taskId>").description("Update a task").option("-n, --name <text>", "New task name").option("-d, --description <text>", "New description (markdown supported)").option("-s, --status <status>", 'New status (e.g. "in progress", "done")').option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", "Add assignee by user ID").action(
+program.command("update <taskId>").description("Update a task").option("-n, --name <text>", "New task name").option("-d, --description <text>", "New description (markdown supported)").option("-s, --status <status>", 'New status (e.g. "in progress", "done")').option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", "Add assignee by user ID").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
     const payload = buildUpdatePayload(opts);
@@ -1800,7 +2053,7 @@ program.command("update <taskId>").description("Update a task").option("-n, --na
     }
   })
 );
-program.command("create").description("Create a new task").option("-l, --list <listId>", "Target list ID (auto-detected from --parent if omitted)").requiredOption("-n, --name <name>", "Task name").option("-d, --description <text>", "Task description").option("-p, --parent <taskId>", "Parent task ID (list auto-detected from parent)").option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", "Assignee user ID").option("--tags <tags>", "Comma-separated tag names").action(
+program.command("create").description("Create a new task").option("-l, --list <listId>", "Target list ID (auto-detected from --parent if omitted)").requiredOption("-n, --name <name>", "Task name").option("-d, --description <text>", "Task description").option("-p, --parent <taskId>", "Parent task ID (list auto-detected from parent)").option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", "Assignee user ID").option("--tags <tags>", "Comma-separated tag names").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     const result = await createTask(config, opts);
@@ -1817,6 +2070,12 @@ program.command("sprint").description("List my tasks in the current active sprin
     await runSprintCommand(config, opts);
   })
 );
+program.command("sprints").description("List all sprints in sprint folders").option("--space <nameOrId>", "Filter by space (partial name or ID)").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (opts) => {
+    const config = loadConfig();
+    await listSprints(config, opts);
+  })
+);
 program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
@@ -1842,6 +2101,13 @@ program.command("comments <taskId>").description("List comments on a task").opti
     printComments(comments, opts.json ?? false);
   })
 );
+program.command("activity <taskId>").description("Show task details and comments combined").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (taskId, opts) => {
+    const config = loadConfig();
+    const result = await fetchActivity(config, taskId);
+    printActivity(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();
@@ -1879,6 +2145,13 @@ program.command("open <query>").description("Open a task in the browser by ID or
     await openTask(config, query, opts);
   })
 );
+program.command("search <query>").description("Search my tasks by name").option("--status <status>", "Filter by status").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (query, opts) => {
+    const config = loadConfig();
+    const tasks = await searchTasks(config, query, { status: opts.status });
+    await printTasks(tasks, opts.json ?? false, config);
+  })
+);
 program.command("summary").description("Daily standup summary: completed, in-progress, overdue").option("--hours <n>", "Completed-tasks lookback in hours", "24").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krodak/clickup-cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "ClickUp CLI for AI agents and humans",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,8 @@
   },
   "files": [
     "dist",
+    ".claude-plugin",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/clickup-cli/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: clickup
+description: 'Use when managing ClickUp tasks, initiatives, sprints, or comments via the `cu` CLI tool. Triggers: task queries, status updates, sprint tracking, creating subtasks, posting comments, standup summaries, searching tasks, checking overdue items.'
+---
+
+# ClickUp CLI (`cu`)
+
+Reference for AI agents using the `cu` CLI tool. Covers task management, sprint tracking, initiatives, comments, and project workflows.
+
+Keywords: ClickUp, task management, sprint, initiative, project management, agile, backlog, subtasks, standup, overdue, search
+
+## Setup
+
+Config at `~/.config/cu/config.json` with `apiToken` and `teamId`. Run `cu init` to set up interactively.
+
+Environment variables `CU_API_TOKEN` and `CU_TEAM_ID` override config file when both are set.
+
+## Output Modes
+
+| Context         | Default output        | Override          |
+| --------------- | --------------------- | ----------------- |
+| Terminal (TTY)  | Interactive picker UI | `--json` for JSON |
+| Piped / non-TTY | Markdown tables       | `--json` for JSON |
+
+- Default piped output is **Markdown** - optimized for agent context windows
+- `cu task <id>` outputs a Markdown summary when piped; use `--json` for the full raw API object (custom fields, checklists, etc.)
+- Set `CU_OUTPUT=json` to always get JSON when piped
+- Set `NO_COLOR` to disable color (tables still render, just uncolored)
+- Agents typically don't need `--json` unless parsing structured data with `jq`
+
+## Commands
+
+All commands support `--help` for full flag details.
+
+### Read
+
+| Command                                                                    | What it returns                                    |
+| -------------------------------------------------------------------------- | -------------------------------------------------- |
+| `cu tasks [--status s] [--name q] [--list id] [--space id] [--json]`       | My tasks (workspace-wide)                          |
+| `cu initiatives [--status s] [--name q] [--list id] [--space id] [--json]` | My initiatives                                     |
+| `cu assigned [--include-closed] [--json]`                                  | All my tasks grouped by status                     |
+| `cu sprint [--status s] [--space nameOrId] [--json]`                       | Tasks in active sprint (auto-detected)             |
+| `cu sprints [--space nameOrId] [--json]`                                   | List all sprints (marks active with \*)            |
+| `cu search <query> [--status s] [--json]`                                  | Search my tasks by name (multi-word, fuzzy status) |
+| `cu task <id> [--json]`                                                    | Single task details                                |
+| `cu subtasks <id> [--json]`                                                | Subtasks of a task or initiative                   |
+| `cu comments <id> [--json]`                                                | Comments on a task                                 |
+| `cu activity <id> [--json]`                                                | Task details + comment history combined            |
+| `cu inbox [--days n] [--json]`                                             | Tasks updated in last n days (default 30)          |
+| `cu summary [--hours n] [--json]`                                          | Standup helper: completed, in-progress, overdue    |
+| `cu overdue [--json]`                                                      | Tasks past their due date                          |
+| `cu spaces [--name partial] [--my] [--json]`                               | List/filter workspace spaces                       |
+| `cu lists <spaceId> [--name partial] [--json]`                             | Lists in a space (including folder lists)          |
+| `cu open <query> [--json]`                                                 | Open task in browser by ID or name                 |
+| `cu auth [--json]`                                                         | Check authentication status                        |
+
+### Write
+
+| Command                                                                                                                               | What it does                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `cu update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d] [--assignee id] [--json]`                               | Update task fields                           |
+| `cu create -n name [-l listId] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--assignee id] [--tags t] [--json]` | Create task (list auto-detected from parent) |
+| `cu comment <id> -m text`                                                                                                             | Post comment on task                         |
+| `cu assign <id> [--to userId\|me] [--remove userId\|me] [--json]`                                                                     | Assign/unassign users                        |
+| `cu config get <key>` / `cu config set <key> <value>` / `cu config path`                                                              | Manage CLI config                            |
+| `cu completion <shell>`                                                                                                               | Shell completions (bash/zsh/fish)            |
+
+## Quick Reference
+
+| Topic               | Detail                                                                            |
+| ------------------- | --------------------------------------------------------------------------------- |
+| Task IDs            | Stable alphanumeric strings (e.g. `abc123def`)                                    |
+| Initiatives         | Detected via `custom_item_id !== 0`                                               |
+| `--list` on create  | Optional when `--parent` is given (auto-detected)                                 |
+| `--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`        | Numeric user ID (find via `cu task <id> --json`)                                  |
+| `--tags`            | Comma-separated (e.g. `--tags "bug,frontend"`)                                    |
+| `--space`           | Partial name match or exact ID                                                    |
+| `--name`            | Partial match, case-insensitive                                                   |
+| `cu assign --to me` | Shorthand for your own user ID                                                    |
+| `cu search`         | Matches all query words against task name, case-insensitive                       |
+| `cu sprint`         | Auto-detects active sprint via view API and date range parsing                    |
+| `cu summary`        | Categories: completed (done/complete/closed within N hours), in progress, overdue |
+| `cu overdue`        | Excludes closed tasks, sorted most overdue first                                  |
+| `cu open`           | Tries task ID first, falls back to name search                                    |
+| `cu task`           | Shows custom fields in detail view                                                |
+| `cu lists`          | Discovers list IDs needed for `--list` and `cu create -l`                         |
+| Errors              | stderr with exit code 1                                                           |
+| Parsing             | Strict - excess/unknown arguments rejected                                        |
+
+## Agent Workflow Examples
+
+### Investigate a task
+
+```bash
+cu task abc123def                   # markdown summary
+cu subtasks abc123def               # child tasks
+cu comments abc123def               # discussion
+cu activity abc123def               # task + comments combined
+```
+
+### Find tasks
+
+```bash
+cu tasks --status "in progress"     # by status
+cu tasks --name "login"             # by partial name
+cu search "payment flow"            # multi-word search
+cu search auth --status "prog"      # fuzzy status match
+cu sprint                           # current sprint
+cu assigned                         # all my tasks by status
+cu overdue                          # past due date
+cu inbox --days 7                   # recently updated
+```
+
+### Make changes
+
+```bash
+cu update abc123def -s "done"
+cu update abc123def --priority high --due-date 2025-03-15
+cu create -n "Fix the thing" -p abc123def
+cu create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
+cu comment abc123def -m "Completed in PR #42"
+cu assign abc123def --to me
+```
+
+### Discover workspace structure
+
+```bash
+cu spaces                           # all spaces
+cu lists <spaceId>                  # lists in a space (needed for --list flag)
+cu sprints                          # all sprints across folders
+cu auth                             # verify token works
+```
+
+### Standup
+
+```bash
+cu summary                          # completed / in progress / overdue
+cu summary --hours 48               # wider window
+```