@krodak/clickup-cli 0.21.0 → 1.1.0

package/dist/index.js

@@ -7,6 +7,7 @@ import { createRequire } from "module";
 
 // src/api.ts
 var BASE_URL = "https://api.clickup.com/api/v2";
+var BASE_URL_V3 = "https://api.clickup.com/api/v3";
 var MAX_PAGES = 100;
 function isCustomTaskId(id) {
   return /^[A-Z]+-\d+$/i.test(id);
@@ -56,6 +57,29 @@ var ClickUpClient = class {
     }
     return data;
   }
+  async requestV3(path, options = {}) {
+    const res = await fetch(`${BASE_URL_V3}${path}`, {
+      ...options,
+      signal: AbortSignal.timeout(3e4),
+      headers: {
+        Authorization: this.apiToken,
+        ...options.body ? { "Content-Type": "application/json" } : {},
+        ...options.headers
+      }
+    });
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new Error(`ClickUp API error ${res.status}: response was not valid JSON`);
+    }
+    if (!res.ok) {
+      const raw = data.err ?? data.error ?? data.ECODE ?? res.statusText;
+      const msg = typeof raw === "string" ? raw : JSON.stringify(raw);
+      throw new Error(`ClickUp API error ${res.status}: ${msg}`);
+    }
+    return data;
+  }
   async getMe() {
     if (this.meCache) return this.meCache;
     const data = await this.request("/user");
@@ -383,6 +407,42 @@ var ClickUpClient = class {
     }
     return data;
   }
+  async getDocs(workspaceId) {
+    const data = await this.requestV3(`/workspaces/${workspaceId}/docs`);
+    return data.docs ?? [];
+  }
+  async getDocPage(workspaceId, docId, pageId) {
+    return this.requestV3(
+      `/workspaces/${workspaceId}/docs/${docId}/pages/${pageId}?content_format=text/md`
+    );
+  }
+  async createDoc(workspaceId, title, content, parentId) {
+    const body = { title };
+    if (content) body.content = content;
+    if (parentId) {
+      body.parent_id = parentId;
+      body.parent_type = "doc";
+    }
+    return this.requestV3(`/workspaces/${workspaceId}/docs`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async createDocPage(workspaceId, docId, name, content, parentPageId) {
+    const body = { name, content_format: "text/md" };
+    if (content) body.content = content;
+    if (parentPageId) body.parent_page_id = parentPageId;
+    return this.requestV3(`/workspaces/${workspaceId}/docs/${docId}/pages`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async editDocPage(workspaceId, docId, pageId, updates) {
+    return this.requestV3(`/workspaces/${workspaceId}/docs/${docId}/pages/${pageId}`, {
+      method: "PUT",
+      body: JSON.stringify(updates)
+    });
+  }
 };
 
 // src/config.ts
@@ -390,18 +450,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 +491,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 +504,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 +517,7 @@ function loadRawConfig() {
   }
 }
 function getConfigPath() {
+  migrateFromLegacy();
   return configPath();
 }
 function writeConfig(config) {
@@ -453,10 +534,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 +664,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 +679,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 +690,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 +771,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 +830,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 +1088,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 +1265,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 +1353,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 +1441,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 +1471,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 +1481,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 +1505,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 +1549,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 +1576,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 +1973,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 +2029,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 +2072,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);
   }
 }
@@ -1939,7 +2091,7 @@ function bashCompletion(name) {
     cword=$COMP_CWORD
   fi
 
-  local commands="init auth tasks task update create sprint sprints subtasks comment comment-edit comment-delete comments replies reply activity lists spaces inbox assigned open search summary overdue assign depend link attach move field delete tag checklist time config completion"
+  local commands="init auth tasks task update create sprint sprints subtasks comment comment-edit comment-delete comments replies reply activity lists spaces inbox assigned open search summary overdue assign depend link attach move field delete tag checklist time docs doc doc-create doc-page-create doc-page-edit config completion"
 
   if [[ $cword -eq 1 ]]; then
     COMPREPLY=($(compgen -W "$commands --help --version" -- "$cur"))
@@ -1973,7 +2125,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"))
@@ -2063,6 +2215,21 @@ function bashCompletion(name) {
     attach)
       COMPREPLY=($(compgen -f -- "$cur"))
       ;;
+    docs)
+      COMPREPLY=($(compgen -W "--json" -- "$cur"))
+      ;;
+    doc)
+      COMPREPLY=($(compgen -W "--json" -- "$cur"))
+      ;;
+    doc-create)
+      COMPREPLY=($(compgen -W "-c --content --json" -- "$cur"))
+      ;;
+    doc-page-create)
+      COMPREPLY=($(compgen -W "-c --content --parent-page --json" -- "$cur"))
+      ;;
+    doc-page-edit)
+      COMPREPLY=($(compgen -W "--name -c --content --json" -- "$cur"))
+      ;;
     config)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "get set path" -- "$cur"))
