@krodak/clickup-cli 0.21.0 → 1.0.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup-cli",
   "description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cup command",
-  "version": "0.21.0",
+  "version": "1.0.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -162,14 +162,14 @@ Status: :white_check_mark: implemented | :construction: planned | :no_entry_sign
 
 ### Sprints & Planning
 
-| Feature                  | Command        | Status             |
-| ------------------------ | -------------- | ------------------ |
-| Active sprint tasks      | `cup sprint`   | :white_check_mark: |
-| List all sprints         | `cup sprints`  | :white_check_mark: |
-| Assigned tasks by status | `cup assigned` | :white_check_mark: |
-| Standup summary          | `cup summary`  | :white_check_mark: |
-| Overdue tasks            | `cup overdue`  | :white_check_mark: |
-| Recently updated         | `cup inbox`    | :white_check_mark: |
+| Feature                  | Command                 | Status             |
+| ------------------------ | ----------------------- | ------------------ |
+| Active sprint tasks      | `cup sprint [--folder]` | :white_check_mark: |
+| List all sprints         | `cup sprints`           | :white_check_mark: |
+| Assigned tasks by status | `cup assigned`          | :white_check_mark: |
+| Standup summary          | `cup summary`           | :white_check_mark: |
+| Overdue tasks            | `cup overdue`           | :white_check_mark: |
+| Recently updated         | `cup inbox`             | :white_check_mark: |
 
 ### Comments
 
@@ -299,12 +299,13 @@ Most commands scope to your assigned tasks by default - keeping output small and
 
 ### Config file
 
-`~/.config/cu/config.json` (or `$XDG_CONFIG_HOME/cu/config.json`):
+`~/.config/cup/config.json` (or `$XDG_CONFIG_HOME/cup/config.json`):
 
 ```json
 {
   "apiToken": "pk_...",
-  "teamId": "12345678"
+  "teamId": "12345678",
+  "sprintFolderId": "optional - folder ID to skip auto-detection"
 }
 ```
 

package/dist/index.js

@@ -390,18 +390,36 @@ import fs from "fs";
 import { homedir } from "os";
 import { join } from "path";
 function configDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg) return join(xdg, "cup");
+  return join(homedir(), ".config", "cup");
+}
+function legacyConfigDir() {
   const xdg = process.env.XDG_CONFIG_HOME;
   if (xdg) return join(xdg, "cu");
   return join(homedir(), ".config", "cu");
 }
+var migrationChecked = false;
+function migrateFromLegacy() {
+  if (migrationChecked) return;
+  migrationChecked = true;
+  const legacy = legacyConfigDir();
+  const current = configDir();
+  if (fs.existsSync(join(legacy, "config.json")) && !fs.existsSync(join(current, "config.json"))) {
+    fs.mkdirSync(current, { recursive: true, mode: 448 });
+    fs.copyFileSync(join(legacy, "config.json"), join(current, "config.json"));
+  }
+}
 function configPath() {
   return join(configDir(), "config.json");
 }
 function loadConfig() {
+  migrateFromLegacy();
   const envToken = process.env.CU_API_TOKEN?.trim();
   const envTeamId = process.env.CU_TEAM_ID?.trim();
   let fileToken;
   let fileTeamId;
+  let fileSprintFolderId;
   const path = configPath();
   if (fs.existsSync(path)) {
     const raw = fs.readFileSync(path, "utf-8");
@@ -413,6 +431,7 @@ function loadConfig() {
     }
     fileToken = parsed.apiToken?.trim();
     fileTeamId = parsed.teamId?.trim();
+    fileSprintFolderId = parsed.sprintFolderId?.trim() || void 0;
   }
   const apiToken = envToken || fileToken;
   if (!apiToken) {
@@ -425,9 +444,10 @@ function loadConfig() {
   if (!teamId) {
     throw new Error("Config missing required field: teamId.\nSet CU_TEAM_ID or run: cup init");
   }
-  return { apiToken, teamId };
+  return { apiToken, teamId, ...fileSprintFolderId ? { sprintFolderId: fileSprintFolderId } : {} };
 }
 function loadRawConfig() {
+  migrateFromLegacy();
   const path = configPath();
   if (!fs.existsSync(path)) return {};
   try {
@@ -437,6 +457,7 @@ function loadRawConfig() {
   }
 }
 function getConfigPath() {
+  migrateFromLegacy();
   return configPath();
 }
 function writeConfig(config) {
@@ -453,10 +474,33 @@ function writeConfig(config) {
 
 // src/date.ts
 function formatDate(ms) {
+  return new Date(Number(ms)).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric"
+  });
+}
+function formatTimestamp(ms) {
+  return new Date(Number(ms)).toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit"
+  });
+}
+function formatDuration(ms) {
+  const totalMinutes = Math.round(Math.abs(ms) / 6e4);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours > 0 && minutes > 0) return `${hours}h ${minutes}m`;
+  if (hours > 0) return `${hours}h`;
+  return `${minutes}m`;
+}
+function formatDateISO(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");
+  const year = d.getFullYear();
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
   return `${year}-${month}-${day}`;
 }
 
@@ -560,12 +604,6 @@ ${formatMarkdownTable(g.tasks, TASK_MD_COLUMNS)}`);
   if (sections.length === 0) return "No tasks found.";
   return sections.join("\n\n");
 }
-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 isInitiative = (task.custom_item_id ?? 0) !== 0;
@@ -581,8 +619,8 @@ function formatTaskDetailMarkdown(task) {
     ],
     ["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],
+    ["Start Date", task.start_date ? formatDateISO(task.start_date) : void 0],
+    ["Due Date", task.due_date ? formatDateISO(task.due_date) : void 0],
     [
       "Time Estimate",
       task.time_estimate != null && task.time_estimate > 0 ? formatDuration(task.time_estimate) : void 0
@@ -592,8 +630,8 @@ function formatTaskDetailMarkdown(task) {
       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]
+    ["Created", task.date_created ? formatDateISO(task.date_created) : void 0],
+    ["Updated", task.date_updated ? formatDateISO(task.date_updated) : void 0]
   ];
   for (const [label, value] of fields) {
     if (value != null && value !== "") {
@@ -673,20 +711,6 @@ function openUrl(url) {
 `);
   }
 }
