@krodak/clickup-cli 0.8.0 → 0.9.0

package/README.md

@@ -1,15 +1,18 @@
 # cu - ClickUp CLI
 
-A ClickUp CLI built for AI agents that also works well for humans. Outputs JSON when piped, interactive tables when run in a terminal.
+> A ClickUp CLI built for AI agents that also works well for humans. Outputs Markdown when piped (optimized for AI context windows), interactive tables when run in a terminal.
 
-## Quick start
+[![npm](https://img.shields.io/npm/v/@krodak/clickup-cli)](https://www.npmjs.com/package/@krodak/clickup-cli)
+[![node](https://img.shields.io/node/v/@krodak/clickup-cli)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@krodak/clickup-cli)](./LICENSE)
+[![CI](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml)
 
 ```bash
 npm install -g @krodak/clickup-cli   # or: brew tap krodak/tap && brew install clickup-cli
 cu init                               # walks you through API token + workspace setup
 ```
 
-You need Node 22+ and a ClickUp personal API token (`pk_...` from https://app.clickup.com/settings/apps).
+You need a ClickUp personal API token (`pk_...` from https://app.clickup.com/settings/apps).
 
 ## Using with AI agents
 
@@ -89,9 +92,9 @@ cu update abc123 -s "done"        # update status
 cu assign abc123 --to me          # assign yourself
 ```
 
-Pass `--json` to any command to get raw JSON output instead of the interactive UI.
+Pass `--json` to any read command to force JSON output instead of the default format.
 
-When output is piped (no TTY), all commands automatically output JSON. All commands support `--json` to force JSON output even in a terminal.
+When output is piped (no TTY), all commands output **Markdown** by default - optimized for AI agent context windows. Pass `--json` to any command for JSON output. Set `CU_OUTPUT=json` environment variable to always get JSON when piped.
 
 ## Commands
 
@@ -179,6 +182,8 @@ cu task abc123
 cu task abc123 --json
 ```
 
+**Note:** When piped, `cu task` outputs a structured Markdown summary of the task. For the full raw API response with all fields (custom fields, checklists, etc.), use `--json`.
+
 ### `cu subtasks <id>`
 
 List subtasks of a task or initiative.
@@ -410,10 +415,11 @@ cu completion fish > ~/.config/fish/completions/cu.fish          # Fish
 
 Environment variables override config file values:
 
-| Variable       | Description                        |
-| -------------- | ---------------------------------- |
-| `CU_API_TOKEN` | ClickUp personal API token (`pk_`) |
-| `CU_TEAM_ID`   | Workspace (team) ID                |
+| Variable       | Description                                                       |
+| -------------- | ----------------------------------------------------------------- |
+| `CU_API_TOKEN` | ClickUp personal API token (`pk_`)                                |
+| `CU_TEAM_ID`   | Workspace (team) ID                                               |
+| `CU_OUTPUT`    | Set to `json` to force JSON output when piped (default: markdown) |
 
 When both are set, the config file is not required. Useful for CI/CD and containerized agents.
 

package/dist/index.js

@@ -227,6 +227,11 @@ import chalk from "chalk";
 function isTTY() {
   return Boolean(process.stdout.isTTY);
 }
+function shouldOutputJson(forceJson) {
+  if (forceJson) return true;
+  if (process.env["CU_OUTPUT"] === "json") return true;
+  return false;
+}
 function cell(value, width) {
   if (value.length > width) return value.slice(0, width - 1) + "\u2026";
   return value.padEnd(width);
@@ -259,6 +264,128 @@ var TASK_COLUMNS = [
   { key: "list", label: "LIST" }
 ];
 
+// src/markdown.ts
+function escapeCell(value) {
+  return value.replace(/\|/g, "\\|");
+}
+function formatMarkdownTable(rows, columns) {
+  const header = "| " + columns.map((c) => c.label).join(" | ") + " |";
+  const divider = "| " + columns.map(() => "---").join(" | ") + " |";
+  const lines = [header, divider];
+  for (const row of rows) {
+    const cells = columns.map((c) => escapeCell(String(row[c.key] ?? "")));
+    lines.push("| " + cells.join(" | ") + " |");
+  }
+  return lines.join("\n");
+}
+var TASK_MD_COLUMNS = [
+  { key: "id", label: "ID" },
+  { key: "name", label: "Name" },
+  { key: "status", label: "Status" },
+  { key: "list", label: "List" }
+];
+function formatTasksMarkdown(tasks) {
+  if (tasks.length === 0) return "No tasks found.";
+  return formatMarkdownTable(tasks, TASK_MD_COLUMNS);
+}
+function formatCommentsMarkdown(comments) {
+  if (comments.length === 0) return "No comments found.";
+  return comments.map((c) => `**${c.user}** (${c.date})
+
+${c.text}`).join("\n\n---\n\n");
+}
+var LIST_MD_COLUMNS = [
+  { key: "id", label: "ID" },
+  { key: "name", label: "Name" },
+  { key: "folder", label: "Folder" }
+];
+function formatListsMarkdown(lists) {
+  if (lists.length === 0) return "No lists found.";
+  return formatMarkdownTable(lists, LIST_MD_COLUMNS);
+}
+var SPACE_MD_COLUMNS = [
+  { key: "id", label: "ID" },
+  { key: "name", label: "Name" }
+];
+function formatSpacesMarkdown(spaces) {
+  if (spaces.length === 0) return "No spaces found.";
+  return formatMarkdownTable(spaces, SPACE_MD_COLUMNS);
+}
+function formatGroupedTasksMarkdown(groups) {
+  const sections = groups.filter((g) => g.tasks.length > 0).map((g) => `## ${g.label}
+
+${formatMarkdownTable(g.tasks, TASK_MD_COLUMNS)}`);
+  if (sections.length === 0) return "No tasks found.";
+  return sections.join("\n\n");
+}
+function formatDate(ms) {
+  const d = new Date(Number(ms));
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function formatDuration(ms) {
+  const totalMinutes = Math.floor(ms / 6e4);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return `${hours}h ${minutes}m`;
+}
+function formatTaskDetailMarkdown(task) {
+  const lines = [`# ${task.name}`, ""];
+  const isInitiative2 = (task.custom_item_id ?? 0) !== 0;
+  const fields = [
+    ["ID", task.id],
+    ["Status", task.status.status],
+    ["Type", isInitiative2 ? "initiative" : "task"],
+    ["List", task.list.name],
+    ["URL", task.url],
+    [
+      "Assignees",
+      task.assignees.length > 0 ? task.assignees.map((a) => a.username).join(", ") : void 0
+    ],
+    ["Priority", task.priority?.priority],
+    ["Parent", task.parent ?? void 0],
+    ["Start Date", task.start_date ? formatDate(task.start_date) : void 0],
+    ["Due Date", task.due_date ? formatDate(task.due_date) : void 0],
+    [
+      "Time Estimate",
+      task.time_estimate != null && task.time_estimate > 0 ? formatDuration(task.time_estimate) : void 0
+    ],
+    [
+      "Time Spent",
+      task.time_spent != null && task.time_spent > 0 ? formatDuration(task.time_spent) : void 0
+    ],
+    ["Tags", task.tags && task.tags.length > 0 ? task.tags.map((t) => t.name).join(", ") : void 0],
+    ["Created", task.date_created ? formatDate(task.date_created) : void 0],
+    ["Updated", task.date_updated ? formatDate(task.date_updated) : void 0]
+  ];
+  for (const [label, value] of fields) {
+    if (value != null && value !== "") {
+      lines.push(`**${label}:** ${value}`);
+    }
+  }
+  if (task.description) {
+    lines.push("", "## Description", "", task.description);
+  }
+  return lines.join("\n");
+}
+function formatUpdateConfirmation(id, name) {
+  return `Updated task ${id}: "${name}"`;
+}
+function formatCreateConfirmation(id, name, url) {
+  return `Created task ${id}: "${name}" - ${url}`;
+}
+function formatCommentConfirmation(id) {
+  return `Comment posted (id: ${id})`;
+}
+function formatAssignConfirmation(taskId, opts) {
+  const parts = [];
+  if (opts.to) parts.push(`Assigned ${opts.to} to ${taskId}`);
+  if (opts.remove) parts.push(`Removed ${opts.remove} from ${taskId}`);
+  return parts.join("; ");
+}
+
 // src/interactive.ts
 import { execFileSync } from "child_process";
 import { checkbox, confirm, Separator } from "@inquirer/prompts";
@@ -490,10 +617,14 @@ async function fetchMyTasks(config, opts = {}) {
   return filtered.map(summarize);
 }
 async function printTasks(tasks, forceJson, config) {
-  if (forceJson || !isTTY()) {
+  if (shouldOutputJson(forceJson)) {
     console.log(JSON.stringify(tasks, null, 2));
     return;
   }
+  if (!isTTY()) {
+    console.log(formatTasksMarkdown(tasks));
+    return;
+  }
   if (tasks.length === 0) {
     console.log("No tasks found.");
     return;
@@ -771,7 +902,7 @@ var SPRINT_COLUMNS = [
   { key: "sprint", label: "SPRINT", maxWidth: 60 },
   { key: "dates", label: "DATES" }
 ];
-function formatDate(d) {
+function formatDate2(d) {
   return `${d.getMonth() + 1}/${d.getDate()}`;
 }
 function buildSprintInfos(lists, folderName, today) {
@@ -832,7 +963,7 @@ async function listSprints(config, opts = {}) {
   }
   const rows = allSprints.map((s) => {
     const dates = parseSprintDates(s.name);
-    const dateStr = dates ? `${formatDate(dates.start)} - ${formatDate(dates.end)}` : "";
+    const dateStr = dates ? `${formatDate2(dates.start)} - ${formatDate2(dates.end)}` : "";
     return {
       id: s.id,
       sprint: s.active ? `* ${s.name}` : s.name,
@@ -859,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",
@@ -879,10 +1010,14 @@ async function fetchComments(config, taskId) {
   }));
 }
 function printComments(comments, forceJson) {
-  if (forceJson || !isTTY()) {
+  if (shouldOutputJson(forceJson)) {
     console.log(JSON.stringify(comments, null, 2));
     return;
   }
+  if (!isTTY()) {
+    console.log(formatCommentsMarkdown(comments));
+    return;
+  }
   if (comments.length === 0) {
     console.log("No comments found.");
     return;
@@ -891,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("");
   }
@@ -920,10 +1055,14 @@ async function fetchLists(config, spaceId, opts = {}) {
   return results;
 }
 function printLists(lists, forceJson) {
-  if (forceJson || !isTTY()) {
+  if (shouldOutputJson(forceJson)) {
     console.log(JSON.stringify(lists, null, 2));
     return;
   }
+  if (!isTTY()) {
+    console.log(formatListsMarkdown(lists));
+    return;
+  }
   if (lists.length === 0) {
     console.log("No lists found.");
     return;
@@ -991,7 +1130,7 @@ async function fetchInbox(config, days = 30) {
 async function printInbox(tasks, forceJson, config) {
   const now = Date.now();
   const groups = groupTasks(tasks, now);
-  if (forceJson || !isTTY()) {
+  if (shouldOutputJson(forceJson)) {
     const jsonGroups = {};
     for (const { key } of TIME_PERIODS) {
       if (groups[key].length > 0) {
@@ -1001,6 +1140,14 @@ async function printInbox(tasks, forceJson, config) {
     console.log(JSON.stringify(jsonGroups, null, 2));
     return;
   }
+  if (!isTTY()) {
+    const mdGroups = TIME_PERIODS.filter((p) => groups[p.key].length > 0).map((p) => ({
+      label: p.label,
+      tasks: groups[p.key]
+    }));
+    console.log(formatGroupedTasksMarkdown(mdGroups));
+    return;
+  }
   if (tasks.length === 0) {
     console.log("No recently updated tasks.");
     return;
@@ -1032,7 +1179,11 @@ async function listSpaces(config, opts) {
     );
     spaces = spaces.filter((s) => mySpaceIds.has(s.id));
   }
-  if (!opts.json && isTTY()) {
+  if (shouldOutputJson(opts.json ?? false)) {
+    console.log(JSON.stringify(spaces, null, 2));
+  } else if (!isTTY()) {
+    console.log(formatSpacesMarkdown(spaces.map((s) => ({ id: s.id, name: s.name }))));
+  } else {
     const table = formatTable(
       spaces.map((s) => ({ id: s.id, name: s.name })),
       [
@@ -1041,8 +1192,6 @@ async function listSpaces(config, opts) {
       ]
     );
     console.log(table);
-  } else {
-    console.log(JSON.stringify(spaces, null, 2));
   }
 }
 
@@ -1097,7 +1246,7 @@ async function runAssignedCommand(config, opts) {
   const client = new ClickUpClient(config);
   const allTasks = await client.getMyTasks(config.teamId);
   const groups = groupByStatus(allTasks, opts.includeClosed ?? false);
-  if (opts.json || !isTTY()) {
+  if (shouldOutputJson(opts.json ?? false)) {
     const result = {};
     for (const group of groups) {
       result[group.status.toLowerCase()] = group.tasks.map((t) => toJsonTask(t, summarize(t)));
@@ -1105,6 +1254,14 @@ async function runAssignedCommand(config, opts) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
+  if (!isTTY()) {
+    const mdGroups = groups.map((g) => ({
+      label: g.status,
+      tasks: g.tasks.map((t) => summarize(t))
+    }));
+    console.log(formatGroupedTasksMarkdown(mdGroups));
+    return;
+  }
   if (groups.length === 0) {
     console.log("No tasks found.");
     return;
@@ -1130,13 +1287,13 @@ async function openTask(config, query, opts = {}) {
     } catch {
     }
     if (task) {
-      if (opts.json) {
+      if (shouldOutputJson(opts.json ?? false)) {
         console.log(JSON.stringify(task, null, 2));
+      } else if (!isTTY()) {
+        console.log(formatTaskDetailMarkdown(task));
       } else {
-        if (isTTY()) {
-          console.log(task.name);
-          console.log(task.url);
-        }
+        console.log(task.name);
+        console.log(task.url);
         openUrl(task.url);
       }
       return task;
@@ -1154,15 +1311,18 @@ async function openTask(config, query, opts = {}) {
     }
     console.log("Opening first match...");
   }
-  if (opts.json) {
+  if (shouldOutputJson(opts.json ?? false)) {
     const fullTask = await client.getTask(first.id);
     console.log(JSON.stringify(fullTask, null, 2));
     return fullTask;
   }
-  if (isTTY()) {
-    console.log(first.name);
-    console.log(first.url);
+  if (!isTTY()) {
+    const fullTask = await client.getTask(first.id);
+    console.log(formatTaskDetailMarkdown(fullTask));
+    return fullTask;
   }
+  console.log(first.name);
+  console.log(first.url);
   openUrl(first.url);
   return {
     id: first.id,
@@ -1224,10 +1384,19 @@ async function runSummaryCommand(config, opts) {
   const client = new ClickUpClient(config);
   const allTasks = await client.getMyTasks(config.teamId);
   const result = categorizeTasks(allTasks, opts.hours);
-  if (opts.json || !isTTY()) {
+  if (shouldOutputJson(opts.json)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
+  if (!isTTY()) {
+    const mdGroups = [
+      { label: "Completed Recently", tasks: result.completed },
+      { label: "In Progress", tasks: result.inProgress },
+      { label: "Overdue", tasks: result.overdue }
+    ];
+    console.log(formatGroupedTasksMarkdown(mdGroups));
+    return;
+  }
   printSection("Completed Recently", result.completed);
   printSection("In Progress", result.inProgress);
   printSection("Overdue", result.overdue);
@@ -1309,7 +1478,7 @@ async function assignTask(config, taskId, opts) {
 
 // src/commands/activity.ts
 import chalk4 from "chalk";
-function formatDate3(timestamp) {
+function formatDate4(timestamp) {
   return new Date(Number(timestamp)).toLocaleString("en-US", {
     month: "short",
     day: "numeric",
@@ -1351,7 +1520,7 @@ function printActivity(result, forceJson) {
       console.log("");
       console.log(chalk4.dim("-".repeat(60)));
     }
-    console.log(`${chalk4.bold(c.user)}  ${chalk4.dim(formatDate3(c.date))}`);
+    console.log(`${chalk4.bold(c.user)}  ${chalk4.dim(formatDate4(c.date))}`);
     console.log(c.text);
   }
 }
@@ -1863,8 +2032,10 @@ program.command("task <taskId>").description("Get task details").option("--json"
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
     const result = await getTask(config, taskId);
-    if (opts.json || !isTTY()) {
+    if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
+    } else if (!isTTY()) {
+      console.log(formatTaskDetailMarkdown(result));
     } else {
       console.log(formatTaskDetail(result));
     }
@@ -1875,10 +2046,10 @@ 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 (opts.json || !isTTY()) {
+    if (shouldOutputJson(false)) {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      console.log(`Updated task ${result.id}: "${result.name}"`);
+      console.log(formatUpdateConfirmation(result.id, result.name));
     }
   })
 );
@@ -1886,10 +2057,10 @@ program.command("create").description("Create a new task").option("-l, --list <l
   wrapAction(async (opts) => {
     const config = loadConfig();
     const result = await createTask(config, opts);
-    if (opts.json || !isTTY()) {
+    if (shouldOutputJson(false)) {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      console.log(`Created task ${result.id}: "${result.name}" - ${result.url}`);
+      console.log(formatCreateConfirmation(result.id, result.name, result.url));
     }
   })
 );
@@ -1916,10 +2087,10 @@ program.command("comment <taskId>").description("Post a comment on a task").requ
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
     const result = await postComment(config, taskId, opts.message);
-    if (isTTY()) {
-      console.log(`Comment posted (id: ${result.id})`);
-    } else {
+    if (shouldOutputJson(false)) {
       console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatCommentConfirmation(result.id));
     }
   })
 );
@@ -2003,13 +2174,10 @@ program.command("assign <taskId>").description("Assign or unassign users from a
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
     const result = await assignTask(config, taskId, opts);
-    if (opts.json || !isTTY()) {
+    if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      const parts = [];
-      if (opts.to) parts.push(`Assigned ${opts.to} to task ${taskId}`);
-      if (opts.remove) parts.push(`Removed ${opts.remove} from task ${taskId}`);
-      console.log(parts.join("; "));
+      console.log(formatAssignConfirmation(taskId, { to: opts.to, remove: opts.remove }));
     }
   })
 );

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -1,19 +1,32 @@
 ---
 name: clickup
-description: 'Use when managing ClickUp tasks, initiatives, sprints, or comments via the `cu` CLI tool. Covers task queries, status updates, sprint tracking, and project management workflows.'
+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` command-line tool to interact with ClickUp. Covers task management, sprint tracking, initiatives, and comments.
+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
+Keywords: ClickUp, task management, sprint, initiative, project management, agile, backlog, subtasks, standup, overdue, search
 
 ## Setup
 
-Config at `~/.config/cu/config.json` (or `$XDG_CONFIG_HOME/cu/config.json`) with `apiToken` and `teamId`. Run `cu init` to set up.
+Config at `~/.config/cu/config.json` with `apiToken` and `teamId`. Run `cu init` to set up interactively.
 
-Alternatively, set `CU_API_TOKEN` and `CU_TEAM_ID` environment variables (overrides config file, no file needed when both are set).
+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
 
@@ -27,19 +40,19 @@ All commands support `--help` for full flag details.
 | `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 inbox [--days n] [--json]`                                             | Tasks updated in last n days (default 30)          |
+| `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]`                                                | List comments on a task                            |
-| `cu spaces [--name partial] [--my] [--json]`                               | List/filter workspace spaces                       |
-| `cu lists <spaceId> [--name partial] [--json]`                             | List all lists in a space (including folder lists) |
-| `cu open <query> [--json]`                                                 | Open task in browser by ID or name                 |
+| `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 search <query> [--status s] [--json]`                                  | Search my tasks by name (multi-word, fuzzy status) |
-| `cu activity <id> [--json]`                                                | Task details + comment history combined            |
+| `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                        |
-| `cu sprints [--space nameOrId] [--json]`                                   | List all sprints (marks active with \*)            |
 
 ### Write
 
@@ -48,102 +61,82 @@ All commands support `--help` for full flag details.
 | `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 from a 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>`                                                                                                               | Output shell completions (bash/zsh/fish)     |
-
-## Output modes
-
-- **TTY (terminal)**: Interactive picker UI. Use `--json` to bypass.
-- **Piped / non-TTY**: Always JSON. This is what agents get by default.
-- **Agents should always pass `--json`** to guarantee machine-readable output.
-- Set `NO_COLOR` to disable color output (tables still render, just without color).
-
-## Key facts
-
-- All task IDs are stable alphanumeric strings (e.g. `abc123def`)
-- Initiatives are detected via `custom_item_id !== 0` (not `task_type`)
-- `--list` is optional in `cu create` when `--parent` is given (list auto-detected from parent)
-- `cu sprint` auto-detects active sprint from spaces where user has tasks, using view API and date range parsing from sprint names like "Acme Sprint 4 (3/1 - 3/14)"
-- `--name` on tasks/initiatives filters by partial name match (case-insensitive)
-- `--space` on sprint/tasks accepts partial name match (e.g. `--space Acm`)
-- `--priority` accepts names (`urgent`, `high`, `normal`, `low`) or numbers (1-4)
-- `--due-date` accepts `YYYY-MM-DD` format
-- `--assignee` takes a numeric user ID (use `cu task <id> --json` to find assignee IDs)
-- `cu assign` supports `me` as a shorthand for your own user ID
-- `cu open` tries task ID lookup first, then falls back to name search
-- `cu summary` categories: completed (done/complete/closed within N hours), in progress, overdue
-- `cu overdue` excludes done/complete/closed tasks, sorted most overdue first
-- `--tags` accepts comma-separated tag names (e.g. `--tags "bug,frontend"`)
-- `cu lists <spaceId>` discovers list IDs needed for `--list` and `cu create -l`
-- Strict argument parsing - excess/unknown arguments are rejected
-- `cu update -s` supports fuzzy status matching (exact > starts-with > contains). Prints matched status to stderr when fuzzy-resolved.
-- `cu task` shows custom fields in detail view (read-only)
-- `cu search` matches all query words against task name (case-insensitive). `--status` supports fuzzy matching.
-- Errors go to stderr with exit code 1
-
-## Agent workflow example
+| `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
-# List my in-progress tasks
-cu tasks --status "in progress" --json
-
-# Find tasks by partial name
-cu tasks --name "login" --json
-
-# Check current sprint
-cu sprint --json | jq '.[].name'
+cu task abc123def                   # markdown summary
+cu subtasks abc123def               # child tasks
+cu comments abc123def               # discussion
+cu activity abc123def               # task + comments combined
+```
 
-# Get full details on a task
-cu task abc123def --json
+### Find tasks
 
-# List subtasks of an initiative
-cu subtasks abc123def --json
+```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
+```
 
-# Read comments on a task
-cu comments abc123def --json
+### Make changes
 
-# Update task status
+```bash
 cu update abc123def -s "done"
-
-# Update priority and due date
 cu update abc123def --priority high --due-date 2025-03-15
-
-# Create subtask under initiative (no --list needed)
 cu create -n "Fix the thing" -p abc123def
-
-# Create task with priority and tags
 cu create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
-
-# Post a comment
 cu comment abc123def -m "Completed in PR #42"
-
-# Discover lists in a space
-cu lists <spaceId> --json
-
-# Open a task in the browser
-cu open abc123def
-
-# Standup summary
-cu summary --json
-
-# Check overdue tasks
-cu overdue --json
-
-# Assign yourself to a task
 cu assign abc123def --to me
+```
 
-# Check/set config
-cu config get teamId
-cu config set apiToken pk_example_token
-
-cu search "login bug" --json
-
-cu activity abc123def --json
+### Discover workspace structure
 
-cu auth --json
+```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
+```
 
-cu sprints --json
+### Standup
 
-cu update abc123def -s "prog"
+```bash
+cu summary                          # completed / in progress / overdue
+cu summary --hours 48               # wider window
 ```