@@ -2070,7 +2237,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
@@ -2123,6 +2290,11 @@ _${name}() {
     'reply:Reply to a comment'
     'link:Add or remove a link between two tasks'
     'attach:Upload a file attachment to a task'
+    'docs:List workspace docs'
+    'doc:View a doc page'
+    'doc-create:Create a new doc'
+    'doc-page-create:Create a page in a doc'
+    'doc-page-edit:Edit a doc page'
     'config:Manage CLI configuration'
     'completion:Output shell completion script'
   )
@@ -2186,6 +2358,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]'
           ;;
@@ -2444,6 +2617,39 @@ _${name}() {
             '2:file_path:_files' \\
             '--json[Force JSON output]'
           ;;
+        docs)
+          _arguments \\
+            '1:query:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc)
+          _arguments \\
+            '1:doc_id:' \\
+            '2:page_id:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc-create)
+          _arguments \\
+            '1:title:' \\
+            '(-c --content)'{-c,--content}'[Initial content]:text:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc-page-create)
+          _arguments \\
+            '1:doc_id:' \\
+            '2:name:' \\
+            '(-c --content)'{-c,--content}'[Page content]:text:' \\
+            '--parent-page[Parent page ID]:page_id:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc-page-edit)
+          _arguments \\
+            '1:doc_id:' \\
+            '2:page_id:' \\
+            '--name[New page name]:text:' \\
+            '(-c --content)'{-c,--content}'[New page content]:text:' \\
+            '--json[Force JSON output]'
+          ;;
         config)
           local -a config_cmds
           config_cmds=(
@@ -2461,7 +2667,7 @@ _${name}() {
             config_args)
               case $words[1] in
                 get|set)
-                  _arguments '1:key:(apiToken teamId)'
+                  _arguments '1:key:(apiToken teamId sprintFolderId)'
                   ;;
               esac
               ;;
@@ -2518,6 +2724,11 @@ complete -c ${name} -n __fish_use_subcommand -a replies -d 'List threaded replie
 complete -c ${name} -n __fish_use_subcommand -a reply -d 'Reply to a comment'
 complete -c ${name} -n __fish_use_subcommand -a link -d 'Add or remove a link between two tasks'
 complete -c ${name} -n __fish_use_subcommand -a attach -d 'Upload a file attachment to a task'
+complete -c ${name} -n __fish_use_subcommand -a docs -d 'List workspace docs'
+complete -c ${name} -n __fish_use_subcommand -a doc -d 'View a doc page'
+complete -c ${name} -n __fish_use_subcommand -a doc-create -d 'Create a new doc'
+complete -c ${name} -n __fish_use_subcommand -a doc-page-create -d 'Create a page in a doc'
+complete -c ${name} -n __fish_use_subcommand -a doc-page-edit -d 'Edit a doc page'
 complete -c ${name} -n __fish_use_subcommand -a config -d 'Manage CLI configuration'
 complete -c ${name} -n __fish_use_subcommand -a completion -d 'Output shell completion script'
 
@@ -2558,6 +2769,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'
 
@@ -2670,10 +2882,25 @@ complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l resolved -d
 complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l unresolved -d 'Mark comment as unresolved'
 complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l json -d 'Force JSON output'
 