-function formatMs(ms) {
-  const hours = Math.floor(ms / 36e5);
-  const mins = Math.floor(ms % 36e5 / 6e4);
-  if (hours > 0 && mins > 0) return `${hours}h ${mins}m`;
-  if (hours > 0) return `${hours}h`;
-  return `${mins}m`;
-}
-function formatTimestamp(ts) {
-  return new Date(Number(ts)).toLocaleDateString("en-US", {
-    month: "short",
-    day: "numeric",
-    year: "numeric"
-  });
-}
 function descriptionPreview(text, maxLines = 3) {
   const lines = text.split("\n").filter((l) => l.trim().length > 0);
   const preview = lines.slice(0, maxLines);
@@ -746,10 +770,10 @@ function formatTaskDetail(task) {
       task.assignees?.length ? task.assignees.map((a) => a.username).join(", ") : void 0
     ],
     ["Priority", task.priority?.priority],
-    ["Start", task.start_date ? formatTimestamp(task.start_date) : void 0],
-    ["Due", task.due_date ? formatTimestamp(task.due_date) : void 0],
-    ["Estimate", task.time_estimate ? formatMs(task.time_estimate) : void 0],
-    ["Tracked", task.time_spent ? formatMs(task.time_spent) : void 0],
+    ["Start", task.start_date ? formatDate(task.start_date) : void 0],
+    ["Due", task.due_date ? formatDate(task.due_date) : void 0],
+    ["Estimate", task.time_estimate ? formatDuration(task.time_estimate) : void 0],
+    ["Tracked", task.time_spent ? formatDuration(task.time_spent) : void 0],
     ["Tags", task.tags?.length ? task.tags.map((t) => t.name).join(", ") : void 0],
     ["Parent", task.parent || void 0],
     ["URL", task.url]
@@ -1004,7 +1028,8 @@ function parseDueDate(value) {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
     throw new Error("Date must be in YYYY-MM-DD format");
   }
-  const date = new Date(value);
+  const parts = value.split("-");
+  const date = new Date(Number(parts[0]), Number(parts[1]) - 1, Number(parts[2]));
   if (isNaN(date.getTime())) throw new Error(`Invalid date: ${value}`);
   return date.getTime();
 }
@@ -1180,23 +1205,75 @@ async function runInitCommand() {
 }
 
 // src/commands/sprint.ts
