@krodak/clickup-cli 0.8.0 → 0.9.1

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,12 +182,15 @@ 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.
 
 ```bash
 cu subtasks abc123
+cu subtasks abc123 --include-closed
 cu subtasks abc123 --json
 ```
 
@@ -410,10 +416,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

@@ -135,6 +135,7 @@ var ClickUpClient = class {
     const baseParams = new URLSearchParams({
       subtasks: String(filters.subtasks ?? true)
     });
+    if (filters.includeClosed) baseParams.set("include_closed", "true");
     baseParams.append("assignees[]", String(me.id));
     for (const s of filters.statuses ?? []) baseParams.append("statuses[]", s);
     for (const id of filters.listIds ?? []) baseParams.append("list_ids[]", id);
@@ -161,9 +162,11 @@ var ClickUpClient = class {
     const data = await this.request(`/task/${taskId}/comment`);
     return data.comments ?? [];
   }
-  async getTasksFromList(listId, params = {}) {
+  async getTasksFromList(listId, params = {}, options = {}) {
     return this.paginate((page) => {
-      const qs = new URLSearchParams({ subtasks: "true", page: String(page), ...params }).toString();
+      const base = { subtasks: "true", page: String(page), ...params };
+      if (options.includeClosed) base["include_closed"] = "true";
+      const qs = new URLSearchParams(base).toString();
       return `/list/${listId}/task?${qs}`;
     });
   }
@@ -227,6 +230,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 +267,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 +620,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 +905,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 +966,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,
@@ -843,10 +977,14 @@ async function listSprints(config, opts = {}) {
 }
 
 // src/commands/subtasks.ts
-async function fetchSubtasks(config, taskId) {
+async function fetchSubtasks(config, taskId, options = {}) {
   const client = new ClickUpClient(config);
   const parent = await client.getTask(taskId);
-  const tasks = await client.getTasksFromList(parent.list.id, { parent: taskId, subtasks: "false" });
+  const tasks = await client.getTasksFromList(
+    parent.list.id,
+    { parent: taskId, subtasks: "false" },
+    { includeClosed: options.includeClosed }
+  );
   return tasks.map(summarize);
 }
 
@@ -859,7 +997,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 +1017,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 +1033,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 +1062,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 +1137,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 +1147,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 +1186,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 +1199,6 @@ async function listSpaces(config, opts) {
       ]
     );
     console.log(table);
-  } else {
-    console.log(JSON.stringify(spaces, null, 2));
   }
 }
 
@@ -1095,9 +1251,11 @@ function groupByStatus(tasks, includeClosed) {
 }
 async function runAssignedCommand(config, opts) {
   const client = new ClickUpClient(config);
-  const allTasks = await client.getMyTasks(config.teamId);
+  const allTasks = await client.getMyTasks(config.teamId, {
+    includeClosed: opts.includeClosed
+  });
   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 +1263,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 +1296,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 +1320,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 +1393,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 +1487,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 +1529,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 +2041,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 +2055,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 +2066,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));
     }
   })
 );
@@ -1905,10 +2085,10 @@ 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("--json", "Force JSON output even in terminal").action(
+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);
+    const tasks = await fetchSubtasks(config, taskId, { includeClosed: opts.includeClosed });
     await printTasks(tasks, opts.json ?? false, config);
   })
 );
@@ -1916,10 +2096,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 +2183,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.1",
   "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, assigning tasks, listing spaces and lists, opening tasks in browser, checking auth or config.'
 ---
 
 # 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 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 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,85 @@ 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                                                   |
+| `--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                                        |
+
+## 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 (open only)
+cu subtasks abc123def --include-closed  # all 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 spaces --name "Engineering"      # find space ID by name
+cu lists <spaceId>                  # lists in a space (needs ID from cu spaces)
+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
 ```