+complete -c ${name} -n '__fish_seen_subcommand_from docs' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc-create' -s c -l content -d 'Initial content'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-create' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-create' -s c -l content -d 'Page content'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-create' -l parent-page -d 'Parent page ID'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-create' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-edit' -l name -d 'New page name'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-edit' -s c -l content -d 'New page content'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-edit' -l json -d 'Force JSON output'
+
 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 +3196,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 +3236,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) {
@@ -3027,24 +3275,52 @@ async function attachFile(config, taskId, filePath) {
   return client.createTaskAttachment(taskId, filePath);
 }
 
-// src/commands/time.ts
+// src/commands/docs.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`;
+async function listDocs(config, query) {
+  const client = new ClickUpClient(config);
+  const docs = await client.getDocs(config.teamId);
+  if (query) {
+    const lower = query.toLowerCase();
+    return docs.filter((d) => d.name.toLowerCase().includes(lower));
+  }
+  return docs;
 }
-function formatTimestamp2(ms) {
-  return new Date(Number(ms)).toLocaleString("en-US", {
-    month: "short",
-    day: "numeric",
-    hour: "numeric",
-    minute: "2-digit"
-  });
+function formatDocs(docs) {
+  if (docs.length === 0) return "No docs found";
+  return docs.map((d) => `${chalk7.bold(d.name)} ${chalk7.dim(d.id)}`).join("\n");
+}
+function formatDocsMarkdown(docs) {
+  if (docs.length === 0) return "No docs found";
+  return docs.map((d) => `- **${d.name}** (${d.id})`).join("\n");
+}
+
+// src/commands/doc.ts
+async function getDocPage(config, docId, pageId) {
+  const client = new ClickUpClient(config);
+  return client.getDocPage(config.teamId, docId, pageId);
+}
+async function createDoc(config, title, content) {
+  if (!title.trim()) throw new Error("Doc title cannot be empty");
+  const client = new ClickUpClient(config);
+  const doc = await client.createDoc(config.teamId, title, content);
+  return { id: doc.id, title: doc.name ?? title };
 }
+async function createDocPage(config, docId, name, content, parentPageId) {
+  if (!name.trim()) throw new Error("Page name cannot be empty");
+  const client = new ClickUpClient(config);
+  return client.createDocPage(config.teamId, docId, name, content, parentPageId);
+}
+async function editDocPage(config, docId, pageId, updates) {
+  if (!updates.name && !updates.content) {
+    throw new Error("Provide --name or --content to update");
+  }
+  const client = new ClickUpClient(config);
+  return client.editDocPage(config.teamId, docId, pageId, updates);
+}
+
+// src/commands/time.ts
+import chalk8 from "chalk";
 async function startTimer(config, taskId, description) {
   const client = new ClickUpClient(config);
   return client.startTimeEntry(config.teamId, taskId, description);
@@ -3079,11 +3355,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 status = isRunning ? chalk7.green("RUNNING") : "";
-  lines.push(`${chalk7.bold(taskName)} ${chalk7.dim(taskId)} ${status}`);
+  const durationStr = formatDuration(elapsed);
+  const status = isRunning ? chalk8.green("RUNNING") : "";
+  lines.push(`${chalk8.bold(taskName)} ${chalk8.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 +3367,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 +3474,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 +3558,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 +3781,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 +3871,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 +3884,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,11 +3916,79 @@ 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));
+    }
+  })
+);
+program.command("docs [query]").description("List workspace docs (optionally filter by name)").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (query, opts) => {
+    const config = loadConfig();
+    const docs = await listDocs(config, query);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(docs, null, 2));
+    } else if (isTTY()) {
+      console.log(formatDocs(docs));
+    } else {
+      console.log(formatDocsMarkdown(docs));
     }
   })
 );
+program.command("doc <docId> <pageId>").description("View a doc page").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (docId, pageId, opts) => {
+    const config = loadConfig();
+    const page = await getDocPage(config, docId, pageId);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(page, null, 2));
+    } else {
+      if (page.name) console.log(`# ${page.name}
+`);
+      console.log(page.content ?? "");
+    }
+  })
+);
+program.command("doc-create <title>").description("Create a new doc").option("-c, --content <text>", "Initial content (markdown)").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (title, opts) => {
+    const config = loadConfig();
+    const result = await createDoc(config, title, opts.content);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Created doc "${result.title}" (${result.id})`);
+    }
+  })
+);
+program.command("doc-page-create <docId> <name>").description("Create a page in a doc").option("-c, --content <text>", "Page content (markdown)").option("--parent-page <pageId>", "Parent page ID for nesting").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (docId, name, opts) => {
+      const config = loadConfig();
+      const page = await createDocPage(config, docId, name, opts.content, opts.parentPage);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(page, null, 2));
+      } else {
+        console.log(`Created page "${page.name}" (${page.id}) in doc ${docId}`);
+      }
+    }
+  )
+);
+program.command("doc-page-edit <docId> <pageId>").description("Edit a doc page").option("--name <text>", "New page name").option("-c, --content <text>", "New page content (markdown)").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (docId, pageId, opts) => {
+      const config = loadConfig();
+      const page = await editDocPage(config, docId, pageId, {
+        name: opts.name,
+        content: opts.content
+      });
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(page, null, 2));
+      } else {
+        console.log(`Updated page "${page.name}" (${page.id})`);
+      }
+    }
+  )
+);
 var configCmd = program.command("config").description("Manage CLI configuration");
 configCmd.command("get <key>").description("Print a config value").action(
   wrapAction(async (key) => {