-function parseSprintDates(name) {
+import { select as select2 } from "@inquirer/prompts";
+var SPRINT_KEYWORDS = ["sprint", "iteration", "cycle", "scrum"];
+function parseUSDateRange(name) {
   const m = name.match(/\((\d{1,2})\/(\d{1,2})\s*[-–]\s*(\d{1,2})\/(\d{1,2})\)/);
   if (!m) return null;
   const year = (/* @__PURE__ */ new Date()).getFullYear();
   const start = new Date(year, Number(m[1]) - 1, Number(m[2]));
   const end = new Date(year, Number(m[3]) - 1, Number(m[4]), 23, 59, 59);
-  if (end < start) {
-    end.setFullYear(end.getFullYear() + 1);
-  }
+  if (end < start) end.setFullYear(end.getFullYear() + 1);
   return { start, end };
 }
+function parseISODateRange(name) {
+  const m = name.match(/\((\d{4}-\d{2}-\d{2})\s*[-–]\s*(\d{4}-\d{2}-\d{2})\)/);
+  if (!m) return null;
+  const [sy, sm, sd] = m[1].split("-").map(Number);
+  const [ey, em, ed] = m[2].split("-").map(Number);
+  const start = new Date(sy, sm - 1, sd);
+  const end = new Date(ey, em - 1, ed, 23, 59, 59);
+  return { start, end };
+}
+function parseMonthDayRange(name) {
+  const months = {
+    jan: 0,
+    feb: 1,
+    mar: 2,
+    apr: 3,
+    may: 4,
+    jun: 5,
+    jul: 6,
+    aug: 7,
+    sep: 8,
+    oct: 9,
+    nov: 10,
+    dec: 11
+  };
+  const m = name.match(/\(([A-Za-z]{3})\s+(\d{1,2})\s*[-–]\s*([A-Za-z]{3})\s+(\d{1,2})\)/);
+  if (!m) return null;
+  const sm = months[m[1].toLowerCase()];
+  const em = months[m[3].toLowerCase()];
+  if (sm === void 0 || em === void 0) return null;
+  const year = (/* @__PURE__ */ new Date()).getFullYear();
+  const start = new Date(year, sm, Number(m[2]));
+  const end = new Date(year, em, Number(m[4]), 23, 59, 59);
+  if (end < start) end.setFullYear(end.getFullYear() + 1);
+  return { start, end };
+}
+function parseEuropeanDateRange(name) {
+  const m = name.match(/\((\d{1,2})\.(\d{1,2})\s*[-–]\s*(\d{1,2})\.(\d{1,2})\)/);
+  if (!m) return null;
+  const year = (/* @__PURE__ */ new Date()).getFullYear();
+  const start = new Date(year, Number(m[2]) - 1, Number(m[1]));
+  const end = new Date(year, Number(m[4]) - 1, Number(m[3]), 23, 59, 59);
+  if (end < start) end.setFullYear(end.getFullYear() + 1);
+  return { start, end };
+}
+function parseSprintDates(name) {
+  return parseUSDateRange(name) ?? parseISODateRange(name) ?? parseMonthDayRange(name) ?? parseEuropeanDateRange(name);
+}
 function findActiveSprintList(lists, today = /* @__PURE__ */ new Date()) {
   if (lists.length === 0) return null;
   for (const list of lists) {
     const dates = parseSprintDates(list.name);
-    if (dates && today >= dates.start && today <= dates.end) {
-      return list;
+    if (dates && today >= dates.start && today <= dates.end) return list;
+  }
+  for (const list of lists) {
+    if (list.start_date && list.due_date) {
+      const start = new Date(Number(list.start_date));
+      const end = new Date(Number(list.due_date));
+      if (today >= start && today <= end) return list;
     }
   }
   return lists[lists.length - 1] ?? null;
@@ -1216,37 +1293,67 @@ function findRelatedSpaces(mySpaceIds, allSpaces) {
 async function runSprintCommand(config, opts) {
   const client = new ClickUpClient(config);
   process.stderr.write("Detecting active sprint...\n");
+  const folderId = opts.folder ?? config.sprintFolderId;
   const [myTasks, allSpaces, customTypes] = await Promise.all([
     client.getMyTasks(config.teamId),
-    client.getSpaces(config.teamId),
+    folderId ? Promise.resolve([]) : client.getSpaces(config.teamId),
     client.getCustomTaskTypes(config.teamId)
   ]);
   const typeMap = buildTypeMap(customTypes);
-  let spaces;
-  if (opts.space) {
-    spaces = allSpaces.filter(
-      (s) => s.name.toLowerCase().includes(opts.space.toLowerCase()) || s.id === opts.space
-    );
-    if (spaces.length === 0) {
-      throw new Error(
-        `No space matching "${opts.space}" found. Use \`cu spaces\` to list available spaces.`
+  let sprintLists;
+  if (folderId) {
+    sprintLists = await client.getFolderLists(folderId);
+  } else {
+    let spaces;
+    if (opts.space) {
+      spaces = allSpaces.filter(
+        (s) => s.name.toLowerCase().includes(opts.space.toLowerCase()) || s.id === opts.space
+      );
+      if (spaces.length === 0) {
+        throw new Error(
+          `No space matching "${opts.space}" found. Use \`cup spaces\` to list available spaces.`
+        );
+      }
+    } else {
+      const mySpaceIds = new Set(
+        myTasks.map((t) => t.space?.id).filter((id) => Boolean(id))
       );
+      spaces = findRelatedSpaces(mySpaceIds, allSpaces);
     }
-  } else {
-    const mySpaceIds = new Set(
-      myTasks.map((t) => t.space?.id).filter((id) => Boolean(id))
+    const foldersBySpace = await Promise.all(spaces.map((space) => client.getFolders(space.id)));
+    const sprintFolders = foldersBySpace.flat().filter((f) => {
+      const lower = f.name.toLowerCase();
+      return SPRINT_KEYWORDS.some((kw) => lower.includes(kw));
+    });
+    const listsByFolder = await Promise.all(
+      sprintFolders.map((folder) => client.getFolderLists(folder.id))
     );
-    spaces = findRelatedSpaces(mySpaceIds, allSpaces);
+    sprintLists = listsByFolder.flat();
+  }
+  let activeList = findActiveSprintList(sprintLists);
+  if (!activeList && sprintLists.length > 1 && isTTY()) {
+    const choice = await select2({
+      message: "Multiple sprint lists found. Which one?",
+      choices: sprintLists.map((l) => ({
+        name: `${l.name} (${l.id})`,
+        value: l
+      }))
+    });
+    activeList = choice;
+  }
+  if (!activeList && sprintLists.length > 1) {
+    process.stderr.write(
+      `Multiple sprint lists found:
+${sprintLists.map((l) => `  - ${l.name} (${l.id})`).join("\n")}
+Using: ${sprintLists[sprintLists.length - 1].name}
+`
+    );
+    activeList = sprintLists[sprintLists.length - 1] ?? null;
   }
-  const foldersBySpace = await Promise.all(spaces.map((space) => client.getFolders(space.id)));
-  const sprintFolders = foldersBySpace.flat().filter((f) => f.name.toLowerCase().includes("sprint"));
-  const listsByFolder = await Promise.all(
-    sprintFolders.map((folder) => client.getFolderLists(folder.id))
-  );
-  const sprintLists = listsByFolder.flat();
-  const activeList = findActiveSprintList(sprintLists);
   if (!activeList) {
-    throw new Error('No sprint list found. Ensure sprint folders contain "sprint" in their name.');
+    throw new Error(
+      'No sprint list found. Ensure sprint folders contain "sprint", "iteration", "cycle", or "scrum" in their name.'
+    );
   }
   process.stderr.write(`Active sprint: ${activeList.name}
 `);
@@ -1274,7 +1381,7 @@ var SPRINT_COLUMNS = [
   { key: "sprint", label: "SPRINT", maxWidth: 60 },
   { key: "dates", label: "DATES" }
 ];
-function formatDate2(d) {
+function formatSprintDate(d) {
   return `${d.getMonth() + 1}/${d.getDate()}`;
 }
 function buildSprintInfos(lists, folderName, today) {
@@ -1304,7 +1411,7 @@ async function listSprints(config, opts = {}) {
     );
     if (spaces.length === 0) {
       throw new Error(
-        `No space matching "${opts.space}" found. Use \`cu spaces\` to list available spaces.`
+        `No space matching "${opts.space}" found. Use \`cup spaces\` to list available spaces.`
       );
     }
   } else {
@@ -1314,7 +1421,10 @@ async function listSprints(config, opts = {}) {
     spaces = findRelatedSpaces(mySpaceIds, allSpaces);
   }
   const foldersBySpace = await Promise.all(spaces.map((space) => client.getFolders(space.id)));
-  const sprintFolders = foldersBySpace.flat().filter((f) => f.name.toLowerCase().includes("sprint"));
+  const sprintFolders = foldersBySpace.flat().filter((f) => {
+    const lower = f.name.toLowerCase();
+    return SPRINT_KEYWORDS.some((kw) => lower.includes(kw));
+  });
   const today = /* @__PURE__ */ new Date();
   const allSprints = [];
   const listsByFolder = await Promise.all(
@@ -1335,7 +1445,7 @@ async function listSprints(config, opts = {}) {
   }
   const rows = allSprints.map((s) => {
     const dates = parseSprintDates(s.name);
-    const dateStr = dates ? `${formatDate2(dates.start)} - ${formatDate2(dates.end)}` : "";
+    const dateStr = dates ? `${formatSprintDate(dates.start)} - ${formatSprintDate(dates.end)}` : "";
     return {
       id: s.id,
       sprint: s.active ? `* ${s.name}` : s.name,
@@ -1379,15 +1489,6 @@ async function postComment(config, taskId, text, notifyAll) {
 
 // src/commands/comments.ts
 import chalk3 from "chalk";
-function formatDate3(timestamp) {
-  return new Date(Number(timestamp)).toLocaleString("en-US", {
-    month: "short",
-    day: "numeric",
-    year: "numeric",
-    hour: "numeric",
-    minute: "2-digit"
-  });
-}
 async function fetchComments(config, taskId) {
   const client = new ClickUpClient(config);
   const comments = await client.getTaskComments(taskId);
@@ -1415,7 +1516,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(formatDate3(c.date))}`);
+    console.log(`${chalk3.bold(c.user)}  ${chalk3.dim(formatTimestamp(c.date))}`);
     console.log(c.text);
     if (i < comments.length - 1) console.log("");
   }
@@ -1812,7 +1913,7 @@ async function fetchOverdueTasks(config, opts = {}) {
 }
 
 // src/commands/config.ts
-var VALID_KEYS = /* @__PURE__ */ new Set(["apiToken", "teamId"]);
+var VALID_KEYS = /* @__PURE__ */ new Set(["apiToken", "teamId", "sprintFolderId"]);
 function assertValidKey(key) {
   if (!VALID_KEYS.has(key)) {
     throw new Error(`Unknown config key: ${key}. Valid keys: ${[...VALID_KEYS].join(", ")}`);
@@ -1868,15 +1969,6 @@ async function assignTask(config, taskId, opts) {
 
 // src/commands/activity.ts
 import chalk4 from "chalk";
-function formatDate4(timestamp) {
-  return new Date(Number(timestamp)).toLocaleString("en-US", {
-    month: "short",
-    day: "numeric",
-    year: "numeric",
-    hour: "numeric",
-    minute: "2-digit"
-  });
-}
 async function fetchActivity(config, taskId) {
   const client = new ClickUpClient(config);
   const [task, rawComments] = await Promise.all([
@@ -1920,7 +2012,7 @@ ${commentsMd}`);
       console.log("");
       console.log(chalk4.dim("-".repeat(60)));
     }
-    console.log(`${chalk4.bold(c.user)}  ${chalk4.dim(formatDate4(c.date))}`);
+    console.log(`${chalk4.bold(c.user)}  ${chalk4.dim(formatTimestamp(c.date))}`);
     console.log(c.text);
   }
 }
@@ -1973,7 +2065,7 @@ function bashCompletion(name) {
       COMPREPLY=($(compgen -W "-l --list -n --name -d --description -p --parent -s --status --priority --due-date --assignee --tags --custom-item-id --time-estimate --json" -- "$cur"))
       ;;
     sprint)
-      COMPREPLY=($(compgen -W "--status --space --include-closed --json" -- "$cur"))
+      COMPREPLY=($(compgen -W "--status --space --folder --include-closed --json" -- "$cur"))
       ;;
     sprints)
       COMPREPLY=($(compgen -W "--space --json" -- "$cur"))
@@ -2070,7 +2162,7 @@ function bashCompletion(name) {
         local subcmd="\${words[2]}"
         case "$subcmd" in
           get|set)
-            COMPREPLY=($(compgen -W "apiToken teamId" -- "$cur"))
+            COMPREPLY=($(compgen -W "apiToken teamId sprintFolderId" -- "$cur"))
             ;;
         esac
       fi
@@ -2186,6 +2278,7 @@ _${name}() {
           _arguments \\
             '--status[Filter by status]:status:(open "in progress" "in review" done closed)' \\
             '--space[Narrow sprint search to a space]:space:' \\
+            '--folder[Sprint folder ID]:folder_id:' \\
             '--include-closed[Include done/closed tasks]' \\
             '--json[Force JSON output]'
           ;;
@@ -2461,7 +2554,7 @@ _${name}() {
             config_args)
               case $words[1] in
                 get|set)
-                  _arguments '1:key:(apiToken teamId)'
+                  _arguments '1:key:(apiToken teamId sprintFolderId)'
                   ;;
               esac
               ;;
@@ -2558,6 +2651,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from create' -l json -d 'Force JS
 
 complete -c ${name} -n '__fish_seen_subcommand_from sprint' -l status -d 'Filter by status'
 complete -c ${name} -n '__fish_seen_subcommand_from sprint' -l space -d 'Narrow sprint search to a space'
+complete -c ${name} -n '__fish_seen_subcommand_from sprint' -l folder -d 'Sprint folder ID'
 complete -c ${name} -n '__fish_seen_subcommand_from sprint' -l include-closed -d 'Include done/closed tasks'
 complete -c ${name} -n '__fish_seen_subcommand_from sprint' -l json -d 'Force JSON output'
 
@@ -2673,7 +2767,7 @@ complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l json -d 'Fo
 complete -c ${name} -n '__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from get set path' -a get -d 'Print a config value'
 complete -c ${name} -n '__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from get set path' -a set -d 'Set a config value'
 complete -c ${name} -n '__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from get set path' -a path -d 'Print config file path'
-complete -c ${name} -n '__fish_seen_subcommand_from get set' -a 'apiToken teamId' -d 'Config key'
+complete -c ${name} -n '__fish_seen_subcommand_from get set' -a 'apiToken teamId sprintFolderId' -d 'Config key'
 
 complete -c ${name} -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d 'Shell type'
 `;
@@ -2969,6 +3063,17 @@ function formatChecklists(checklists) {
   }
   return lines.join("\n");
 }
+function formatChecklistsMarkdown(checklists) {
+  if (checklists.length === 0) return "No checklists";
+  return checklists.map((cl) => {
+    const resolved = cl.items.filter((i) => i.resolved).length;
+    const header = `### ${cl.name} (${resolved}/${cl.items.length})`;
+    const items = cl.items.map(
+      (item) => `- [${item.resolved ? "x" : " "}] ${item.name}`
+    );
+    return [header, "", ...items].join("\n");
+  }).join("\n\n");
+}
 
 // src/commands/comment-edit.ts
 async function editComment(config, commentId, text, resolved) {
@@ -2998,11 +3103,21 @@ function formatReplies(replies) {
   if (replies.length === 0) return "No replies";
   return replies.map((r) => {
     const user = r.user?.username ?? "Unknown";
-    const date = new Date(Number(r.date)).toLocaleString();
+    const date = formatTimestamp(Number(r.date));
     return `${chalk6.bold(user)} ${chalk6.dim(date)}
   ${r.comment_text}`;
   }).join("\n\n");
 }
+function formatRepliesMarkdown(replies) {
+  if (replies.length === 0) return "No replies";
+  return replies.map((r) => {
+    const user = r.user?.username ?? "Unknown";
+    const date = formatTimestamp(Number(r.date));
+    return `**${user}** (${date})
+
+${r.comment_text}`;
+  }).join("\n\n---\n\n");
+}
 
 // src/commands/link.ts
 async function manageTaskLink(config, taskId, linksTo, remove) {
@@ -3029,22 +3144,6 @@ async function attachFile(config, taskId, filePath) {
 
 // src/commands/time.ts
 import chalk7 from "chalk";
-function formatDuration2(ms) {
-  const totalMinutes = Math.round(Math.abs(ms) / 6e4);
-  const hours = Math.floor(totalMinutes / 60);
-  const minutes = totalMinutes % 60;
-  if (hours > 0 && minutes > 0) return `${hours}h ${minutes}m`;
-  if (hours > 0) return `${hours}h`;
-  return `${minutes}m`;
-}
-function formatTimestamp2(ms) {
-  return new Date(Number(ms)).toLocaleString("en-US", {
-    month: "short",
-    day: "numeric",
-    hour: "numeric",
-    minute: "2-digit"
-  });
-}
 async function startTimer(config, taskId, description) {
   const client = new ClickUpClient(config);
   return client.startTimeEntry(config.teamId, taskId, description);
@@ -3079,11 +3178,11 @@ function formatTimeEntry(entry) {
   const taskId = entry.task?.id ?? "";
   const isRunning = entry.duration < 0;
   const elapsed = isRunning ? Date.now() - Number(entry.start) : entry.duration;
-  const durationStr = formatDuration2(elapsed);
+  const durationStr = formatDuration(elapsed);
   const status = isRunning ? chalk7.green("RUNNING") : "";
   lines.push(`${chalk7.bold(taskName)} ${chalk7.dim(taskId)} ${status}`);
   lines.push(
-    `  ${durationStr} - ${formatTimestamp2(entry.start)}${entry.description ? ` - ${entry.description}` : ""}`
+    `  ${durationStr} - ${formatTimestamp(entry.start)}${entry.description ? ` - ${entry.description}` : ""}`
   );
   return lines.join("\n");
 }
@@ -3091,6 +3190,19 @@ function formatTimeEntries(entries) {
   if (entries.length === 0) return "No time entries";
   return entries.map(formatTimeEntry).join("\n");
 }
+function formatTimeEntryMarkdown(entry) {
+  const taskName = entry.task?.name ?? "No task";
+  const taskId = entry.task?.id ?? "";
+  const isRunning = entry.duration < 0;
+  const elapsed = isRunning ? Date.now() - Number(entry.start) : entry.duration;
+  const durationStr = formatDuration(elapsed);
+  const status = isRunning ? " (RUNNING)" : "";
+  return `**${taskName}** ${taskId}${status} - ${durationStr}${entry.description ? ` - ${entry.description}` : ""}`;
+}
+function formatTimeEntriesMarkdown(entries) {
+  if (entries.length === 0) return "No time entries";
+  return entries.map(formatTimeEntryMarkdown).join("\n");
+}
 
 // src/index.ts
 var require2 = createRequire(import.meta.url);
@@ -3185,7 +3297,7 @@ program.command("create").description("Create a new task").option("-l, --list <l
     }
   })
 );
-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(
+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("--folder <folderId>", "Sprint folder ID (overrides config and auto-detection)").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
   wrapAction(
     async (opts) => {
       const config = loadConfig();
@@ -3269,8 +3381,10 @@ program.command("replies <commentId>").description("List threaded replies on a c
     const replies = await getReplies(config, commentId);
     if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(replies, null, 2));
-    } else {
+    } else if (isTTY()) {
       console.log(formatReplies(replies));
+    } else {
+      console.log(formatRepliesMarkdown(replies));
     }
   })
 );
@@ -3490,8 +3604,10 @@ checklistCmd.command("view <taskId>").description("View checklists on a task").o
     const checklists = await viewChecklists(config, taskId);
     if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(checklists, null, 2));
-    } else {
+    } else if (isTTY()) {
       console.log(formatChecklists(checklists));
+    } else {
+      console.log(formatChecklistsMarkdown(checklists));
     }
   })
 );
@@ -3578,8 +3694,10 @@ timeCmd.command("stop").description("Stop the running timer").option("--json", "
     const result = await stopTimer(config);
     if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
-    } else {
+    } else if (isTTY()) {
       console.log(formatTimeEntry(result));
+    } else {
+      console.log(formatTimeEntryMarkdown(result));
     }
   })
 );
