@krodak/clickup-cli 0.10.0 → 0.11.1

package/README.md

@@ -118,6 +118,7 @@ cu tasks --status "in progress"
 cu tasks --name "login"
 cu tasks --list <listId>
 cu tasks --space <spaceId>
+cu tasks --include-closed
 cu tasks --json
 ```
 
@@ -131,6 +132,7 @@ cu initiatives --status "to do"
 cu initiatives --name "auth"
 cu initiatives --list <listId>
 cu initiatives --space <spaceId>
+cu initiatives --include-closed
 cu initiatives --json
 ```
 
@@ -141,6 +143,7 @@ List my tasks in the currently active sprint (auto-detected from sprint folder d
 ```bash
 cu sprint
 cu sprint --status "in progress"
+cu sprint --include-closed
 cu sprint --json
 ```
 
@@ -159,6 +162,7 @@ All tasks assigned to me, grouped by pipeline stage (code review, in progress, t
 
 ```bash
 cu assigned
+cu assigned --status "in progress"
 cu assigned --include-closed
 cu assigned --json
 ```
@@ -190,6 +194,8 @@ List subtasks of a task or initiative.
 
 ```bash
 cu subtasks abc123
+cu subtasks abc123 --status "in progress"
+cu subtasks abc123 --name "auth"
 cu subtasks abc123 --include-closed
 cu subtasks abc123 --json
 ```
@@ -330,6 +336,7 @@ cu search "login bug"
 cu search auth
 cu search "payment flow" --json
 cu search auth --status "prog"     # fuzzy matches "in progress"
+cu search "old task" --include-closed
 ```
 
 ### `cu summary`

package/dist/index.js

@@ -177,8 +177,8 @@ var ClickUpClient = class {
   async getTask(taskId) {
     return this.request(`/task/${taskId}`);
   }
-  async updateTaskDescription(taskId, description) {
-    return this.updateTask(taskId, { description });
+  async updateTaskMarkdown(taskId, markdown) {
+    return this.updateTask(taskId, { markdown_content: markdown });
   }
   async createTask(listId, options) {
     return this.request(`/list/${listId}/task`, {
@@ -712,7 +712,7 @@ function parseTimeEstimate(value) {
 function buildUpdatePayload(opts) {
   const payload = {};
   if (opts.name !== void 0) payload.name = opts.name;
-  if (opts.description !== void 0) payload.description = opts.description;
+  if (opts.description !== void 0) payload.markdown_content = opts.description;
   if (opts.status !== void 0) payload.status = opts.status;
   if (opts.priority !== void 0) payload.priority = parsePriority(opts.priority);
   if (opts.dueDate !== void 0) {
@@ -728,7 +728,7 @@ function buildUpdatePayload(opts) {
   return payload;
 }
 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.time_estimate !== void 0 || options.assignees !== 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.time_estimate !== void 0 || options.assignees !== void 0;
 }
 async function resolveStatus(client, taskId, statusInput) {
   const task = await client.getTask(taskId);
@@ -771,7 +771,7 @@ async function createTask(config, options) {
   }
   const payload = {
     name: options.name,
-    ...options.description !== void 0 ? { description: options.description } : {},
+    ...options.description !== void 0 ? { markdown_content: options.description } : {},
     ...options.parent !== void 0 ? { parent: options.parent } : {},
     ...options.status !== void 0 ? { status: options.status } : {}
   };
@@ -934,7 +934,10 @@ async function runSprintCommand(config, opts) {
   } else {
     allTasks = await client.getTasksFromList(activeList.id);
   }
-  const sprintTasks = allTasks.filter((t) => t.assignees.some((a) => Number(a.id) === me.id));
+  let sprintTasks = allTasks.filter((t) => t.assignees.some((a) => Number(a.id) === me.id));
+  if (!opts.includeClosed) {
+    sprintTasks = sprintTasks.filter((t) => !isDoneStatus(t.status.status));
+  }
   const filtered = opts.status ? sprintTasks.filter((t) => t.status.status.toLowerCase() === opts.status.toLowerCase()) : sprintTasks;
   const summaries = filtered.map(summarize);
   await printTasks(summaries, opts.json ?? false, config);
@@ -997,7 +1000,7 @@ async function listSprints(config, opts = {}) {
     const lists = listsByFolder[i];
     allSprints.push(...buildSprintInfos(lists, folder.name, today));
   }
-  if (opts.json || !isTTY()) {
+  if (shouldOutputJson(opts.json ?? false)) {
     console.log(JSON.stringify(allSprints, null, 2));
     return;
   }
@@ -1014,6 +1017,15 @@ async function listSprints(config, opts = {}) {
       dates: dateStr
     };
   });
+  if (!isTTY()) {
+    const mdColumns = [
+      { key: "id", label: "ID" },
+      { key: "sprint", label: "Sprint" },
+      { key: "dates", label: "Dates" }
+    ];
+    console.log(formatMarkdownTable(rows, mdColumns));
+    return;
+  }
   console.log(formatTable(rows, SPRINT_COLUMNS));
 }
 
@@ -1231,6 +1243,8 @@ async function listSpaces(config, opts) {
     console.log(JSON.stringify(spaces, null, 2));
   } else if (!isTTY()) {
     console.log(formatSpacesMarkdown(spaces.map((s) => ({ id: s.id, name: s.name }))));
+  } else if (spaces.length === 0) {
+    console.log("No spaces found.");
   } else {
     const table = formatTable(
       spaces.map((s) => ({ id: s.id, name: s.name })),
@@ -1295,7 +1309,11 @@ async function runAssignedCommand(config, opts) {
   const allTasks = await client.getMyTasks(config.teamId, {
     includeClosed: opts.includeClosed
   });
-  const groups = groupByStatus(allTasks, opts.includeClosed ?? false);
+  let groups = groupByStatus(allTasks, opts.includeClosed ?? false);
+  if (opts.status) {
+    const lower = opts.status.toLowerCase();
+    groups = groups.filter((g) => g.status.toLowerCase() === lower);
+  }
   if (shouldOutputJson(opts.json ?? false)) {
     const result = {};
     for (const group of groups) {
@@ -1552,10 +1570,20 @@ async function fetchActivity(config, taskId) {
   return { task, comments };
 }
 function printActivity(result, forceJson) {
-  if (forceJson || !isTTY()) {
+  if (shouldOutputJson(forceJson)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
+  if (!isTTY()) {
+    const taskMd = formatTaskDetailMarkdown(result.task);
+    const commentsMd = formatCommentsMarkdown(result.comments);
+    console.log(`${taskMd}
+
+## Comments
+
+${commentsMd}`);
+    return;
+  }
   console.log(formatTaskDetail(result.task));
   console.log("");
   console.log(chalk4.bold("Comments"));
@@ -1998,7 +2026,9 @@ async function searchTasks(config, query, opts = {}) {
     throw new Error("Search query cannot be empty");
   }
   const client = new ClickUpClient(config);
-  const allTasks = await client.getMyTasks(config.teamId);
+  const allTasks = await client.getMyTasks(config.teamId, {
+    includeClosed: opts.includeClosed
+  });
   const words = trimmed.toLowerCase().split(/\s+/);
   let matched = allTasks.filter((task) => {
     const name = task.name.toLowerCase();
@@ -2067,17 +2097,16 @@ program.command("auth").description("Validate API token and show current user").
   wrapAction(async (opts) => {
     const config = loadConfig();
     const result = await checkAuth(config);
-    if (opts.json || !isTTY()) {
+    if (shouldOutputJson(opts.json ?? false)) {
       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);
+      throw new Error(`Authentication failed: ${result.error ?? "unknown error"}`);
     }
   })
 );
-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(
+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("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     const tasks = await fetchMyTasks(config, {
@@ -2085,12 +2114,13 @@ program.command("tasks").description("List tasks assigned to me").option("--stat
       statuses: opts.status ? [opts.status] : void 0,
       listIds: opts.list ? [opts.list] : void 0,
       spaceIds: opts.space ? [opts.space] : void 0,
-      name: opts.name
+      name: opts.name,
+      includeClosed: opts.includeClosed
     });
     await printTasks(tasks, opts.json ?? false, config);
   })
 );
-program.command("initiatives").description("List initiatives assigned to me").option("--status <status>", "Filter by status").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(
+program.command("initiatives").description("List initiatives assigned to me").option("--status <status>", "Filter by status").option("--list <listId>", "Filter by list ID").option("--space <spaceId>", "Filter by space ID").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     const tasks = await fetchMyTasks(config, {
@@ -2098,7 +2128,8 @@ program.command("initiatives").description("List initiatives assigned to me").op
       statuses: opts.status ? [opts.status] : void 0,
       listIds: opts.list ? [opts.list] : void 0,
       spaceIds: opts.space ? [opts.space] : void 0,
-      name: opts.name
+      name: opts.name,
+      includeClosed: opts.includeClosed
     });
     await printTasks(tasks, opts.json ?? false, config);
   })
@@ -2121,29 +2152,31 @@ program.command("update <taskId>").description("Update a task").option("-n, --na
     const config = loadConfig();
     const payload = buildUpdatePayload(opts);
     const result = await updateTask(config, taskId, payload);
-    if (shouldOutputJson(false)) {
+    if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
     } else {
       console.log(formatUpdateConfirmation(result.id, result.name));
     }
   })
 );
-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("--custom-item-id <id>", "Custom task type ID (use to create initiatives)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--json", "Force JSON output even in terminal").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 (markdown supported)").option("-p, --parent <taskId>", "Parent task ID (list auto-detected from parent)").option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", "Assignee user ID").option("--tags <tags>", "Comma-separated tag names").option("--custom-item-id <id>", "Custom task type ID (use to create initiatives)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     const result = await createTask(config, opts);
-    if (shouldOutputJson(false)) {
+    if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
     } else {
       console.log(formatCreateConfirmation(result.id, result.name, result.url));
     }
   })
 );
-program.command("sprint").description("List my tasks in the current active sprint (auto-detected)").option("--status <status>", "Filter by status").option("--space <nameOrId>", "Narrow sprint search to a specific space (partial name or ID)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    await runSprintCommand(config, opts);
-  })
+program.command("sprint").description("List my tasks in the current active sprint (auto-detected)").option("--status <status>", "Filter by status").option("--space <nameOrId>", "Narrow sprint search to a specific space (partial name or ID)").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (opts) => {
+      const config = loadConfig();
+      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) => {
@@ -2151,18 +2184,28 @@ program.command("sprints").description("List all sprints in sprint folders").opt
     await listSprints(config, opts);
   })
 );
-program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--include-closed", "Include closed/done subtasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const tasks = await fetchSubtasks(config, taskId, { includeClosed: opts.includeClosed });
-    await printTasks(tasks, opts.json ?? false, config);
-  })
+program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--status <status>", "Filter by status").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--include-closed", "Include closed/done subtasks").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (taskId, opts) => {
+      const config = loadConfig();
+      let tasks = await fetchSubtasks(config, taskId, { includeClosed: opts.includeClosed });
+      if (opts.status) {
+        const lower = opts.status.toLowerCase();
+        tasks = tasks.filter((t) => t.status.toLowerCase() === lower);
+      }
+      if (opts.name) {
+        const query = opts.name.toLowerCase();
+        tasks = tasks.filter((t) => t.name.toLowerCase().includes(query));
+      }
+      await printTasks(tasks, opts.json ?? false, config);
+    }
+  )
 );
-program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").action(
+program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
     const result = await postComment(config, taskId, opts.message);
-    if (shouldOutputJson(false)) {
+    if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
     } else {
       console.log(formatCommentConfirmation(result.id));
@@ -2201,14 +2244,13 @@ program.command("inbox").description("Recently updated tasks grouped by time per
     const config = loadConfig();
     const days = Number(opts.days ?? 30);
     if (!Number.isFinite(days) || days <= 0) {
-      console.error("Error: --days must be a positive number");
-      process.exit(1);
+      throw new Error("--days must be a positive number");
     }
     const tasks = await fetchInbox(config, days);
     await printInbox(tasks, opts.json ?? false, config);
   })
 );
-program.command("assigned").description("Show all tasks assigned to me, grouped by status").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
+program.command("assigned").description("Show all tasks assigned to me, grouped by status").option("--status <status>", "Show only tasks with this status").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     await runAssignedCommand(config, opts);
@@ -2220,20 +2262,24 @@ 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("search <query>").description("Search my tasks by name").option("--status <status>", "Filter by status").option("--include-closed", "Include done/closed tasks in search").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,
+        includeClosed: opts.includeClosed
+      });
+      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();
     const hours = Number(opts.hours ?? 24);
     if (!Number.isFinite(hours) || hours <= 0) {
-      console.error("Error: --hours must be a positive number");
-      process.exit(1);
+      throw new Error("--hours must be a positive number");
     }
     await runSummaryCommand(config, { hours, json: opts.json ?? false });
   })

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -34,25 +34,25 @@ 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> [--include-closed] [--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                        |
+| Command                                                                                       | What it returns                                    |
+| --------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `cu tasks [--status s] [--name q] [--list id] [--space id] [--include-closed] [--json]`       | My tasks (workspace-wide)                          |
+| `cu initiatives [--status s] [--name q] [--list id] [--space id] [--include-closed] [--json]` | My initiatives                                     |
+| `cu assigned [--status s] [--include-closed] [--json]`                                        | All my tasks grouped by status                     |
+| `cu sprint [--status s] [--space nameOrId] [--include-closed] [--json]`                       | Tasks in active sprint (auto-detected)             |
+| `cu sprints [--space nameOrId] [--json]`                                                      | List all sprints (marks active with \*)            |
+| `cu search <query> [--status s] [--include-closed] [--json]`                                  | Search my tasks by name (multi-word, fuzzy status) |
+| `cu task <id> [--json]`                                                                       | Single task details                                |
+| `cu subtasks <id> [--status s] [--name q] [--include-closed] [--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
 
@@ -68,32 +68,32 @@ All commands support `--help` for full flag details.
 
 ## 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"`)                                    |
-| `--time-estimate`   | Duration format: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds                  |
-| `--custom-item-id`  | Custom task type ID (e.g. `1` for initiative)                                     |
-| `--on` / `--blocks` | Task dependency direction (used with `cu depend`)                                 |
-| `--space`           | Partial name match or exact ID                                                    |
-| `--name`            | Partial match, case-insensitive                                                   |
-| `--include-closed`  | Include closed/done tasks (on `subtasks` and `assigned`)                          |
-| `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                                        |
+| 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"`)                                                    |
+| `--time-estimate`   | Duration format: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds                                  |
+| `--custom-item-id`  | Custom task type ID (e.g. `1` for initiative)                                                     |
+| `--on` / `--blocks` | Task dependency direction (used with `cu depend`)                                                 |
+| `--space`           | Partial name match or exact ID                                                                    |
+| `--name`            | Partial match, case-insensitive                                                                   |
+| `--include-closed`  | Include closed/done tasks (on `tasks`, `initiatives`, `assigned`, `subtasks`, `sprint`, `search`) |
+| `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