@@ -3589,10 +3707,12 @@ timeCmd.command("status").description("Show the currently running timer").option
     const result = await timerStatus(config);
     if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(result, null, 2));
-    } else if (result) {
+    } else if (!result) {
+      console.log("No timer running");
+    } else if (isTTY()) {
       console.log(formatTimeEntry(result));
     } else {
-      console.log("No timer running");
+      console.log(formatTimeEntryMarkdown(result));
     }
   })
 );
@@ -3619,8 +3739,10 @@ timeCmd.command("list").description("List recent time entries (default: last 7 d
     const entries = await listTimeEntries(config, { days, taskId: opts.task });
     if (shouldOutputJson(opts.json ?? false)) {
       console.log(JSON.stringify(entries, null, 2));
-    } else {
+    } else if (isTTY()) {
       console.log(formatTimeEntries(entries));
+    } else {
+      console.log(formatTimeEntriesMarkdown(entries));
     }
   })
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krodak/clickup-cli",
-  "version": "0.21.0",
+  "version": "1.0.0",
   "description": "ClickUp CLI for AI agents and humans",
   "type": "module",
   "license": "MIT",
@@ -52,7 +52,6 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@inquirer/testing": "^3.3.0",
     "@types/node": "^25.3.0",
     "dotenv": "^17.3.1",
     "eslint": "^10.0.2",

package/skills/clickup-cli/SKILL.md

@@ -11,7 +11,7 @@ Keywords: ClickUp, task management, sprint, project management, agile, backlog,
 
 ## Setup
 
-Config at `~/.config/cu/config.json` with `apiToken` and `teamId`. Run `cup init` to set up interactively.
+Config at `~/.config/cup/config.json` with `apiToken` and `teamId`. Optional: `sprintFolderId` to pin sprint detection to a specific folder. Run `cup init` to set up interactively.
 
 Environment variables `CU_API_TOKEN` and `CU_TEAM_ID` override config file when both are set.
 
@@ -38,7 +38,7 @@ All commands support `--help` for full flag details.
 | --------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
 | `cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--include-closed] [--json]` | My tasks (all types, or filter with --type)        |
 | `cup assigned [--status s] [--include-closed] [--json]`                                             | All my tasks grouped by status                     |
-| `cup sprint [--status s] [--space nameOrId] [--include-closed] [--json]`                            | Tasks in active sprint (auto-detected)             |
+| `cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed] [--json]`              | Tasks in active sprint (auto-detected)             |
 | `cup sprints [--space nameOrId] [--json]`                                                           | List all sprints (marks active with \*)            |
 | `cup search <query> [--status s] [--include-closed] [--json]`                                       | Search my tasks by name (multi-word, fuzzy status) |
 | `cup task <id> [--json]`                                                                            | Single task details                                |
@@ -55,79 +55,79 @@ All commands support `--help` for full flag details.
 
 ### Write
 
-| Command                                                                                                                                                                             | What it does                                |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `cup update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id\|me] [--parent id] [--json]`                                      | Update task fields (desc supports markdown) |
-| `cup create -n name [-l listId] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id\|me] [--tags t] [--custom-item-id n] [--json]` | Create task (desc supports markdown)        |
-| `cup comment <id> -m text [--notify-all] [--json]`                                                                                                                                  | Post comment on task                        |
-| `cup comment-edit <commentId> -m text [--resolved] [--unresolved] [--json]`                                                                                                         | Edit an existing comment                    |
-| `cup assign <id> [--to userId\|me] [--remove userId\|me] [--json]`                                                                                                                  | Assign/unassign users                       |
-| `cup depend <id> [--on taskId] [--blocks taskId] [--remove] [--json]`                                                                                                               | Add/remove task dependencies                |
-| `cup move <id> [--to listId] [--remove listId] [--json]`                                                                                                                            | Add/remove task from lists                  |
-| `cup field <id> [--set "Name" value] [--remove "Name"] [--json]`                                                                                                                    | Set/remove custom field values              |
-| `cup delete <id> [--confirm] [--json]`                                                                                                                                              | Delete a task (DESTRUCTIVE, irreversible)   |
-| `cup tag <id> [--add tags] [--remove tags] [--json]`                                                                                                                                | Add/remove tags on a task                   |
-| `cup checklist view <id> [--json]`                                                                                                                                                  | View checklists on a task                   |
-| `cup checklist create <id> <name> [--json]`                                                                                                                                         | Create a checklist                          |
-| `cup checklist delete <checklistId> [--json]`                                                                                                                                       | Delete a checklist                          |
-| `cup checklist add-item <checklistId> <name> [--json]`                                                                                                                              | Add item to a checklist                     |
-| `cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--json]`                                                                    | Edit a checklist item                       |
-| `cup checklist delete-item <checklistId> <itemId> [--json]`                                                                                                                         | Delete a checklist item                     |
-| `cup comment-delete <commentId> [--json]`                                                                                                                                           | Delete a comment                            |
-| `cup replies <commentId> [--json]`                                                                                                                                                  | List threaded replies on a comment          |
-| `cup reply <commentId> -m text [--notify-all] [--json]`                                                                                                                             | Reply to a comment                          |
-| `cup link <taskId> <linksTo> [--remove] [--json]`                                                                                                                                   | Add or remove link between tasks            |
-| `cup attach <taskId> <filePath> [--json]`                                                                                                                                           | Upload file attachment to a task            |
-| `cup time start <taskId> [-d desc] [--json]`                                                                                                                                        | Start tracking time on a task               |
-| `cup time stop [--json]`                                                                                                                                                            | Stop the running timer                      |
-| `cup time status [--json]`                                                                                                                                                          | Show currently running timer                |
-| `cup time log <taskId> <duration> [-d desc] [--json]`                                                                                                                               | Log manual time entry (e.g. "2h", "30m")    |
-| `cup time list [--days n] [--task id] [--json]`                                                                                                                                     | List recent time entries                    |
-| `cup config get <key>` / `cup config set <key> <value>` / `cup config path`                                                                                                         | Manage CLI config                           |
-| `cup completion <shell>`                                                                                                                                                            | Shell completions (bash/zsh/fish)           |
+| Command                                                                                                                                                                             | What it does                                               |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `cup update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id\|me] [--parent id] [--json]`                                      | Update task fields (desc supports markdown)                |
+| `cup create -n name [-l listId] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id\|me] [--tags t] [--custom-item-id n] [--json]` | Create task (desc supports markdown)                       |
+| `cup comment <id> -m text [--notify-all] [--json]`                                                                                                                                  | Post comment on task                                       |
+| `cup comment-edit <commentId> -m text [--resolved] [--unresolved] [--json]`                                                                                                         | Edit an existing comment                                   |
+| `cup assign <id> [--to userId\|me] [--remove userId\|me] [--json]`                                                                                                                  | Assign/unassign users                                      |
+| `cup depend <id> [--on taskId] [--blocks taskId] [--remove] [--json]`                                                                                                               | Add/remove task dependencies                               |
+| `cup move <id> [--to listId] [--remove listId] [--json]`                                                                                                                            | Add/remove task from lists                                 |
+| `cup field <id> [--set "Name" value] [--remove "Name"] [--json]`                                                                                                                    | Set/remove custom field values                             |
+| `cup delete <id> [--confirm] [--json]`                                                                                                                                              | Delete a task (DESTRUCTIVE, irreversible)                  |
+| `cup tag <id> [--add tags] [--remove tags] [--json]`                                                                                                                                | Add/remove tags on a task                                  |
+| `cup checklist view <id> [--json]`                                                                                                                                                  | View checklists on a task                                  |
+| `cup checklist create <id> <name> [--json]`                                                                                                                                         | Create a checklist                                         |
+| `cup checklist delete <checklistId> [--json]`                                                                                                                                       | Delete a checklist                                         |
+| `cup checklist add-item <checklistId> <name> [--json]`                                                                                                                              | Add item to a checklist                                    |
+| `cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--json]`                                                                    | Edit a checklist item                                      |
+| `cup checklist delete-item <checklistId> <itemId> [--json]`                                                                                                                         | Delete a checklist item                                    |
+| `cup comment-delete <commentId> [--json]`                                                                                                                                           | Delete a comment                                           |
+| `cup replies <commentId> [--json]`                                                                                                                                                  | List threaded replies on a comment                         |
+| `cup reply <commentId> -m text [--notify-all] [--json]`                                                                                                                             | Reply to a comment                                         |
+| `cup link <taskId> <linksTo> [--remove] [--json]`                                                                                                                                   | Add or remove link between tasks                           |
+| `cup attach <taskId> <filePath> [--json]`                                                                                                                                           | Upload file attachment to a task                           |
+| `cup time start <taskId> [-d desc] [--json]`                                                                                                                                        | Start tracking time on a task                              |
+| `cup time stop [--json]`                                                                                                                                                            | Stop the running timer                                     |
+| `cup time status [--json]`                                                                                                                                                          | Show currently running timer                               |
+| `cup time log <taskId> <duration> [-d desc] [--json]`                                                                                                                               | Log manual time entry (e.g. "2h", "30m")                   |
+| `cup time list [--days n] [--task id] [--json]`                                                                                                                                     | List recent time entries                                   |
+| `cup config get <key>` / `cup config set <key> <value>` / `cup config path`                                                                                                         | Manage CLI config (keys: apiToken, teamId, sprintFolderId) |
+| `cup completion <shell>`                                                                                                                                                            | Shell completions (bash/zsh/fish)                          |
 
 ## Quick Reference
 
-| Topic                       | Detail                                                                                                 |
-| --------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Task IDs                    | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format        |
-| `--type`                    | Filter by task type: `task` (regular), or custom type name/ID (e.g. `initiative`, `Bug`)               |
-| `--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`                | User ID or `me` (on `cup create`, `cup update`, `cup assign`)                                          |
-| `--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 for `cup create` (e.g. `1` for initiative)                                         |
-| `--on` / `--blocks`         | Task dependency direction (used with `cup depend`)                                                     |
-| `--to` / `--remove`         | List ID to add/remove task (used with `cup move`)                                                      |
-| `cup field --set`           | Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email   |
-| `cup field`                 | Field names resolved case-insensitively; errors list available fields/options                          |
-| `cup delete`                | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone                            |
-| `cup tag --add/--remove`    | Comma-separated tag names (e.g. `--add "bug,frontend"`)                                                |
-| `--space`                   | Partial name match or exact ID                                                                         |
-| `--name`                    | Partial match, case-insensitive                                                                        |
-| `--include-closed`          | Include closed/done tasks (on `tasks`, `assigned`, `subtasks`, `sprint`, `search`, `inbox`, `overdue`) |
-| `cup assign --to me`        | Shorthand for your own user ID                                                                         |
-| `cup search`                | Matches all query words against task name, case-insensitive                                            |
-| `cup sprint`                | Auto-detects active sprint via view API and date range parsing                                         |
-| `cup summary`               | Categories: completed (done/complete/closed within N hours), in progress, overdue                      |
-| `cup overdue`               | Excludes closed tasks, sorted most overdue first                                                       |
-| `cup open`                  | Tries task ID first, falls back to name search                                                         |
-| `cup checklist`             | Full CRUD for task checklists: view, create, delete, add-item, edit-item, delete-item                  |
-| `cup time`                  | Track time: start/stop timer, log entries, list history. Duration format: "2h", "30m", "1h30m"         |
-| `cup comment-edit`          | Edit comment text and resolution status                                                                |
-| `cup comment-delete`        | Delete a comment                                                                                       |
-| `cup replies` / `cup reply` | View and post threaded comment replies                                                                 |
-| Custom task IDs             | Auto-detected by format (`PROJ-123`). Uses `teamId` from config. All commands support them             |
-| `cup link` + custom IDs     | Both IDs must be the same type (both custom or both native). Mixing may not work                       |
-| `cup link`                  | Link/unlink tasks (different from dependencies)                                                        |
-| `cup attach`                | Upload files to tasks. Attachments shown in `cup task` detail view                                     |
-| `cup task`                  | Shows custom fields, checklists, attachments, dependencies, and linked tasks in detail view            |
-| `cup lists`                 | Discovers list IDs needed for `--list` and `cup create -l`                                             |
-| Errors                      | stderr with exit code 1                                                                                |
-| Parsing                     | Strict - excess/unknown arguments rejected                                                             |
+| Topic                       | Detail                                                                                                                                                                                                                                                    |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Task IDs                    | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format                                                                                                                                                           |
+| `--type`                    | Filter by task type: `task` (regular), or custom type name/ID (e.g. `initiative`, `Bug`)                                                                                                                                                                  |
+| `--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`                | User ID or `me` (on `cup create`, `cup update`, `cup assign`)                                                                                                                                                                                             |
+| `--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 for `cup create` (e.g. `1` for initiative)                                                                                                                                                                                            |
+| `--on` / `--blocks`         | Task dependency direction (used with `cup depend`)                                                                                                                                                                                                        |
+| `--to` / `--remove`         | List ID to add/remove task (used with `cup move`)                                                                                                                                                                                                         |
+| `cup field --set`           | Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email                                                                                                                                                      |
+| `cup field`                 | Field names resolved case-insensitively; errors list available fields/options                                                                                                                                                                             |
+| `cup delete`                | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone                                                                                                                                                                               |
+| `cup tag --add/--remove`    | Comma-separated tag names (e.g. `--add "bug,frontend"`)                                                                                                                                                                                                   |
+| `--space`                   | Partial name match or exact ID                                                                                                                                                                                                                            |
+| `--name`                    | Partial match, case-insensitive                                                                                                                                                                                                                           |
+| `--include-closed`          | Include closed/done tasks (on `tasks`, `assigned`, `subtasks`, `sprint`, `search`, `inbox`, `overdue`)                                                                                                                                                    |
+| `cup assign --to me`        | Shorthand for your own user ID                                                                                                                                                                                                                            |
+| `cup search`                | Matches all query words against task name, case-insensitive                                                                                                                                                                                               |
+| `cup sprint`                | Auto-detects active sprint by searching for folders named sprint/iteration/cycle/scrum, parses multiple date formats (US, ISO, month-day, European), prompts in TTY when ambiguous. Override with `--folder <id>` or `cup config set sprintFolderId <id>` |
+| `cup summary`               | Categories: completed (done/complete/closed within N hours), in progress, overdue                                                                                                                                                                         |
+| `cup overdue`               | Excludes closed tasks, sorted most overdue first                                                                                                                                                                                                          |
+| `cup open`                  | Tries task ID first, falls back to name search                                                                                                                                                                                                            |
+| `cup checklist`             | Full CRUD for task checklists: view, create, delete, add-item, edit-item, delete-item                                                                                                                                                                     |
+| `cup time`                  | Track time: start/stop timer, log entries, list history. Duration format: "2h", "30m", "1h30m"                                                                                                                                                            |
+| `cup comment-edit`          | Edit comment text and resolution status                                                                                                                                                                                                                   |
+| `cup comment-delete`        | Delete a comment                                                                                                                                                                                                                                          |
+| `cup replies` / `cup reply` | View and post threaded comment replies                                                                                                                                                                                                                    |
+| Custom task IDs             | Auto-detected by format (`PROJ-123`). Uses `teamId` from config. All commands support them                                                                                                                                                                |
+| `cup link` + custom IDs     | Both IDs must be the same type (both custom or both native). Mixing may not work                                                                                                                                                                          |
+| `cup link`                  | Link/unlink tasks (different from dependencies)                                                                                                                                                                                                           |
+| `cup attach`                | Upload files to tasks. Attachments shown in `cup task` detail view                                                                                                                                                                                        |
+| `cup task`                  | Shows custom fields, checklists, attachments, dependencies, and linked tasks in detail view                                                                                                                                                               |
+| `cup lists`                 | Discovers list IDs needed for `--list` and `cup create -l`                                                                                                                                                                                                |
+| Errors                      | stderr with exit code 1                                                                                                                                                                                                                                   |
+| Parsing                     | Strict - excess/unknown arguments rejected                                                                                                                                                                                                                |
 
 ## Agent Workflow Examples
 
@@ -203,6 +203,7 @@ cup spaces --name "Engineering"      # find space ID by name
 cup lists <spaceId>                  # lists in a space (needs ID from cup spaces)
 cup sprints                          # all sprints across folders
 cup auth                             # verify token works
+cup config set sprintFolderId <id>   # pin sprint detection to a folder
 ```
 
 ### Standup