@krodak/clickup-cli 1.5.0 → 1.5.1

package/dist/index.js

@@ -1,14 +1,69 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { basename } from "path";
+import { basename, resolve } from "path";
 import { Command } from "commander";
 import { createRequire } from "module";
+import { fileURLToPath } from "url";
 
 // 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 isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function expectRecord(value, context) {
+  if (!isRecord(value)) {
+    throw new Error(`Unexpected API response: expected ${context} object`);
+  }
+  return value;
+}
+function expectRecordField(data, key, context) {
+  return expectRecord(data[key], context);
+}
+function expectNumericField(data, key, context) {
+  const value = Number(data[key]);
+  if (!Number.isInteger(value)) {
+    throw new Error(`Unexpected API response: expected ${context}.${key} to be numeric`);
+  }
+  return value;
+}
+function expectStringField(data, key, context) {
+  const value = data[key];
+  if (typeof value !== "string") {
+    throw new Error(`Unexpected API response: expected ${context}.${key} to be a string`);
+  }
+  return value;
+}
+function expectArrayField(data, key, context) {
+  const value = data[key];
+  if (!Array.isArray(value)) {
+    throw new Error(`Unexpected API response: expected ${context}.${key} to be an array`);
+  }
+  return value;
+}
+function readCollectionField(data, key, context) {
+  if (data[key] === void 0) return [];
+  return expectArrayField(data, key, context);
+}
+function expectBooleanField(data, key, context) {
+  const value = data[key];
+  if (typeof value !== "boolean") {
+    throw new Error(`Unexpected API response: expected ${context}.${key} to be a boolean`);
+  }
+  return value;
+}
+function expectPaginatedCollectionField(data, key, context) {
+  const items = data[key];
+  if (!Array.isArray(items)) {
+    throw new Error(`Unexpected API response: expected ${key} array`);
+  }
+  return {
+    items,
+    lastPage: expectBooleanField(data, "last_page", context)
+  };
+}
 function isCustomTaskId(id) {
   return /^[A-Z]+-\d+$/i.test(id);
 }
@@ -44,12 +99,13 @@ var ClickUpClient = class {
         ...options.headers
       }
     });
-    let data;
+    let parsed;
     try {
-      data = await res.json();
+      parsed = await res.json();
     } catch {
       throw new Error(`ClickUp API error ${res.status}: response was not valid JSON`);
     }
+    const data = expectRecord(parsed, "JSON");
     if (!res.ok) {
       const raw = data.err ?? data.error ?? data.ECODE ?? res.statusText;
       const errMsg = typeof raw === "string" ? raw : JSON.stringify(raw);
@@ -66,8 +122,12 @@ var ClickUpClient = class {
   async getMe() {
     if (this.meCache) return this.meCache;
     const data = await this.request("/user");
-    this.meCache = data.user;
-    return data.user;
+    const user = expectRecordField(data, "user", "user");
+    this.meCache = {
+      id: expectNumericField(user, "id", "user"),
+      username: expectStringField(user, "username", "user")
+    };
+    return this.meCache;
   }
   async paginate(buildPath) {
     const allTasks = [];
@@ -75,12 +135,13 @@ var ClickUpClient = class {
     let lastPage = false;
     while (!lastPage && page < MAX_PAGES) {
       const data = await this.request(buildPath(page));
-      const tasks = data.tasks;
-      if (!Array.isArray(tasks)) {
-        throw new Error(`Unexpected API response: expected tasks array, got ${typeof tasks}`);
-      }
-      allTasks.push(...tasks);
-      lastPage = data.last_page ?? true;
+      const taskPage = expectPaginatedCollectionField(
+        data,
+        "tasks",
+        "task page"
+      );
+      allTasks.push(...taskPage.items);
+      lastPage = taskPage.lastPage;
       page++;
     }
     if (page >= MAX_PAGES && !lastPage) {
@@ -123,7 +184,11 @@ var ClickUpClient = class {
   }
   async getTaskComments(taskId) {
     const data = await this.request(this.taskPath(taskId, "/comment"));
-    return data.comments ?? [];
+    return readCollectionField(
+      data,
+      "comments",
+      "task comments"
+    );
   }
   async getTasksFromList(listId, params = {}, options = {}) {
     return this.paginate((page) => {
@@ -144,7 +209,7 @@ var ClickUpClient = class {
   }
   async getTeams() {
     const data = await this.request("/team");
-    return data.teams ?? [];
+    return readCollectionField(data, "teams", "teams");
   }
   async getSpaceWithStatuses(spaceId) {
     return this.request(`/space/${spaceId}`);
@@ -154,27 +219,31 @@ var ClickUpClient = class {
   }
   async getSpaces(teamId) {
     const data = await this.request(`/team/${teamId}/space?archived=false`);
-    return data.spaces ?? [];
+    return readCollectionField(data, "spaces", "spaces");
   }
   async getCustomTaskTypes(teamId) {
     const data = await this.request(
       `/team/${teamId}/custom_item`
     );
-    return data.custom_items ?? [];
+    return readCollectionField(
+      data,
+      "custom_items",
+      "custom task types"
+    );
   }
   async getLists(spaceId) {
     const data = await this.request(`/space/${spaceId}/list?archived=false`);
-    return data.lists ?? [];
+    return readCollectionField(data, "lists", "space lists");
   }
   async getFolders(spaceId) {
     const data = await this.request(
       `/space/${spaceId}/folder?archived=false`
     );
-    return data.folders ?? [];
+    return readCollectionField(data, "folders", "space folders");
   }
   async getFolderLists(folderId) {
     const data = await this.request(`/folder/${folderId}/list?archived=false`);
-    return data.lists ?? [];
+    return readCollectionField(data, "lists", "folder lists");
   }
   async getListViews(listId) {
     return this.request(
@@ -242,7 +311,11 @@ var ClickUpClient = class {
   }
   async getThreadedComments(commentId) {
     const data = await this.request(`/comment/${commentId}/reply`);
-    return data.comments ?? [];
+    return readCollectionField(
+      data,
+      "comments",
+      "threaded comments"
+    );
   }
   async createThreadedComment(commentId, text, notifyAll) {
     const body = { comment_text: text };
@@ -264,14 +337,22 @@ var ClickUpClient = class {
   }
   async getListCustomFields(listId) {
     const data = await this.request(`/list/${listId}/field`);
-    return data.fields ?? [];
+    return readCollectionField(
+      data,
+      "fields",
+      "list custom fields"
+    );
   }
   async createChecklist(taskId, name) {
     const data = await this.request(this.taskPath(taskId, "/checklist"), {
       method: "POST",
       body: JSON.stringify({ name })
     });
-    return data.checklist;
+    return expectRecordField(
+      data,
+      "checklist",
+      "checklist"
+    );
   }
   async deleteChecklist(checklistId) {
     await this.request(`/checklist/${checklistId}`, { method: "DELETE" });
@@ -281,14 +362,22 @@ var ClickUpClient = class {
       `/checklist/${checklistId}/checklist_item`,
       { method: "POST", body: JSON.stringify({ name }) }
     );
-    return data.checklist;
+    return expectRecordField(
+      data,
+      "checklist",
+      "checklist"
+    );
   }
   async editChecklistItem(checklistId, checklistItemId, updates) {
     const data = await this.request(
       `/checklist/${checklistId}/checklist_item/${checklistItemId}`,
       { method: "PUT", body: JSON.stringify(updates) }
     );
-    return data.checklist;
+    return expectRecordField(
+      data,
+      "checklist",
+      "checklist"
+    );
   }
   async deleteChecklistItem(checklistId, checklistItemId) {
     await this.request(
@@ -348,7 +437,11 @@ var ClickUpClient = class {
     const query = params.toString();
     const url = `/team/${teamId}/time_entries${query ? `?${query}` : ""}`;
     const data = await this.request(url);
-    const entries = data.data ?? [];
+    const entries = readCollectionField(
+      data,
+      "data",
+      "time entries"
+    );
     if (opts?.taskId) {
       return entries.filter((e) => e.task?.id === opts.taskId);
     }
@@ -363,7 +456,7 @@ var ClickUpClient = class {
   }
   async getSpaceTags(spaceId) {
     const data = await this.request(`/space/${spaceId}/tag`);
-    return data.tags ?? [];
+    return readCollectionField(data, "tags", "space tags");
   }
   async createSpaceTag(spaceId, name, fg, bg) {
     await this.request(`/space/${spaceId}/tag`, {
@@ -381,7 +474,11 @@ var ClickUpClient = class {
   }
   async getWorkspaceMembers(teamId) {
     const data = await this.request("/team");
-    const team = data.teams?.find((t) => t.id === teamId);
+    const team = readCollectionField(
+      data,
+      "teams",
+      "workspace members"
+    ).find((t) => t.id === teamId);
     return team?.members?.map((m) => m.user) ?? [];
   }
   async deleteTimeEntry(teamId, timeEntryId) {
@@ -422,7 +519,7 @@ var ClickUpClient = class {
   }
   async getDocs(workspaceId) {
     const data = await this.requestV3(`/workspaces/${workspaceId}/docs`);
-    return data.docs ?? [];
+    return readCollectionField(data, "docs", "docs");
   }
   async getDocPage(workspaceId, docId, pageId) {
     return this.requestV3(
@@ -463,17 +560,21 @@ var ClickUpClient = class {
     const data = await this.requestV3(
       `/workspaces/${workspaceId}/docs/${docId}/pagelisting`
     );
-    return data.pages ?? [];
+    return readCollectionField(
+      data,
+      "pages",
+      "doc page listing"
+    );
   }
   async getDocPages(workspaceId, docId) {
     const data = await this.requestV3(
       `/workspaces/${workspaceId}/docs/${docId}/pages?content_format=text/md`
     );
-    return data.pages ?? [];
+    return readCollectionField(data, "pages", "doc pages");
   }
   async getGoals(teamId) {
     const data = await this.request(`/team/${teamId}/goal`);
-    return data.goals ?? [];
+    return readCollectionField(data, "goals", "goals");
   }
   async createGoal(teamId, name, opts) {
     const body = { name, multiple_owners: true };
@@ -553,7 +654,11 @@ var ClickUpClient = class {
     const data = await this.request(
       `/team/${teamId}/taskTemplate?page=0`
     );
-    return data.templates ?? [];
+    return readCollectionField(
+      data,
+      "templates",
+      "task templates"
+    );
   }
   async createTaskFromTemplate(listId, templateId, name) {
     return this.request(`/list/${listId}/taskTemplate/${templateId}`, {
@@ -567,6 +672,50 @@ var ClickUpClient = class {
 import fs from "fs";
 import { homedir } from "os";
 import { join } from "path";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readConfigString(parsed, key, path, strict) {
+  const value = parsed[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") {
+    if (strict) {
+      throw new Error(`Config field ${key} must be a string in ${path}.`);
+    }
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function parseConfigFile(raw, path, strictFields, strictRoot = strictFields) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    if (strictRoot) {
+      throw new Error(`Config file at ${path} contains invalid JSON. Please check the file syntax.`);
+    }
+    return {};
+  }
+  if (!isRecord2(parsed)) {
+    if (strictRoot) {
+      throw new Error(`Config file at ${path} must contain a JSON object.`);
+    }
+    return {};
+  }
+  const apiToken = readConfigString(parsed, "apiToken", path, strictFields);
+  const teamId = readConfigString(parsed, "teamId", path, strictFields);
+  const sprintFolderId = readConfigString(parsed, "sprintFolderId", path, strictFields);
+  return {
+    ...apiToken ? { apiToken } : {},
+    ...teamId ? { teamId } : {},
+    ...sprintFolderId ? { sprintFolderId } : {}
+  };
+}
+function trimConfigValue(value) {
+  const trimmed = value?.trim();
+  return trimmed || void 0;
+}
 function configDir() {
   const xdg = process.env.XDG_CONFIG_HOME;
   if (xdg) return join(xdg, "cup");
@@ -601,15 +750,10 @@ function loadConfig() {
   const path = configPath();
   if (fs.existsSync(path)) {
     const raw = fs.readFileSync(path, "utf-8");
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      throw new Error(`Config file at ${path} contains invalid JSON. Please check the file syntax.`);
-    }
-    fileToken = parsed.apiToken?.trim();
-    fileTeamId = parsed.teamId?.trim();
-    fileSprintFolderId = parsed.sprintFolderId?.trim() || void 0;
+    const parsed = parseConfigFile(raw, path, true);
+    fileToken = parsed.apiToken;
+    fileTeamId = parsed.teamId;
+    fileSprintFolderId = parsed.sprintFolderId;
   }
   const apiToken = envToken || fileToken;
   if (!apiToken) {
@@ -628,11 +772,7 @@ function loadRawConfig() {
   migrateFromLegacy();
   const path = configPath();
   if (!fs.existsSync(path)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(path, "utf-8"));
-  } catch {
-    return {};
-  }
+  return parseConfigFile(fs.readFileSync(path, "utf-8"), path, false, true);
 }
 function getConfigPath() {
   migrateFromLegacy();
@@ -644,7 +784,15 @@ function writeConfig(config) {
     fs.mkdirSync(dir, { recursive: true, mode: 448 });
   }
   const filePath = join(dir, "config.json");
-  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n", {
+  const apiToken = trimConfigValue(config.apiToken) ?? "";
+  const teamId = trimConfigValue(config.teamId) ?? "";
+  const sprintFolderId = trimConfigValue(config.sprintFolderId);
+  const normalizedConfig = {
+    ...apiToken ? { apiToken } : {},
+    ...teamId ? { teamId } : {},
+    ...sprintFolderId ? { sprintFolderId } : {}
+  };
+  fs.writeFileSync(filePath, JSON.stringify(normalizedConfig, null, 2) + "\n", {
     encoding: "utf-8",
     mode: 384
   });
@@ -2096,6 +2244,11 @@ async function fetchOverdueTasks(config, opts = {}) {
 
 // src/commands/config.ts
 var VALID_KEYS = /* @__PURE__ */ new Set(["apiToken", "teamId", "sprintFolderId"]);
+function readStoredString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
 function assertValidKey(key) {
   if (!VALID_KEYS.has(key)) {
     throw new Error(`Unknown config key: ${key}. Valid keys: ${[...VALID_KEYS].join(", ")}`);
@@ -2104,23 +2257,33 @@ function assertValidKey(key) {
 function getConfigValue(key) {
   assertValidKey(key);
   const raw = loadRawConfig();
-  const value = raw[key]?.trim();
-  return value || void 0;
+  return readStoredString(raw[key]);
 }
 function setConfigValue(key, value) {
   assertValidKey(key);
-  if (key === "apiToken" && !value.startsWith("pk_")) {
+  const normalizedValue = readStoredString(value);
+  if (key === "apiToken" && (!normalizedValue || !normalizedValue.startsWith("pk_"))) {
     throw new Error("apiToken must start with pk_");
   }
-  if (key === "teamId" && value.trim() === "") {
+  if (key === "teamId" && !normalizedValue) {
     throw new Error("teamId must be non-empty");
   }
   const raw = loadRawConfig();
+  const sprintFolderId = readStoredString(raw.sprintFolderId);
   const merged = {
-    apiToken: raw.apiToken ?? "",
-    teamId: raw.teamId ?? "",
-    ...{ [key]: value }
+    ...readStoredString(raw.apiToken) ? { apiToken: readStoredString(raw.apiToken) } : {},
+    ...readStoredString(raw.teamId) ? { teamId: readStoredString(raw.teamId) } : {},
+    ...sprintFolderId ? { sprintFolderId } : {}
   };
+  if (key === "sprintFolderId") {
+    if (normalizedValue) {
+      merged.sprintFolderId = normalizedValue;
+    } else {
+      delete merged.sprintFolderId;
+    }
+  } else {
+    merged[key] = normalizedValue;
+  }
   writeConfig(merged);
 }
 function configPath2() {
@@ -2199,7 +2362,702 @@ ${commentsMd}`);
   }
 }
 
+// src/commands/metadata.ts
+var commandMetadata = [
+  {
+    name: "init",
+    description: "Set up cup for the first time",
+    quickReference: [{ section: "setup", usage: "init", description: "First-time setup wizard" }]
+  },
+  {
+    name: "auth",
+    description: "Validate API token and show current user",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "auth", description: "Check authentication status" }
+    ]
+  },
+  {
+    name: "tasks",
+    description: "List tasks assigned to me",
+    flags: ["--status", "--list", "--space", "--name", "--type", "--include-closed", "--json"],
+    quickReference: [{ section: "read", usage: "tasks", description: "List tasks assigned to me" }]
+  },
+  {
+    name: "task",
+    description: "Get task details",
+    flags: ["--json"],
+    quickReference: [{ section: "read", usage: "task <taskId>", description: "Get task details" }]
+  },
+  {
+    name: "update",
+    description: "Update a task",
+    flags: [
+      "-n",
+      "--name",
+      "-d",
+      "--description",
+      "-s",
+      "--status",
+      "--priority",
+      "--due-date",
+      "--time-estimate",
+      "--assignee",
+      "--parent",
+      "--json"
+    ],
+    quickReference: [{ section: "write", usage: "update <taskId>", description: "Update a task" }]
+  },
+  {
+    name: "create",
+    description: "Create a new task",
+    flags: [
+      "-l",
+      "--list",
+      "-n",
+      "--name",
+      "-d",
+      "--description",
+      "-p",
+      "--parent",
+      "-s",
+      "--status",
+      "--priority",
+      "--due-date",
+      "--assignee",
+      "--tags",
+      "--custom-item-id",
+      "--time-estimate",
+      "--template",
+      "--json"
+    ],
+    quickReference: [{ section: "write", usage: "create", description: "Create a new task" }]
+  },
+  {
+    name: "sprint",
+    description: "List my tasks in the current active sprint (auto-detected)",
+    flags: ["--status", "--space", "--folder", "--include-closed", "--json"],
+    quickReference: [
+      { section: "read", usage: "sprint", description: "My tasks in the active sprint" }
+    ]
+  },
+  {
+    name: "sprints",
+    description: "List all sprints in sprint folders",
+    flags: ["--space", "--json"],
+    quickReference: [
+      { section: "read", usage: "sprints", description: "List all sprints across folders" }
+    ]
+  },
+  {
+    name: "subtasks",
+    description: "List subtasks of a task or initiative",
+    flags: ["--status", "--name", "--include-closed", "--json"],
+    quickReference: [
+      { section: "read", usage: "subtasks <taskId>", description: "List subtasks of a task" }
+    ]
+  },
+  {
+    name: "comment",
+    description: "Post a comment on a task",
+    flags: ["-m", "--message", "--notify-all", "--json"],
+    quickReference: [
+      { section: "write", usage: "comment <taskId>", description: "Post a comment on a task" }
+    ]
+  },
+  {
+    name: "comment-edit",
+    description: "Edit an existing comment",
+    flags: ["-m", "--message", "--resolved", "--unresolved", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "comment-edit <commentId>",
+        description: "Edit an existing comment"
+      }
+    ]
+  },
+  {
+    name: "comment-delete",
+    description: "Delete a comment",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "comment-delete <commentId>",
+        description: "Delete a comment"
+      }
+    ]
+  },
+  {
+    name: "comments",
+    description: "List comments on a task",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "comments <taskId>", description: "List comments on a task" }
+    ]
+  },
+  {
+    name: "replies",
+    description: "List threaded replies on a comment",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "read",
+        usage: "replies <commentId>",
+        description: "List threaded replies on a comment"
+      }
+    ]
+  },
+  {
+    name: "reply",
+    description: "Reply to a comment",
+    flags: ["-m", "--message", "--notify-all", "--json"],
+    quickReference: [
+      { section: "write", usage: "reply <commentId>", description: "Reply to a comment" }
+    ]
+  },
+  {
+    name: "activity",
+    description: "Show task details and comments combined",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "read",
+        usage: "activity <taskId>",
+        description: "Task details + comment history"
+      }
+    ]
+  },
+  {
+    name: "lists",
+    description: "List all lists in a space (including lists inside folders)",
+    flags: ["--name", "--json"],
+    quickReference: [
+      { section: "read", usage: "lists <spaceId>", description: "List all lists in a space" }
+    ]
+  },
+  {
+    name: "spaces",
+    description: "List spaces in your workspace",
+    flags: ["--name", "--my", "--json"],
+    quickReference: [{ section: "read", usage: "spaces", description: "List spaces in workspace" }]
+  },
+  {
+    name: "inbox",
+    description: "Recently updated tasks grouped by time period",
+    flags: ["--include-closed", "--json", "--days"],
+    quickReference: [
+      {
+        section: "read",
+        usage: "inbox",
+        description: "Recently updated tasks assigned to me"
+      }
+    ]
+  },
+  {
+    name: "assigned",
+    description: "Show all tasks assigned to me, grouped by status",
+    flags: ["--status", "--include-closed", "--json"],
+    quickReference: [
+      { section: "read", usage: "assigned", description: "My tasks grouped by pipeline stage" }
+    ]
+  },
+  {
+    name: "open",
+    description: "Open a task in the browser by ID or name",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "open <query>", description: "Open a task in the browser" }
+    ]
+  },
+  {
+    name: "search",
+    description: "Search my tasks by name",
+    flags: ["--status", "--include-closed", "--json"],
+    quickReference: [
+      { section: "read", usage: "search <query>", description: "Search my tasks by name" }
+    ]
+  },
+  {
+    name: "summary",
+    description: "Daily standup summary: completed, in-progress, overdue",
+    flags: ["--hours", "--json"],
+    quickReference: [{ section: "read", usage: "summary", description: "Daily standup helper" }]
+  },
+  {
+    name: "overdue",
+    description: "List tasks that are past their due date",
+    flags: ["--include-closed", "--json"],
+    quickReference: [
+      { section: "read", usage: "overdue", description: "Tasks past their due date" }
+    ]
+  },
+  {
+    name: "assign",
+    description: "Assign or unassign users from a task",
+    flags: ["--to", "--remove", "--json"],
+    quickReference: [
+      { section: "write", usage: "assign <taskId>", description: "Assign or unassign users" }
+    ]
+  },
+  {
+    name: "depend",
+    description: "Add or remove task dependencies",
+    flags: ["--on", "--blocks", "--remove", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "depend <taskId>",
+        description: "Add or remove task dependencies"
+      }
+    ]
+  },
+  {
+    name: "link",
+    description: "Add or remove a link between two tasks",
+    flags: ["--remove", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "link <taskId> <linksTo>",
+        description: "Add or remove a link between tasks"
+      }
+    ]
+  },
+  {
+    name: "attach",
+    description: "Upload a file attachment to a task",
+    flags: ["--json"],
+    bashFileCompletion: true,
+    quickReference: [
+      {
+        section: "write",
+        usage: "attach <taskId> <filePath>",
+        description: "Upload a file attachment to a task"
+      }
+    ]
+  },
+  {
+    name: "move",
+    description: "Add or remove a task from a list",
+    flags: ["--to", "--remove", "--json"],
+    quickReference: [
+      { section: "write", usage: "move <taskId>", description: "Add or remove a task from a list" }
+    ]
+  },
+  {
+    name: "field",
+    description: "Set or remove a custom field value on a task",
+    flags: ["--set", "--remove", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "field <taskId>",
+        description: "Set or remove custom field values"
+      }
+    ]
+  },
+  {
+    name: "delete",
+    description: "Delete a task (requires confirmation)",
+    flags: ["--confirm", "--json"],
+    quickReference: [{ section: "write", usage: "delete <taskId>", description: "Delete a task" }]
+  },
+  {
+    name: "tag",
+    description: "Add or remove tags from a task",
+    flags: ["--add", "--remove", "--json"],
+    quickReference: [
+      { section: "write", usage: "tag <taskId>", description: "Add or remove tags on a task" }
+    ]
+  },
+  {
+    name: "tags",
+    description: "List tags in a space",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "tags <spaceId>", description: "List tags in a space" }
+    ]
+  },
+  {
+    name: "tag-create",
+    description: "Create a tag in a space",
+    flags: ["--fg", "--bg", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "tag-create <spaceId> <name>",
+        description: "Create a tag in a space"
+      }
+    ]
+  },
+  {
+    name: "tag-delete",
+    description: "Delete a tag from a space",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "tag-delete <spaceId> <name>",
+        description: "Delete a tag from a space"
+      }
+    ]
+  },
+  {
+    name: "tag-update",
+    description: "Update a tag in a space",
+    flags: ["--name", "--fg", "--bg", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "tag-update <spaceId> <tagName>",
+        description: "Update a tag in a space"
+      }
+    ]
+  },
+  {
+    name: "checklist",
+    description: "Manage checklists on a task",
+    quickReference: [
+      { section: "write", usage: "checklist", description: "Manage checklists on tasks" }
+    ]
+  },
+  {
+    name: "time",
+    description: "Track time on tasks",
+    quickReference: [
+      {
+        section: "write",
+        usage: "time start <taskId>",
+        description: "Start tracking time on a task"
+      },
+      { section: "write", usage: "time stop", description: "Stop the running timer" },
+      { section: "write", usage: "time status", description: "Show the currently running timer" },
+      {
+        section: "write",
+        usage: "time log <taskId> <duration>",
+        description: "Log a manual time entry"
+      },
+      { section: "write", usage: "time list", description: "List recent time entries" },
+      { section: "write", usage: "time update <timeEntryId>", description: "Update a time entry" },
+      { section: "write", usage: "time delete <timeEntryId>", description: "Delete a time entry" }
+    ]
+  },
+  {
+    name: "docs",
+    description: "List workspace docs (optionally filter by name)",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "docs [query]", description: "List workspace docs" }
+    ]
+  },
+  {
+    name: "doc",
+    description: "View a doc (metadata + page tree) or a specific page",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "doc <docId> [pageId]", description: "View a doc or doc page" }
+    ]
+  },
+  {
+    name: "doc-create",
+    description: "Create a new doc",
+    flags: ["-c", "--content", "--json"],
+    quickReference: [
+      { section: "write", usage: "doc-create <title>", description: "Create a new doc" }
+    ]
+  },
+  {
+    name: "doc-pages",
+    description: "List all pages in a doc with content",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "read",
+        usage: "doc-pages <docId>",
+        description: "All pages in a doc with content"
+      }
+    ]
+  },
+  {
+    name: "doc-page-create",
+    description: "Create a page in a doc",
+    flags: ["-c", "--content", "--parent-page", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "doc-page-create <docId> <name>",
+        description: "Create a page in a doc"
+      }
+    ]
+  },
+  {
+    name: "doc-page-edit",
+    description: "Edit a doc page",
+    flags: ["--name", "-c", "--content", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "doc-page-edit <docId> <pageId>",
+        description: "Edit a doc page"
+      }
+    ]
+  },
+  {
+    name: "doc-delete",
+    description: "Delete a doc",
+    flags: ["--json"],
+    quickReference: [
+      { section: "write", usage: "doc-delete <docId>", description: "Delete a doc" }
+    ]
+  },
+  {
+    name: "doc-page-delete",
+    description: "Delete a doc page",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "doc-page-delete <docId> <pageId>",
+        description: "Delete a doc page"
+      }
+    ]
+  },
+  {
+    name: "folders",
+    description: "List folders in a space (with their lists)",
+    flags: ["--name", "--json"],
+    quickReference: [
+      { section: "read", usage: "folders <spaceId>", description: "List folders in a space" }
+    ]
+  },
+  {
+    name: "members",
+    description: "List workspace members",
+    flags: ["--json"],
+    quickReference: [{ section: "read", usage: "members", description: "List workspace members" }]
+  },
+  {
+    name: "fields",
+    description: "List custom fields for a list",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "fields <listId>", description: "List custom fields for a list" }
+    ]
+  },
+  {
+    name: "duplicate",
+    description: "Duplicate a task",
+    flags: ["--json"],
+    quickReference: [
+      { section: "write", usage: "duplicate <taskId>", description: "Duplicate a task" }
+    ]
+  },
+  {
+    name: "bulk",
+    description: "Bulk task operations",
+    quickReference: [
+      {
+        section: "write",
+        usage: "bulk status <status> <taskIds...>",
+        description: "Bulk update task status"
+      }
+    ]
+  },
+  {
+    name: "goals",
+    description: "List goals in your workspace",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "goals", description: "List goals in your workspace" }
+    ]
+  },
+  {
+    name: "goal-create",
+    description: "Create a goal",
+    flags: ["-d", "--description", "--color", "--json"],
+    quickReference: [
+      { section: "write", usage: "goal-create <name>", description: "Create a goal" }
+    ]
+  },
+  {
+    name: "goal-update",
+    description: "Update a goal",
+    flags: ["-n", "--name", "-d", "--description", "--color", "--json"],
+    quickReference: [
+      { section: "write", usage: "goal-update <goalId>", description: "Update a goal" }
+    ]
+  },
+  {
+    name: "goal-delete",
+    description: "Delete a goal",
+    flags: ["--json"],
+    quickReference: [
+      { section: "write", usage: "goal-delete <goalId>", description: "Delete a goal" }
+    ]
+  },
+  {
+    name: "key-results",
+    description: "List key results for a goal",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "read",
+        usage: "key-results <goalId>",
+        description: "List key results for a goal"
+      }
+    ]
+  },
+  {
+    name: "key-result-create",
+    description: "Create a key result on a goal",
+    flags: ["--type", "--target", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "key-result-create <goalId> <name>",
+        description: "Create a key result on a goal"
+      }
+    ]
+  },
+  {
+    name: "key-result-update",
+    description: "Update a key result",
+    flags: ["--progress", "--note", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "key-result-update <keyResultId>",
+        description: "Update a key result"
+      }
+    ]
+  },
+  {
+    name: "key-result-delete",
+    description: "Delete a key result",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "key-result-delete <keyResultId>",
+        description: "Delete a key result"
+      }
+    ]
+  },
+  {
+    name: "task-types",
+    description: "List custom task types in your workspace",
+    flags: ["--json"],
+    quickReference: [
+      { section: "read", usage: "task-types", description: "List custom task types" }
+    ]
+  },
+  {
+    name: "templates",
+    description: "List task templates in your workspace",
+    flags: ["--json"],
+    quickReference: [{ section: "read", usage: "templates", description: "List task templates" }]
+  },
+  {
+    name: "config",
+    description: "Manage CLI configuration",
+    quickReference: [
+      { section: "configuration", usage: "config", description: "Manage CLI configuration" }
+    ]
+  },
+  {
+    name: "completion",
+    description: "Output shell completion script (bash, zsh, fish)",
+    quickReference: [
+      {
+        section: "configuration",
+        usage: "completion <shell>",
+        description: "Output shell completion script"
+      }
+    ]
+  }
+];
+function parseCommandFlags(flags = []) {
+  const parsed = [];
+  for (const flag of flags) {
+    if (flag.startsWith("--")) {
+      const previous = parsed.at(-1);
+      if (previous && previous.long === "") {
+        previous.long = flag;
+      } else {
+        parsed.push({ long: flag });
+      }
+      continue;
+    }
+    parsed.push({ short: flag, long: "" });
+  }
+  return parsed.map((flag) => ({
+    short: flag.short,
+    long: flag.long
+  }));
+}
+function commandDescription(command, programName = "cup") {
+  if (command.name === "init") {
+    return `Set up ${programName} for the first time`;
+  }
+  return command.description;
+}
+function topLevelCommandDefinitions(programName = "cup") {
+  return commandMetadata.map((command) => ({
+    name: command.name,
+    description: commandDescription(command, programName),
+    flags: parseCommandFlags("flags" in command ? command.flags : [])
+  }));
+}
+function topLevelCommandNames() {
+  return commandMetadata.map((command) => command.name);
+}
+
 // src/commands/completion.ts
+var bashSpecialCaseCommands = /* @__PURE__ */ new Set(["checklist", "time", "bulk", "config", "completion"]);
+function escapeSingleQuotes(value) {
+  return value.replaceAll("'", "'\\''");
+}
+function renderBashCommandCases() {
+  return commandMetadata.filter(
+    (command) => !bashSpecialCaseCommands.has(command.name) && ((command.flags?.length ?? 0) > 0 || command.bashFileCompletion)
+  ).map((command) => {
+    if (command.bashFileCompletion) {
+      return `    ${command.name})
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=($(compgen -W "${command.flags?.join(" ") ?? ""}" -- "$cur"))
+      else
+        COMPREPLY=($(compgen -f -- "$cur"))
+      fi
+      ;;`;
+    }
+    return `    ${command.name})
+      COMPREPLY=($(compgen -W "${command.flags?.join(" ") ?? ""}" -- "$cur"))
+      ;;`;
+  }).join("\n");
+}
+function renderZshTopLevelCommands(name) {
+  return topLevelCommandDefinitions(name).map((command) => `    '${command.name}:${escapeSingleQuotes(command.description)}'`).join("\n");
+}
+function renderFishTopLevelCommands(name) {
+  return topLevelCommandDefinitions(name).map(
+    (command) => `complete -c ${name} -n __fish_use_subcommand -a ${command.name} -d '${escapeSingleQuotes(command.description)}'`
+  ).join("\n");
+}
+function renderFishFlagDefinition(name, commandName, flag) {
+  const parts = [`complete -c ${name} -n '__fish_seen_subcommand_from ${commandName}'`];
+  if (flag.short) {
+    parts.push(`-s ${flag.short.slice(1)}`);
+  }
+  parts.push(`-l ${flag.long.slice(2)}`);
+  return parts.join(" ");
+}
+function renderFishTopLevelFlags(name) {
+  return topLevelCommandDefinitions().filter((command) => command.flags.length > 0).flatMap(
+    (command) => command.flags.map((flag) => renderFishFlagDefinition(name, command.name, flag))
+  ).join("\n");
+}
 function bashCompletion(name) {
   return `_${name}_completions() {
   local cur prev words cword
@@ -2213,7 +3071,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 tags tag-create tag-delete tag-update checklist time docs doc doc-create doc-pages doc-page-create doc-page-edit doc-delete doc-page-delete folders members fields duplicate bulk goals goal-create goal-update goal-delete key-results key-result-create key-result-update key-result-delete task-types templates config completion"
+  local commands="${topLevelCommandNames().join(" ")}"
 
   if [[ $cword -eq 1 ]]; then
     COMPREPLY=($(compgen -W "$commands --help --version" -- "$cur"))
@@ -2234,81 +3092,7 @@ function bashCompletion(name) {
   esac
 
   case "$cmd" in
-    tasks)
-      COMPREPLY=($(compgen -W "--status --list --space --name --type --include-closed --json" -- "$cur"))
-      ;;
-    task)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    update)
-      COMPREPLY=($(compgen -W "-n --name -d --description -s --status --priority --due-date --time-estimate --assignee --parent --json" -- "$cur"))
-      ;;
-    create)
-      COMPREPLY=($(compgen -W "-l --list -n --name -d --description -p --parent -s --status --priority --due-date --assignee --tags --custom-item-id --time-estimate --template --json" -- "$cur"))
-      ;;
-    sprint)
-      COMPREPLY=($(compgen -W "--status --space --folder --include-closed --json" -- "$cur"))
-      ;;
-    sprints)
-      COMPREPLY=($(compgen -W "--space --json" -- "$cur"))
-      ;;
-    subtasks)
-      COMPREPLY=($(compgen -W "--status --name --include-closed --json" -- "$cur"))
-      ;;
-    comment)
-      COMPREPLY=($(compgen -W "-m --message --notify-all --json" -- "$cur"))
-      ;;
-    comments)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    activity)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    lists)
-      COMPREPLY=($(compgen -W "--name --json" -- "$cur"))
-      ;;
-    spaces)
-      COMPREPLY=($(compgen -W "--name --my --json" -- "$cur"))
-      ;;
-    inbox)
-      COMPREPLY=($(compgen -W "--include-closed --json --days" -- "$cur"))
-      ;;
-    assigned)
-      COMPREPLY=($(compgen -W "--status --include-closed --json" -- "$cur"))
-      ;;
-    open)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    search)
-      COMPREPLY=($(compgen -W "--status --include-closed --json" -- "$cur"))
-      ;;
-    summary)
-      COMPREPLY=($(compgen -W "--hours --json" -- "$cur"))
-      ;;
-    overdue)
-      COMPREPLY=($(compgen -W "--include-closed --json" -- "$cur"))
-      ;;
-    assign)
-      COMPREPLY=($(compgen -W "--to --remove --json" -- "$cur"))
-      ;;
-    auth)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    depend)
-      COMPREPLY=($(compgen -W "--on --blocks --remove --json" -- "$cur"))
-      ;;
-    move)
-      COMPREPLY=($(compgen -W "--to --remove --json" -- "$cur"))
-      ;;
-    field)
-      COMPREPLY=($(compgen -W "--set --remove --json" -- "$cur"))
-      ;;
-    delete)
-      COMPREPLY=($(compgen -W "--confirm --json" -- "$cur"))
-      ;;
-    tag)
-      COMPREPLY=($(compgen -W "--add --remove --json" -- "$cur"))
-      ;;
+${renderBashCommandCases()}
     checklist)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "view create delete add-item edit-item delete-item" -- "$cur"))
@@ -2319,107 +3103,11 @@ function bashCompletion(name) {
         COMPREPLY=($(compgen -W "start stop status log list update delete" -- "$cur"))
       fi
       ;;
-    comment-edit)
-      COMPREPLY=($(compgen -W "-m --message --resolved --unresolved --json" -- "$cur"))
-      ;;
-    comment-delete)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    replies)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    reply)
-      COMPREPLY=($(compgen -W "-m --message --notify-all --json" -- "$cur"))
-      ;;
-    link)
-      COMPREPLY=($(compgen -W "--remove --json" -- "$cur"))
-      ;;
-    attach)
-      COMPREPLY=($(compgen -f -- "$cur"))
-      ;;
-    docs)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    doc)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    doc-pages)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    tags)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    tag-create)
-      COMPREPLY=($(compgen -W "--fg --bg --json" -- "$cur"))
-      ;;
-    tag-delete)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    members)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    fields)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    duplicate)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
     bulk)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "status" -- "$cur"))
       fi
       ;;
-    goals)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    goal-create)
-      COMPREPLY=($(compgen -W "-d --description --color --json" -- "$cur"))
-      ;;
-    goal-update)
-      COMPREPLY=($(compgen -W "-n --name -d --description --color --json" -- "$cur"))
-      ;;
-    goal-delete)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    key-results)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    key-result-create)
-      COMPREPLY=($(compgen -W "--type --target --json" -- "$cur"))
-      ;;
-    key-result-update)
-      COMPREPLY=($(compgen -W "--progress --note --json" -- "$cur"))
-      ;;
-    key-result-delete)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    folders)
-      COMPREPLY=($(compgen -W "--name --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"))
-      ;;
-    doc-delete)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    doc-page-delete)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    tag-update)
-      COMPREPLY=($(compgen -W "--name --fg --bg --json" -- "$cur"))
-      ;;
-    task-types)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
-    templates)
-      COMPREPLY=($(compgen -W "--json" -- "$cur"))
-      ;;
     config)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "get set path" -- "$cur"))
@@ -2446,69 +3134,7 @@ function zshCompletion(name) {
 _${name}() {
   local -a commands
   commands=(
-    'init:Set up ${name} for the first time'
-    'auth:Validate API token and show current user'
-    'tasks:List tasks assigned to me'
-    'task:Get task details'
-    'update:Update a task'
-    'create:Create a new task'
-    'sprint:List my tasks in the current active sprint'
-    'sprints:List all sprints in sprint folders'
-    'subtasks:List subtasks of a task or initiative'
-    'comment:Post a comment on a task'
-    'comments:List comments on a task'
-    'activity:Show task details and comments combined'
-    'lists:List all lists in a space'
-    'spaces:List spaces in your workspace'
-    'inbox:Recently updated tasks grouped by time period'
-    'assigned:Show all tasks assigned to me'
-    'open:Open a task in the browser by ID or name'
-    'search:Search my tasks by name'
-    'summary:Daily standup summary'
-    'overdue:List tasks that are past their due date'
-    'assign:Assign or unassign users from a task'
-    'depend:Add or remove task dependencies'
-    'move:Add or remove a task from a list'
-    'field:Set or remove a custom field value on a task'
-    'delete:Delete a task'
-    'tag:Add or remove tags from a task'
-    'checklist:Manage checklists on a task'
-    'time:Track time on tasks'
-    'comment-edit:Edit an existing comment'
-    'comment-delete:Delete a comment'
-    'replies:List threaded replies on a comment'
-    '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 or doc page'
-    'doc-create:Create a new doc'
-    'doc-pages:List all pages in a doc with content'
-    'doc-page-create:Create a page in a doc'
-    'doc-page-edit:Edit a doc page'
-    'tags:List tags in a space'
-    'tag-create:Create a tag in a space'
-    'tag-delete:Delete a tag from a space'
-    'members:List workspace members'
-    'fields:List custom fields for a list'
-    'duplicate:Duplicate a task'
-    'bulk:Bulk task operations'
-    'goals:List goals in your workspace'
-    'goal-create:Create a goal'
-    'goal-update:Update a goal'
-    'goal-delete:Delete a goal'
-    'key-results:List key results for a goal'
-    'key-result-create:Create a key result on a goal'
-    'key-result-update:Update a key result'
-    'key-result-delete:Delete a key result'
-    'doc-delete:Delete a doc'
-    'doc-page-delete:Delete a doc page'
-    'tag-update:Update a tag in a space'
-    'task-types:List custom task types'
-    'templates:List task templates'
-    'folders:List folders in a space'
-    'config:Manage CLI configuration'
-    'completion:Output shell completion script'
+${renderZshTopLevelCommands(name)}
   )
 
   _arguments -C \\
@@ -3059,178 +3685,13 @@ function fishCompletion(name) {
 complete -c ${name} -n __fish_use_subcommand -s h -l help -d 'Show help'
 complete -c ${name} -n __fish_use_subcommand -s V -l version -d 'Show version'
 
-complete -c ${name} -n __fish_use_subcommand -a init -d 'Set up ${name} for the first time'
-complete -c ${name} -n __fish_use_subcommand -a auth -d 'Validate API token and show current user'
-complete -c ${name} -n __fish_use_subcommand -a tasks -d 'List tasks assigned to me'
-complete -c ${name} -n __fish_use_subcommand -a task -d 'Get task details'
-complete -c ${name} -n __fish_use_subcommand -a update -d 'Update a task'
-complete -c ${name} -n __fish_use_subcommand -a create -d 'Create a new task'
-complete -c ${name} -n __fish_use_subcommand -a sprint -d 'List my tasks in the current active sprint'
-complete -c ${name} -n __fish_use_subcommand -a sprints -d 'List all sprints in sprint folders'
-complete -c ${name} -n __fish_use_subcommand -a subtasks -d 'List subtasks of a task or initiative'
-complete -c ${name} -n __fish_use_subcommand -a comment -d 'Post a comment on a task'
-complete -c ${name} -n __fish_use_subcommand -a comments -d 'List comments on a task'
-complete -c ${name} -n __fish_use_subcommand -a activity -d 'Show task details and comments combined'
-complete -c ${name} -n __fish_use_subcommand -a lists -d 'List all lists in a space'
-complete -c ${name} -n __fish_use_subcommand -a spaces -d 'List spaces in your workspace'
-complete -c ${name} -n __fish_use_subcommand -a inbox -d 'Recently updated tasks grouped by time period'
-complete -c ${name} -n __fish_use_subcommand -a assigned -d 'Show all tasks assigned to me'
-complete -c ${name} -n __fish_use_subcommand -a open -d 'Open a task in the browser by ID or name'
-complete -c ${name} -n __fish_use_subcommand -a search -d 'Search my tasks by name'
-complete -c ${name} -n __fish_use_subcommand -a summary -d 'Daily standup summary'
-complete -c ${name} -n __fish_use_subcommand -a overdue -d 'List tasks that are past their due date'
-complete -c ${name} -n __fish_use_subcommand -a assign -d 'Assign or unassign users from a task'
-complete -c ${name} -n __fish_use_subcommand -a depend -d 'Add or remove task dependencies'
-complete -c ${name} -n __fish_use_subcommand -a move -d 'Add or remove a task from a list'
-complete -c ${name} -n __fish_use_subcommand -a field -d 'Set or remove a custom field value on a task'
-complete -c ${name} -n __fish_use_subcommand -a delete -d 'Delete a task'
-complete -c ${name} -n __fish_use_subcommand -a tag -d 'Add or remove tags from a task'
-complete -c ${name} -n __fish_use_subcommand -a checklist -d 'Manage checklists on a task'
-complete -c ${name} -n __fish_use_subcommand -a time -d 'Track time on tasks'
-complete -c ${name} -n __fish_use_subcommand -a comment-edit -d 'Edit an existing comment'
-complete -c ${name} -n __fish_use_subcommand -a comment-delete -d 'Delete a comment'
-complete -c ${name} -n __fish_use_subcommand -a replies -d 'List threaded replies on a comment'
-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 or 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-pages -d 'List all pages in a doc with content'
-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 tags -d 'List tags in a space'
-complete -c ${name} -n __fish_use_subcommand -a tag-create -d 'Create a tag in a space'
-complete -c ${name} -n __fish_use_subcommand -a tag-delete -d 'Delete a tag from a space'
-complete -c ${name} -n __fish_use_subcommand -a members -d 'List workspace members'
-complete -c ${name} -n __fish_use_subcommand -a fields -d 'List custom fields for a list'
-complete -c ${name} -n __fish_use_subcommand -a duplicate -d 'Duplicate a task'
-complete -c ${name} -n __fish_use_subcommand -a bulk -d 'Bulk task operations'
-complete -c ${name} -n __fish_use_subcommand -a goals -d 'List goals in your workspace'
-complete -c ${name} -n __fish_use_subcommand -a goal-create -d 'Create a goal'
-complete -c ${name} -n __fish_use_subcommand -a goal-update -d 'Update a goal'
-complete -c ${name} -n __fish_use_subcommand -a key-results -d 'List key results for a goal'
-complete -c ${name} -n __fish_use_subcommand -a key-result-create -d 'Create a key result on a goal'
-complete -c ${name} -n __fish_use_subcommand -a key-result-update -d 'Update a key result'
-complete -c ${name} -n __fish_use_subcommand -a goal-delete -d 'Delete a goal'
-complete -c ${name} -n __fish_use_subcommand -a key-result-delete -d 'Delete a key result'
-complete -c ${name} -n __fish_use_subcommand -a doc-delete -d 'Delete a doc'
-complete -c ${name} -n __fish_use_subcommand -a doc-page-delete -d 'Delete a doc page'
-complete -c ${name} -n __fish_use_subcommand -a tag-update -d 'Update a tag in a space'
-complete -c ${name} -n __fish_use_subcommand -a task-types -d 'List custom task types'
-complete -c ${name} -n __fish_use_subcommand -a templates -d 'List task templates'
-complete -c ${name} -n __fish_use_subcommand -a folders -d 'List folders in a space'
-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'
+${renderFishTopLevelCommands(name)}
 
-complete -c ${name} -n '__fish_seen_subcommand_from auth' -l json -d 'Force JSON output'
+${renderFishTopLevelFlags(name)}
 
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l status -d 'Filter by status'
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l list -d 'Filter by list ID'
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l space -d 'Filter by space ID'
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l name -d 'Filter by name'
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l type -d 'Filter by task type'
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l include-closed -d 'Include done/closed tasks'
-complete -c ${name} -n '__fish_seen_subcommand_from tasks' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from task' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from update' -s n -l name -d 'New task name'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -s d -l description -d 'New description'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -s s -l status -d 'New status'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -l priority -d 'Priority level' -a 'urgent high normal low'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -l due-date -d 'Due date'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -l time-estimate -d 'Time estimate'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -l assignee -d 'Add assignee'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -l parent -d 'Set parent task'
-complete -c ${name} -n '__fish_seen_subcommand_from update' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from create' -s l -l list -d 'Target list ID'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -s n -l name -d 'Task name'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -s d -l description -d 'Task description'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -s p -l parent -d 'Parent task ID'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -s s -l status -d 'Initial status'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l priority -d 'Priority level' -a 'urgent high normal low'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l due-date -d 'Due date'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l assignee -d 'Assignee user ID'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l tags -d 'Comma-separated tag names'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l custom-item-id -d 'Custom task type ID'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l time-estimate -d 'Time estimate'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l template -d 'Create from a task template'
-complete -c ${name} -n '__fish_seen_subcommand_from create' -l json -d 'Force JSON output'
-
-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'
-
-complete -c ${name} -n '__fish_seen_subcommand_from sprints' -l space -d 'Filter by space'
-complete -c ${name} -n '__fish_seen_subcommand_from sprints' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l status -d 'Filter by status'
-complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l name -d 'Filter by name'
-complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l include-closed -d 'Include closed/done subtasks'
-complete -c ${name} -n '__fish_seen_subcommand_from subtasks' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from comment' -s m -l message -d 'Comment text'
-complete -c ${name} -n '__fish_seen_subcommand_from comment' -l notify-all -d 'Notify all assignees'
-complete -c ${name} -n '__fish_seen_subcommand_from comment' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from comments' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from activity' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from lists' -l name -d 'Filter by name'
-complete -c ${name} -n '__fish_seen_subcommand_from lists' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from spaces' -l name -d 'Filter spaces by name'
-complete -c ${name} -n '__fish_seen_subcommand_from spaces' -l my -d 'Show only spaces where I have assigned tasks'
-complete -c ${name} -n '__fish_seen_subcommand_from spaces' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from inbox' -l include-closed -d 'Include done/closed tasks'
-complete -c ${name} -n '__fish_seen_subcommand_from inbox' -l json -d 'Force JSON output'
-complete -c ${name} -n '__fish_seen_subcommand_from inbox' -l days -d 'Lookback period in days'
-
-complete -c ${name} -n '__fish_seen_subcommand_from assigned' -l status -d 'Show only tasks with this status'
-complete -c ${name} -n '__fish_seen_subcommand_from assigned' -l include-closed -d 'Include done/closed tasks'
-complete -c ${name} -n '__fish_seen_subcommand_from assigned' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from open' -l json -d 'Output task JSON instead of opening'
-
-complete -c ${name} -n '__fish_seen_subcommand_from search' -l status -d 'Filter by status'
-complete -c ${name} -n '__fish_seen_subcommand_from search' -l include-closed -d 'Include done/closed tasks in search'
-complete -c ${name} -n '__fish_seen_subcommand_from search' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from summary' -l hours -d 'Completed-tasks lookback in hours'
-complete -c ${name} -n '__fish_seen_subcommand_from summary' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from overdue' -l include-closed -d 'Include done/closed overdue tasks'
-complete -c ${name} -n '__fish_seen_subcommand_from overdue' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from assign' -l to -d 'Add assignee'
-complete -c ${name} -n '__fish_seen_subcommand_from assign' -l remove -d 'Remove assignee'
-complete -c ${name} -n '__fish_seen_subcommand_from assign' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from depend' -l on -d 'Task that this task depends on'
-complete -c ${name} -n '__fish_seen_subcommand_from depend' -l blocks -d 'Task that this task blocks'
-complete -c ${name} -n '__fish_seen_subcommand_from depend' -l remove -d 'Remove the dependency'
-complete -c ${name} -n '__fish_seen_subcommand_from depend' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from move' -l to -d 'Add task to this list'
-complete -c ${name} -n '__fish_seen_subcommand_from move' -l remove -d 'Remove task from this list'
-complete -c ${name} -n '__fish_seen_subcommand_from move' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from field' -l set -d 'Set field name and value'
-complete -c ${name} -n '__fish_seen_subcommand_from field' -l remove -d 'Remove field value by name'
-complete -c ${name} -n '__fish_seen_subcommand_from field' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from delete' -l confirm -d 'Skip confirmation prompt'
-complete -c ${name} -n '__fish_seen_subcommand_from delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from tag' -l add -d 'Comma-separated tag names to add'
-complete -c ${name} -n '__fish_seen_subcommand_from tag' -l remove -d 'Comma-separated tag names to remove'
-complete -c ${name} -n '__fish_seen_subcommand_from tag' -l json -d 'Force JSON output'
+complete -c ${name} -n '__fish_seen_subcommand_from update' -l priority -a 'urgent high normal low'
+complete -c ${name} -n '__fish_seen_subcommand_from create' -l priority -a 'urgent high normal low'
+complete -c ${name} -n '__fish_seen_subcommand_from key-result-create' -l type -a 'number percentage'
 
 complete -c ${name} -n '__fish_seen_subcommand_from checklist; and not __fish_seen_subcommand_from view create delete add-item edit-item delete-item' -a view -d 'View checklists on a task'
 complete -c ${name} -n '__fish_seen_subcommand_from checklist; and not __fish_seen_subcommand_from view create delete add-item edit-item delete-item' -a create -d 'Create a checklist on a task'
@@ -3259,100 +3720,11 @@ complete -c ${name} -n '__fish_seen_subcommand_from list; and __fish_seen_subcom
 complete -c ${name} -n '__fish_seen_subcommand_from update; and __fish_seen_subcommand_from time' -s d -l description -d 'New description'
 complete -c ${name} -n '__fish_seen_subcommand_from update; and __fish_seen_subcommand_from time' -l duration -d 'New duration'
 
-complete -c ${name} -n '__fish_seen_subcommand_from comment-delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from replies' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from reply' -s m -l message -d 'Reply text'
-complete -c ${name} -n '__fish_seen_subcommand_from reply' -l notify-all -d 'Notify all assignees'
-complete -c ${name} -n '__fish_seen_subcommand_from reply' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from link' -l remove -d 'Remove the link'
-complete -c ${name} -n '__fish_seen_subcommand_from link' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from attach' -l json -d 'Force JSON output'
 complete -c ${name} -n '__fish_seen_subcommand_from attach' -F
 
-complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -s m -l message -d 'New comment text'
-complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l resolved -d 'Mark comment as resolved'
-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-pages' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from tags' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from tag-create' -l fg -d 'Foreground color'
-complete -c ${name} -n '__fish_seen_subcommand_from tag-create' -l bg -d 'Background color'
-complete -c ${name} -n '__fish_seen_subcommand_from tag-create' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from tag-delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from members' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from fields' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from duplicate' -l json -d 'Force JSON output'
-
 complete -c ${name} -n '__fish_seen_subcommand_from bulk; and not __fish_seen_subcommand_from status' -a status -d 'Update status of multiple tasks'
 complete -c ${name} -n '__fish_seen_subcommand_from status; and __fish_seen_subcommand_from bulk' -l json -d 'Force JSON output'
 
-complete -c ${name} -n '__fish_seen_subcommand_from goals' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from goal-create' -s d -l description -d 'Goal description'
-complete -c ${name} -n '__fish_seen_subcommand_from goal-create' -l color -d 'Goal color'
-complete -c ${name} -n '__fish_seen_subcommand_from goal-create' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from goal-update' -s n -l name -d 'New goal name'
-complete -c ${name} -n '__fish_seen_subcommand_from goal-update' -s d -l description -d 'New description'
-complete -c ${name} -n '__fish_seen_subcommand_from goal-update' -l color -d 'New color'
-complete -c ${name} -n '__fish_seen_subcommand_from goal-update' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from key-results' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-create' -l type -d 'Key result type' -a 'number percentage'
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-create' -l target -d 'Target value'
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-create' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-update' -l progress -d 'Current progress'
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-update' -l note -d 'Progress note'
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-update' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from goal-delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from key-result-delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from doc-delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from doc-page-delete' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from tag-update' -l name -d 'New tag name'
-complete -c ${name} -n '__fish_seen_subcommand_from tag-update' -l fg -d 'New foreground color'
-complete -c ${name} -n '__fish_seen_subcommand_from tag-update' -l bg -d 'New background color'
-complete -c ${name} -n '__fish_seen_subcommand_from tag-update' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from task-types' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from templates' -l json -d 'Force JSON output'
-
-complete -c ${name} -n '__fish_seen_subcommand_from folders' -l name -d 'Filter by folder name'
-complete -c ${name} -n '__fish_seen_subcommand_from folders' -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'
@@ -4162,984 +4534,1009 @@ function formatTemplatesMarkdown(templates) {
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
-var programName = basename(process.argv[1] ?? "cup");
 function wrapAction(fn) {
-  return (...args) => {
-    fn(...args).catch((err) => {
+  return async (...args) => {
+    await fn(...args).catch((err) => {
       console.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     });
   };
 }
-var program = new Command();
-program.name(programName).description("ClickUp CLI for AI agents").version(version).allowExcessArguments(false);
-program.command("init").description(`Set up ${programName} for the first time`).action(
-  wrapAction(async () => {
-    await runInitCommand();
-  })
-);
-program.command("auth").description("Validate API token and show current user").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const result = await checkAuth(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (result.authenticated && result.user) {
-      console.log(`Authenticated as @${result.user.username} (id: ${result.user.id})`);
-    } else {
-      throw new Error(`Authentication failed: ${result.error ?? "unknown error"}`);
-    }
-  })
-);
-program.command("tasks").description("List tasks assigned to me").option("--status <status>", 'Filter by status (e.g. "in progress")').option("--list <listId>", "Filter by list ID").option("--space <spaceId>", "Filter by space ID").option("--name <partial>", "Filter by name (case-insensitive contains)").option(
-  "--type <type>",
-  'Filter by task type (e.g. "task", "initiative", or custom type name/ID)'
-).option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const tasks = await fetchMyTasks(config, {
-      typeFilter: opts.type,
-      statuses: opts.status ? [opts.status] : void 0,
-      listIds: opts.list ? [opts.list] : void 0,
-      spaceIds: opts.space ? [opts.space] : void 0,
-      name: opts.name,
-      includeClosed: opts.includeClosed
-    });
-    await printTasks(tasks, opts.json ?? false, config);
-  })
-);
-program.command("task <taskId>").description("Get task details").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await getTask(config, taskId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (!isTTY()) {
-      console.log(formatTaskDetailMarkdown(result));
-    } else {
-      console.log(formatTaskDetail(result));
-    }
-  })
-);
-program.command("update <taskId>").description("Update a task").option("-n, --name <text>", "New task name").option("-d, --description <text>", "New description (markdown supported)").option("-s, --status <status>", 'New status (e.g. "in progress", "done")').option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--assignee <userId>", 'Add assignee by user ID or "me"').option("--parent <taskId>", "Set parent task (makes this a subtask)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    if (opts.assignee === "me") {
-      const client = new ClickUpClient(config);
-      opts.assignee = String(await resolveAssigneeId(client, "me"));
-    }
-    const payload = buildUpdatePayload(opts);
-    const result = await updateTask(config, taskId, payload);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(formatUpdateConfirmation(result.id, result.name));
-    }
-  })
-);
-program.command("create").description("Create a new task").option("-l, --list <listId>", "Target list ID (auto-detected from --parent if omitted)").requiredOption("-n, --name <name>", "Task name").option("-d, --description <text>", "Task description (markdown supported)").option("-p, --parent <taskId>", "Parent task ID (list auto-detected from parent)").option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", 'Assignee user ID or "me"').option("--tags <tags>", "Comma-separated tag names").option("--custom-item-id <id>", "Custom task type ID (use to create initiatives)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--template <id>", "Create from a task template").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    if (opts.assignee === "me") {
-      const client = new ClickUpClient(config);
-      opts.assignee = String(await resolveAssigneeId(client, "me"));
-    }
-    const result = await createTask(config, opts);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(formatCreateConfirmation(result.id, result.name, result.url));
-    }
-  })
-);
-program.command("sprint").description("List my tasks in the current active sprint (auto-detected)").option("--status <status>", "Filter by status").option("--space <nameOrId>", "Narrow sprint search to a specific space (partial name or ID)").option("--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) => {
+function parseOptionalNumberOption(value, optionName) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${optionName} must be a number or "null"`);
+  }
+  return parsed;
+}
+function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
+  const program = new Command();
+  program.name(programName).description("ClickUp CLI for AI agents").version(version).allowExcessArguments(false);
+  program.command("init").description(`Set up ${programName} for the first time`).action(
+    wrapAction(async () => {
+      await runInitCommand();
+    })
+  );
+  program.command("auth").description("Validate API token and show current user").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
       const config = loadConfig();
-      await runSprintCommand(config, opts);
-    }
-  )
-);
-program.command("sprints").description("List all sprints in sprint folders").option("--space <nameOrId>", "Filter by space (partial name or ID)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    await listSprints(config, opts);
-  })
-);
-program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--status <status>", "Filter by status").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--include-closed", "Include closed/done subtasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (taskId, opts) => {
+      const result = await checkAuth(config);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (result.authenticated && result.user) {
+        console.log(`Authenticated as @${result.user.username} (id: ${result.user.id})`);
+      } else {
+        throw new Error(`Authentication failed: ${result.error ?? "unknown error"}`);
+      }
+    })
+  );
+  program.command("tasks").description("List tasks assigned to me").option("--status <status>", 'Filter by status (e.g. "in progress")').option("--list <listId>", "Filter by list ID").option("--space <spaceId>", "Filter by space ID").option("--name <partial>", "Filter by name (case-insensitive contains)").option(
+    "--type <type>",
+    'Filter by task type (e.g. "task", "initiative", or custom type name/ID)'
+  ).option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const tasks = await fetchMyTasks(config, {
+        typeFilter: opts.type,
+        statuses: opts.status ? [opts.status] : void 0,
+        listIds: opts.list ? [opts.list] : void 0,
+        spaceIds: opts.space ? [opts.space] : void 0,
+        name: opts.name,
+        includeClosed: opts.includeClosed
+      });
+      await printTasks(tasks, opts.json ?? false, config);
+    })
+  );
+  program.command("task <taskId>").description("Get task details").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
       const config = loadConfig();
-      let tasks = await fetchSubtasks(config, taskId, { includeClosed: opts.includeClosed });
-      if (opts.status) {
-        const lower = opts.status.toLowerCase();
-        tasks = tasks.filter((t) => t.status.toLowerCase() === lower);
+      const result = await getTask(config, taskId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (!isTTY()) {
+        console.log(formatTaskDetailMarkdown(result));
+      } else {
+        console.log(formatTaskDetail(result));
       }
-      if (opts.name) {
-        const query = opts.name.toLowerCase();
-        tasks = tasks.filter((t) => t.name.toLowerCase().includes(query));
+    })
+  );
+  program.command("update <taskId>").description("Update a task").option("-n, --name <text>", "New task name").option("-d, --description <text>", "New description (markdown supported)").option("-s, --status <status>", 'New status (e.g. "in progress", "done")').option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--assignee <userId>", 'Add assignee by user ID or "me"').option("--parent <taskId>", "Set parent task (makes this a subtask)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      if (opts.assignee === "me") {
+        const client = new ClickUpClient(config);
+        opts.assignee = String(await resolveAssigneeId(client, "me"));
       }
-      await printTasks(tasks, opts.json ?? false, config);
-    }
-  )
-);
-program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (taskId, opts) => {
+      const payload = buildUpdatePayload(opts);
+      const result = await updateTask(config, taskId, payload);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatUpdateConfirmation(result.id, result.name));
+      }
+    })
+  );
+  program.command("create").description("Create a new task").option("-l, --list <listId>", "Target list ID (auto-detected from --parent if omitted)").requiredOption("-n, --name <name>", "Task name").option("-d, --description <text>", "Task description (markdown supported)").option("-p, --parent <taskId>", "Parent task ID (list auto-detected from parent)").option("-s, --status <status>", "Initial status").option("--priority <level>", "Priority: urgent, high, normal, low (or 1-4)").option("--due-date <date>", "Due date (YYYY-MM-DD)").option("--assignee <userId>", 'Assignee user ID or "me"').option("--tags <tags>", "Comma-separated tag names").option("--custom-item-id <id>", "Custom task type ID (use to create initiatives)").option("--time-estimate <duration>", 'Time estimate (e.g. "2h", "30m", "1h30m")').option("--template <id>", "Create from a task template").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
       const config = loadConfig();
-      const result = await postComment(config, taskId, opts.message, opts.notifyAll);
+      if (opts.assignee === "me") {
+        const client = new ClickUpClient(config);
+        opts.assignee = String(await resolveAssigneeId(client, "me"));
+      }
+      const result = await createTask(config, opts);
       if (shouldOutputJson(opts.json ?? false)) {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        console.log(formatCommentConfirmation(result.id));
+        console.log(formatCreateConfirmation(result.id, result.name, result.url));
       }
-    }
-  )
-);
-program.command("comments <taskId>").description("List comments on a task").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const comments = await fetchComments(config, taskId);
-    printComments(comments, opts.json ?? false);
-  })
-);
-program.command("comment-edit <commentId>").description("Edit an existing comment").requiredOption("-m, --message <text>", "New comment text").option("--resolved", "Mark comment as resolved").option("--unresolved", "Mark comment as unresolved").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (commentId, opts) => {
+    })
+  );
+  program.command("sprint").description("List my tasks in the current active sprint (auto-detected)").option("--status <status>", "Filter by status").option("--space <nameOrId>", "Narrow sprint search to a specific space (partial name or ID)").option("--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();
+        await runSprintCommand(config, opts);
+      }
+    )
+  );
+  program.command("sprints").description("List all sprints in sprint folders").option("--space <nameOrId>", "Filter by space (partial name or ID)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      await listSprints(config, opts);
+    })
+  );
+  program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--status <status>", "Filter by status").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--include-closed", "Include closed/done subtasks").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (taskId, opts) => {
+        const config = loadConfig();
+        let tasks = await fetchSubtasks(config, taskId, { includeClosed: opts.includeClosed });
+        if (opts.status) {
+          const lower = opts.status.toLowerCase();
+          tasks = tasks.filter((t) => t.status.toLowerCase() === lower);
+        }
+        if (opts.name) {
+          const query = opts.name.toLowerCase();
+          tasks = tasks.filter((t) => t.name.toLowerCase().includes(query));
+        }
+        await printTasks(tasks, opts.json ?? false, config);
+      }
+    )
+  );
+  program.command("comment <taskId>").description("Post a comment on a task").requiredOption("-m, --message <text>", "Comment text").option("--notify-all", "Notify all assignees").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (taskId, opts) => {
+        const config = loadConfig();
+        const result = await postComment(config, taskId, opts.message, opts.notifyAll);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(formatCommentConfirmation(result.id));
+        }
+      }
+    )
+  );
+  program.command("comments <taskId>").description("List comments on a task").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      const comments = await fetchComments(config, taskId);
+      printComments(comments, opts.json ?? false);
+    })
+  );
+  program.command("comment-edit <commentId>").description("Edit an existing comment").requiredOption("-m, --message <text>", "New comment text").option("--resolved", "Mark comment as resolved").option("--unresolved", "Mark comment as unresolved").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (commentId, opts) => {
+        const config = loadConfig();
+        let resolved;
+        if (opts.resolved) resolved = true;
+        if (opts.unresolved) resolved = false;
+        await editComment(config, commentId, opts.message, resolved);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify({ success: true, commentId }, null, 2));
+        } else {
+          console.log(`Comment ${commentId} updated`);
+        }
+      }
+    )
+  );
+  program.command("comment-delete <commentId>").description("Delete a comment").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (commentId, opts) => {
       const config = loadConfig();
-      let resolved;
-      if (opts.resolved) resolved = true;
-      if (opts.unresolved) resolved = false;
-      await editComment(config, commentId, opts.message, resolved);
+      await deleteComment(config, commentId);
       if (shouldOutputJson(opts.json ?? false)) {
         console.log(JSON.stringify({ success: true, commentId }, null, 2));
       } else {
-        console.log(`Comment ${commentId} updated`);
+        console.log(`Deleted comment ${commentId}`);
       }
-    }
-  )
-);
-program.command("comment-delete <commentId>").description("Delete a comment").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (commentId, opts) => {
-    const config = loadConfig();
-    await deleteComment(config, commentId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, commentId }, null, 2));
-    } else {
-      console.log(`Deleted comment ${commentId}`);
-    }
-  })
-);
-program.command("replies <commentId>").description("List threaded replies on a comment").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (commentId, opts) => {
-    const config = loadConfig();
-    const replies = await getReplies(config, commentId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(replies, null, 2));
-    } else if (isTTY()) {
-      console.log(formatReplies(replies));
-    } else {
-      console.log(formatRepliesMarkdown(replies));
-    }
-  })
-);
-program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--notify-all", "Notify all assignees").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (commentId, opts) => {
+    })
+  );
+  program.command("replies <commentId>").description("List threaded replies on a comment").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (commentId, opts) => {
       const config = loadConfig();
-      await createReply(config, commentId, opts.message, opts.notifyAll);
+      const replies = await getReplies(config, commentId);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify({ success: true, commentId }, null, 2));
+        console.log(JSON.stringify(replies, null, 2));
+      } else if (isTTY()) {
+        console.log(formatReplies(replies));
       } else {
-        console.log(`Replied to comment ${commentId}`);
+        console.log(formatRepliesMarkdown(replies));
       }
-    }
-  )
-);
-program.command("activity <taskId>").description("Show task details and comments combined").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await fetchActivity(config, taskId);
-    printActivity(result, opts.json ?? false);
-  })
-);
-program.command("lists <spaceId>").description("List all lists in a space (including lists inside folders)").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (spaceId, opts) => {
-    const config = loadConfig();
-    const lists = await fetchLists(config, spaceId, { name: opts.name });
-    printLists(lists, opts.json ?? false);
-  })
-);
-program.command("spaces").description("List spaces in your workspace").option("--name <partial>", "Filter spaces by name (case-insensitive contains)").option("--my", "Show only spaces where I have assigned tasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    await listSpaces(config, opts);
-  })
-);
-program.command("inbox").description("Recently updated tasks grouped by time period").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").option("--days <n>", "Lookback period in days", "30").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const days = Number(opts.days ?? 30);
-    if (!Number.isFinite(days) || days <= 0) {
-      throw new Error("--days must be a positive number");
-    }
-    const tasks = await fetchInbox(config, days, { includeClosed: opts.includeClosed });
-    await printInbox(tasks, opts.json ?? false, config);
-  })
-);
-program.command("assigned").description("Show all tasks assigned to me, grouped by status").option("--status <status>", "Show only tasks with this status").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    await runAssignedCommand(config, opts);
-  })
-);
-program.command("open <query>").description("Open a task in the browser by ID or name").option("--json", "Output task JSON instead of opening").action(
-  wrapAction(async (query, opts) => {
-    const config = loadConfig();
-    await openTask(config, query, opts);
-  })
-);
-program.command("search <query>").description("Search my tasks by name").option("--status <status>", "Filter by status").option("--include-closed", "Include done/closed tasks in search").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (query, opts) => {
+    })
+  );
+  program.command("reply <commentId>").description("Reply to a comment").requiredOption("-m, --message <text>", "Reply text").option("--notify-all", "Notify all assignees").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (commentId, opts) => {
+        const config = loadConfig();
+        await createReply(config, commentId, opts.message, opts.notifyAll);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify({ success: true, commentId }, null, 2));
+        } else {
+          console.log(`Replied to comment ${commentId}`);
+        }
+      }
+    )
+  );
+  program.command("activity <taskId>").description("Show task details and comments combined").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
       const config = loadConfig();
-      const tasks = await searchTasks(config, query, {
-        status: opts.status,
-        includeClosed: opts.includeClosed
-      });
+      const result = await fetchActivity(config, taskId);
+      printActivity(result, opts.json ?? false);
+    })
+  );
+  program.command("lists <spaceId>").description("List all lists in a space (including lists inside folders)").option("--name <partial>", "Filter by name (case-insensitive contains)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (spaceId, opts) => {
+      const config = loadConfig();
+      const lists = await fetchLists(config, spaceId, { name: opts.name });
+      printLists(lists, opts.json ?? false);
+    })
+  );
+  program.command("spaces").description("List spaces in your workspace").option("--name <partial>", "Filter spaces by name (case-insensitive contains)").option("--my", "Show only spaces where I have assigned tasks").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      await listSpaces(config, opts);
+    })
+  );
+  program.command("inbox").description("Recently updated tasks grouped by time period").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").option("--days <n>", "Lookback period in days", "30").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const days = Number(opts.days ?? 30);
+      if (!Number.isFinite(days) || days <= 0) {
+        throw new Error("--days must be a positive number");
+      }
+      const tasks = await fetchInbox(config, days, { includeClosed: opts.includeClosed });
+      await printInbox(tasks, opts.json ?? false, config);
+    })
+  );
+  program.command("assigned").description("Show all tasks assigned to me, grouped by status").option("--status <status>", "Show only tasks with this status").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      await runAssignedCommand(config, opts);
+    })
+  );
+  program.command("open <query>").description("Open a task in the browser by ID or name").option("--json", "Output task JSON instead of opening").action(
+    wrapAction(async (query, opts) => {
+      const config = loadConfig();
+      await openTask(config, query, opts);
+    })
+  );
+  program.command("search <query>").description("Search my tasks by name").option("--status <status>", "Filter by status").option("--include-closed", "Include done/closed tasks in search").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (query, opts) => {
+        const config = loadConfig();
+        const tasks = await searchTasks(config, query, {
+          status: opts.status,
+          includeClosed: opts.includeClosed
+        });
+        await printTasks(tasks, opts.json ?? false, config);
+      }
+    )
+  );
+  program.command("summary").description("Daily standup summary: completed, in-progress, overdue").option("--hours <n>", "Completed-tasks lookback in hours", "24").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const hours = Number(opts.hours ?? 24);
+      if (!Number.isFinite(hours) || hours <= 0) {
+        throw new Error("--hours must be a positive number");
+      }
+      await runSummaryCommand(config, { hours, json: opts.json ?? false });
+    })
+  );
+  program.command("overdue").description("List tasks that are past their due date").option("--include-closed", "Include done/closed overdue tasks").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const tasks = await fetchOverdueTasks(config, { includeClosed: opts.includeClosed });
       await printTasks(tasks, opts.json ?? false, config);
-    }
-  )
-);
-program.command("summary").description("Daily standup summary: completed, in-progress, overdue").option("--hours <n>", "Completed-tasks lookback in hours", "24").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const hours = Number(opts.hours ?? 24);
-    if (!Number.isFinite(hours) || hours <= 0) {
-      throw new Error("--hours must be a positive number");
-    }
-    await runSummaryCommand(config, { hours, json: opts.json ?? false });
-  })
-);
-program.command("overdue").description("List tasks that are past their due date").option("--include-closed", "Include done/closed overdue tasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const tasks = await fetchOverdueTasks(config, { includeClosed: opts.includeClosed });
-    await printTasks(tasks, opts.json ?? false, config);
-  })
-);
-program.command("assign <taskId>").description("Assign or unassign users from a task").option("--to <userId>", 'Add assignee (user ID or "me")').option("--remove <userId>", 'Remove assignee (user ID or "me")').option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await assignTask(config, taskId, opts);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(formatAssignConfirmation(taskId, { to: opts.to, remove: opts.remove }));
-    }
-  })
-);
-program.command("depend <taskId>").description("Add or remove task dependencies").option("--on <taskId>", "Task that this task depends on (waiting on)").option("--blocks <taskId>", "Task that this task blocks").option("--remove", "Remove the dependency instead of adding it").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const message = await manageDependency(config, taskId, opts);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(
-        JSON.stringify(
-          { taskId, on: opts.on, blocks: opts.blocks, remove: opts.remove, message },
-          null,
-          2
-        )
-      );
-    } else {
-      console.log(message);
-    }
-  })
-);
-program.command("link <taskId> <linksTo>").description("Add or remove a link between two tasks").option("--remove", "Remove the link instead of adding it").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (taskId, linksTo, opts) => {
+    })
+  );
+  program.command("assign <taskId>").description("Assign or unassign users from a task").option("--to <userId>", 'Add assignee (user ID or "me")').option("--remove <userId>", 'Remove assignee (user ID or "me")').option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      const result = await assignTask(config, taskId, opts);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatAssignConfirmation(taskId, { to: opts.to, remove: opts.remove }));
+      }
+    })
+  );
+  program.command("depend <taskId>").description("Add or remove task dependencies").option("--on <taskId>", "Task that this task depends on (waiting on)").option("--blocks <taskId>", "Task that this task blocks").option("--remove", "Remove the dependency instead of adding it").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
       const config = loadConfig();
-      const result = await manageTaskLink(config, taskId, linksTo, opts.remove ?? false);
+      const message = await manageDependency(config, taskId, opts);
       if (shouldOutputJson(opts.json ?? false)) {
         console.log(
           JSON.stringify(
-            { success: true, taskId, linksTo, action: opts.remove ? "removed" : "added" },
+            { taskId, on: opts.on, blocks: opts.blocks, remove: opts.remove, message },
             null,
             2
           )
         );
       } else {
-        console.log(result);
+        console.log(message);
       }
-    }
-  )
-);
-program.command("attach <taskId> <filePath>").description("Upload a file attachment to a task").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, filePath, opts) => {
-    const config = loadConfig();
-    const result = await attachFile(config, taskId, filePath);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Uploaded "${result.title}" to task ${taskId}`);
-      console.log(`  ${result.url}`);
-    }
-  })
-);
-program.command("move <taskId>").description("Add or remove a task from a list").option("--to <listId>", "Add task to this list").option("--remove <listId>", "Remove task from this list").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const message = await moveTask(config, taskId, opts);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ taskId, to: opts.to, remove: opts.remove, message }, null, 2));
-    } else {
-      console.log(message);
-    }
-  })
-);
-program.command("field <taskId>").description("Set or remove a custom field value on a task").option("--set <nameAndValue...>", 'Set field: --set "Field Name" value').option("--remove <fieldName>", "Remove field value by name").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (taskId, opts) => {
-      const config = loadConfig();
-      const fieldOpts = {};
-      if (opts.set) {
-        if (opts.set.length !== 2) {
-          throw new Error("--set requires exactly two arguments: field name and value");
+    })
+  );
+  program.command("link <taskId> <linksTo>").description("Add or remove a link between two tasks").option("--remove", "Remove the link instead of adding it").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (taskId, linksTo, opts) => {
+        const config = loadConfig();
+        const result = await manageTaskLink(config, taskId, linksTo, opts.remove ?? false);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(
+            JSON.stringify(
+              { success: true, taskId, linksTo, action: opts.remove ? "removed" : "added" },
+              null,
+              2
+            )
+          );
+        } else {
+          console.log(result);
         }
-        fieldOpts.set = [opts.set[0], opts.set[1]];
       }
-      if (opts.remove) {
-        fieldOpts.remove = opts.remove;
+    )
+  );
+  program.command("attach <taskId> <filePath>").description("Upload a file attachment to a task").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, filePath, opts) => {
+      const config = loadConfig();
+      const result = await attachFile(config, taskId, filePath);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Uploaded "${result.title}" to task ${taskId}`);
+        console.log(`  ${result.url}`);
       }
-      const { results } = await setCustomField(config, taskId, fieldOpts);
+    })
+  );
+  program.command("move <taskId>").description("Add or remove a task from a list").option("--to <listId>", "Add task to this list").option("--remove <listId>", "Remove task from this list").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      const message = await moveTask(config, taskId, opts);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(results, null, 2));
+        console.log(
+          JSON.stringify({ taskId, to: opts.to, remove: opts.remove, message }, null, 2)
+        );
       } else {
-        for (const r of results) {
-          if (r.action === "set") {
-            console.log(`Set "${r.field}" to ${JSON.stringify(r.value)} on ${r.taskId}`);
-          } else {
-            console.log(`Removed "${r.field}" from ${r.taskId}`);
+        console.log(message);
+      }
+    })
+  );
+  program.command("field <taskId>").description("Set or remove a custom field value on a task").option("--set <nameAndValue...>", 'Set field: --set "Field Name" value').option("--remove <fieldName>", "Remove field value by name").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (taskId, opts) => {
+        const config = loadConfig();
+        const fieldOpts = {};
+        if (opts.set) {
+          if (opts.set.length !== 2) {
+            throw new Error("--set requires exactly two arguments: field name and value");
+          }
+          fieldOpts.set = [opts.set[0], opts.set[1]];
+        }
+        if (opts.remove) {
+          fieldOpts.remove = opts.remove;
+        }
+        const { results } = await setCustomField(config, taskId, fieldOpts);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(results, null, 2));
+        } else {
+          for (const r of results) {
+            if (r.action === "set") {
+              console.log(`Set "${r.field}" to ${JSON.stringify(r.value)} on ${r.taskId}`);
+            } else {
+              console.log(`Removed "${r.field}" from ${r.taskId}`);
+            }
           }
         }
       }
-    }
-  )
-);
-program.command("delete <taskId>").description("Delete a task (requires confirmation)").option("--confirm", "Skip confirmation prompt (required in non-interactive mode)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await deleteTaskCommand(config, taskId, opts);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Deleted task ${result.taskId}`);
-    }
-  })
-);
-program.command("tag <taskId>").description("Add or remove tags from a task").option("--add <tags>", "Comma-separated tag names to add").option("--remove <tags>", "Comma-separated tag names to remove").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await manageTags(config, taskId, opts);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const parts = [];
-      if (result.added.length > 0) parts.push(`Added tags: ${result.added.join(", ")}`);
-      if (result.removed.length > 0) parts.push(`Removed tags: ${result.removed.join(", ")}`);
-      console.log(parts.join("; "));
-    }
-  })
-);
-var checklistCmd = program.command("checklist").description("Manage checklists on a task");
-checklistCmd.command("view <taskId>").description("View checklists on a task").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const checklists = await viewChecklists(config, taskId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(checklists, null, 2));
-    } else if (isTTY()) {
-      console.log(formatChecklists(checklists));
-    } else {
-      console.log(formatChecklistsMarkdown(checklists));
-    }
-  })
-);
-checklistCmd.command("create <taskId> <name>").description("Create a checklist on a task").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, name, opts) => {
-    const config = loadConfig();
-    const result = await createChecklist(config, taskId, name);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Created checklist "${result.name}" (id: ${result.id})`);
-    }
-  })
-);
-checklistCmd.command("delete <checklistId>").description("Delete a checklist").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (checklistId, opts) => {
-    const config = loadConfig();
-    const result = await deleteChecklist(config, checklistId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Deleted checklist ${result.checklistId}`);
-    }
-  })
-);
-checklistCmd.command("add-item <checklistId> <name>").description("Add an item to a checklist").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (checklistId, name, opts) => {
-    const config = loadConfig();
-    const result = await addChecklistItem(config, checklistId, name);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Added item "${name}" to checklist ${checklistId}`);
-    }
-  })
-);
-checklistCmd.command("edit-item <checklistId> <checklistItemId>").description("Edit a checklist item").option("--name <name>", "New item name").option("--resolved", "Mark item as resolved").option("--unresolved", "Mark item as unresolved").option("--assignee <userId>", 'Assign user by ID (use "null" to unassign)').option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (checklistId, checklistItemId, opts) => {
+    )
+  );
+  program.command("delete <taskId>").description("Delete a task (requires confirmation)").option("--confirm", "Skip confirmation prompt (required in non-interactive mode)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
       const config = loadConfig();
-      const updates = {};
-      if (opts.name) updates.name = opts.name;
-      if (opts.resolved) updates.resolved = true;
-      if (opts.unresolved) updates.resolved = false;
-      if (opts.assignee !== void 0) {
-        updates.assignee = opts.assignee === "null" ? null : Number(opts.assignee);
+      const result = await deleteTaskCommand(config, taskId, opts);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Deleted task ${result.taskId}`);
+      }
+    })
+  );
+  program.command("tag <taskId>").description("Add or remove tags from a task").option("--add <tags>", "Comma-separated tag names to add").option("--remove <tags>", "Comma-separated tag names to remove").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (taskId, opts) => {
+        const config = loadConfig();
+        const result = await manageTags(config, taskId, opts);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          const parts = [];
+          if (result.added.length > 0) parts.push(`Added tags: ${result.added.join(", ")}`);
+          if (result.removed.length > 0) parts.push(`Removed tags: ${result.removed.join(", ")}`);
+          console.log(parts.join("; "));
+        }
       }
-      const result = await editChecklistItem(config, checklistId, checklistItemId, updates);
+    )
+  );
+  const checklistCmd = program.command("checklist").description("Manage checklists on a task");
+  checklistCmd.command("view <taskId>").description("View checklists on a task").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      const checklists = await viewChecklists(config, taskId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(checklists, null, 2));
+      } else if (isTTY()) {
+        console.log(formatChecklists(checklists));
+      } else {
+        console.log(formatChecklistsMarkdown(checklists));
+      }
+    })
+  );
+  checklistCmd.command("create <taskId> <name>").description("Create a checklist on a task").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, name, opts) => {
+      const config = loadConfig();
+      const result = await createChecklist(config, taskId, name);
       if (shouldOutputJson(opts.json ?? false)) {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        console.log(`Updated checklist item ${checklistItemId}`);
+        console.log(`Created checklist "${result.name}" (id: ${result.id})`);
       }
-    }
-  )
-);
-checklistCmd.command("delete-item <checklistId> <checklistItemId>").description("Delete a checklist item").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (checklistId, checklistItemId, opts) => {
-    const config = loadConfig();
-    const result = await deleteChecklistItem(config, checklistId, checklistItemId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Deleted checklist item ${result.checklistItemId}`);
-    }
-  })
-);
-var timeCmd = program.command("time").description("Track time on tasks");
-timeCmd.command("start <taskId>").description("Start tracking time on a task").option("-d, --description <text>", "Description for the time entry").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await startTimer(config, taskId, opts.description);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const taskName = result.task?.name ?? taskId;
-      console.log(`Started timer on "${taskName}"`);
-    }
-  })
-);
-timeCmd.command("stop").description("Stop the running timer").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const result = await stopTimer(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (isTTY()) {
-      console.log(formatTimeEntry(result));
-    } else {
-      console.log(formatTimeEntryMarkdown(result));
-    }
-  })
-);
-timeCmd.command("status").description("Show the currently running timer").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const result = await timerStatus(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (!result) {
-      console.log("No timer running");
-    } else if (isTTY()) {
-      console.log(formatTimeEntry(result));
-    } else {
-      console.log(formatTimeEntryMarkdown(result));
-    }
-  })
-);
-timeCmd.command("log <taskId> <duration>").description('Log a manual time entry (e.g. "2h", "30m", "1h30m")').option("-d, --description <text>", "Description for the time entry").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (taskId, duration, opts) => {
+    })
+  );
+  checklistCmd.command("delete <checklistId>").description("Delete a checklist").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (checklistId, opts) => {
       const config = loadConfig();
-      const result = await logTime(config, taskId, duration, opts.description);
+      const result = await deleteChecklist(config, checklistId);
       if (shouldOutputJson(opts.json ?? false)) {
         console.log(JSON.stringify(result, null, 2));
       } else {
-        console.log(`Logged ${duration} on task ${taskId}`);
+        console.log(`Deleted checklist ${result.checklistId}`);
       }
-    }
-  )
-);
-timeCmd.command("list").description("List recent time entries (default: last 7 days)").option("--days <n>", "Number of days to look back", "7").option("--task <taskId>", "Filter by task ID").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const days = opts.days ? Number(opts.days) : 7;
-    if (!Number.isFinite(days) || days <= 0) {
-      throw new Error("--days must be a positive number");
-    }
-    const entries = await listTimeEntries(config, { days, taskId: opts.task });
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(entries, null, 2));
-    } else if (isTTY()) {
-      console.log(formatTimeEntries(entries));
-    } else {
-      console.log(formatTimeEntriesMarkdown(entries));
-    }
-  })
-);
-timeCmd.command("update <timeEntryId>").description("Update a time entry").option("-d, --description <text>", "New description").option("--duration <duration>", 'New duration (e.g. "2h", "30m")').option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (timeEntryId, opts) => {
+    })
+  );
+  checklistCmd.command("add-item <checklistId> <name>").description("Add an item to a checklist").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (checklistId, name, opts) => {
       const config = loadConfig();
-      const entry = await updateTimeEntry(config, timeEntryId, {
-        description: opts.description,
-        duration: opts.duration
-      });
+      const result = await addChecklistItem(config, checklistId, name);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Added item "${name}" to checklist ${checklistId}`);
+      }
+    })
+  );
+  checklistCmd.command("edit-item <checklistId> <checklistItemId>").description("Edit a checklist item").option("--name <name>", "New item name").option("--resolved", "Mark item as resolved").option("--unresolved", "Mark item as unresolved").option("--assignee <userId>", 'Assign user by ID (use "null" to unassign)').option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (checklistId, checklistItemId, opts) => {
+        const config = loadConfig();
+        const updates = {};
+        if (opts.name) updates.name = opts.name;
+        if (opts.resolved) updates.resolved = true;
+        if (opts.unresolved) updates.resolved = false;
+        if (opts.assignee !== void 0) {
+          updates.assignee = opts.assignee === "null" ? null : parseOptionalNumberOption(opts.assignee, "--assignee");
+        }
+        const result = await editChecklistItem(config, checklistId, checklistItemId, updates);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`Updated checklist item ${checklistItemId}`);
+        }
+      }
+    )
+  );
+  checklistCmd.command("delete-item <checklistId> <checklistItemId>").description("Delete a checklist item").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (checklistId, checklistItemId, opts) => {
+      const config = loadConfig();
+      const result = await deleteChecklistItem(config, checklistId, checklistItemId);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(entry, null, 2));
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Deleted checklist item ${result.checklistItemId}`);
+      }
+    })
+  );
+  const timeCmd = program.command("time").description("Track time on tasks");
+  timeCmd.command("start <taskId>").description("Start tracking time on a task").option("-d, --description <text>", "Description for the time entry").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      const result = await startTimer(config, taskId, opts.description);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const taskName = result.task?.name ?? taskId;
+        console.log(`Started timer on "${taskName}"`);
+      }
+    })
+  );
+  timeCmd.command("stop").description("Stop the running timer").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const result = await stopTimer(config);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
       } else if (isTTY()) {
-        console.log(formatTimeEntry(entry));
+        console.log(formatTimeEntry(result));
       } else {
-        console.log(formatTimeEntryMarkdown(entry));
+        console.log(formatTimeEntryMarkdown(result));
       }
-    }
-  )
-);
-timeCmd.command("delete <timeEntryId>").description("Delete a time entry").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (timeEntryId, opts) => {
-    const config = loadConfig();
-    await deleteTimeEntry(config, timeEntryId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ deleted: timeEntryId }));
-    } else {
-      console.log(`Deleted time entry ${timeEntryId}`);
-    }
-  })
-);
-program.command("tags <spaceId>").description("List tags in a space").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (spaceId, opts) => {
-    const config = loadConfig();
-    const tags = await listSpaceTags(config, spaceId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(tags, null, 2));
-    } else if (isTTY()) {
-      console.log(formatTags(tags));
-    } else {
-      console.log(formatTagsMarkdown(tags));
-    }
-  })
-);
-program.command("tag-create <spaceId> <name>").description("Create a tag in a space").option("--fg <color>", "Foreground color (hex)").option("--bg <color>", "Background color (hex)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (spaceId, name, opts) => {
+    })
+  );
+  timeCmd.command("status").description("Show the currently running timer").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
       const config = loadConfig();
-      await createSpaceTag(config, spaceId, name, opts.fg, opts.bg);
+      const result = await timerStatus(config);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify({ success: true, spaceId, tag: name }, null, 2));
+        console.log(JSON.stringify(result, null, 2));
+      } else if (!result) {
+        console.log("No timer running");
+      } else if (isTTY()) {
+        console.log(formatTimeEntry(result));
       } else {
-        console.log(`Created tag "${name}" in space ${spaceId}`);
+        console.log(formatTimeEntryMarkdown(result));
       }
-    }
-  )
-);
-program.command("tag-delete <spaceId> <name>").description("Delete a tag from a space").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (spaceId, name, opts) => {
-    const config = loadConfig();
-    await deleteSpaceTag(config, spaceId, name);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, spaceId, tag: name }, null, 2));
-    } else {
-      console.log(`Deleted tag "${name}" from space ${spaceId}`);
-    }
-  })
-);
-program.command("members").description("List workspace members").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const members = await listMembers(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(members, null, 2));
-    } else if (isTTY()) {
-      console.log(formatMembers(members));
-    } else {
-      console.log(formatMembersMarkdown(members));
-    }
-  })
-);
-program.command("fields <listId>").description("List custom fields for a list").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (listId, opts) => {
-    const config = loadConfig();
-    const fields = await listFields(config, listId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(fields, null, 2));
-    } else if (isTTY()) {
-      console.log(formatFields(fields));
-    } else {
-      console.log(formatFieldsMarkdown(fields));
-    }
-  })
-);
-program.command("duplicate <taskId>").description("Duplicate a task").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (taskId, opts) => {
-    const config = loadConfig();
-    const result = await duplicateTask(config, taskId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Duplicated as "${result.name}" (${result.id})`);
-    }
-  })
-);
-var bulkCmd = program.command("bulk").description("Bulk task operations");
-bulkCmd.command("status <status> <taskIds...>").description("Update status of multiple tasks").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (status, taskIds, opts) => {
-    const config = loadConfig();
-    const result = await bulkUpdateStatus(config, taskIds, status);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(`Updated ${result.updated} tasks to "${status}"`);
-      if (result.failed.length > 0) {
-        for (const f of result.failed) {
-          console.log(`  Failed ${f.id}: ${f.reason}`);
+    })
+  );
+  timeCmd.command("log <taskId> <duration>").description('Log a manual time entry (e.g. "2h", "30m", "1h30m")').option("-d, --description <text>", "Description for the time entry").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (taskId, duration, opts) => {
+        const config = loadConfig();
+        const result = await logTime(config, taskId, duration, opts.description);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`Logged ${duration} on task ${taskId}`);
         }
       }
-    }
-  })
-);
-program.command("goals").description("List goals in your workspace").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const goals = await listGoals(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(goals, null, 2));
-    } else if (isTTY()) {
-      console.log(formatGoals(goals));
-    } else {
-      console.log(formatGoalsMarkdown(goals));
-    }
-  })
-);
-program.command("goal-create <name>").description("Create a goal").option("-d, --description <text>", "Goal description").option("--color <hex>", "Goal color (hex)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (name, opts) => {
+    )
+  );
+  timeCmd.command("list").description("List recent time entries (default: last 7 days)").option("--days <n>", "Number of days to look back", "7").option("--task <taskId>", "Filter by task ID").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
       const config = loadConfig();
-      const goal = await createGoal(config, name, {
-        description: opts.description,
-        color: opts.color
-      });
+      const days = opts.days ? Number(opts.days) : 7;
+      if (!Number.isFinite(days) || days <= 0) {
+        throw new Error("--days must be a positive number");
+      }
+      const entries = await listTimeEntries(config, { days, taskId: opts.task });
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(goal, null, 2));
+        console.log(JSON.stringify(entries, null, 2));
+      } else if (isTTY()) {
+        console.log(formatTimeEntries(entries));
       } else {
-        console.log(`Created goal "${goal.name}" (${goal.id})`);
+        console.log(formatTimeEntriesMarkdown(entries));
       }
-    }
-  )
-);
-program.command("goal-update <goalId>").description("Update a goal").option("-n, --name <text>", "New goal name").option("-d, --description <text>", "New description").option("--color <hex>", "New color (hex)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (goalId, opts) => {
+    })
+  );
+  timeCmd.command("update <timeEntryId>").description("Update a time entry").option("-d, --description <text>", "New description").option("--duration <duration>", 'New duration (e.g. "2h", "30m")').option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (timeEntryId, opts) => {
+        const config = loadConfig();
+        const entry = await updateTimeEntry(config, timeEntryId, {
+          description: opts.description,
+          duration: opts.duration
+        });
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(entry, null, 2));
+        } else if (isTTY()) {
+          console.log(formatTimeEntry(entry));
+        } else {
+          console.log(formatTimeEntryMarkdown(entry));
+        }
+      }
+    )
+  );
+  timeCmd.command("delete <timeEntryId>").description("Delete a time entry").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (timeEntryId, opts) => {
       const config = loadConfig();
-      const goal = await updateGoal(config, goalId, {
-        name: opts.name,
-        description: opts.description,
-        color: opts.color
-      });
+      await deleteTimeEntry(config, timeEntryId);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(goal, null, 2));
+        console.log(JSON.stringify({ deleted: timeEntryId }));
       } else {
-        console.log(`Updated goal "${goal.name}" (${goal.id})`);
+        console.log(`Deleted time entry ${timeEntryId}`);
       }
-    }
-  )
-);
-program.command("goal-delete <goalId>").description("Delete a goal").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (goalId, opts) => {
-    const config = loadConfig();
-    await deleteGoal(config, goalId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, goalId }, null, 2));
-    } else {
-      console.log(`Deleted goal ${goalId}`);
-    }
-  })
-);
-program.command("key-results <goalId>").description("List key results for a goal").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (goalId, opts) => {
-    const config = loadConfig();
-    const krs = await listKeyResults(config, goalId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(krs, null, 2));
-    } else if (isTTY()) {
-      console.log(formatKeyResults(krs));
-    } else {
-      console.log(formatKeyResultsMarkdown(krs));
-    }
-  })
-);
-program.command("key-result-create <goalId> <name>").description("Create a key result on a goal").option("--type <type>", "Key result type (number or percentage)", "number").option("--target <n>", "Target value", "100").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (goalId, name, opts) => {
+    })
+  );
+  program.command("tags <spaceId>").description("List tags in a space").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (spaceId, opts) => {
       const config = loadConfig();
-      const target = Number(opts.target ?? 100);
-      if (!Number.isFinite(target) || target <= 0) {
-        throw new Error("--target must be a positive number");
+      const tags = await listSpaceTags(config, spaceId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(tags, null, 2));
+      } else if (isTTY()) {
+        console.log(formatTags(tags));
+      } else {
+        console.log(formatTagsMarkdown(tags));
+      }
+    })
+  );
+  program.command("tag-create <spaceId> <name>").description("Create a tag in a space").option("--fg <color>", "Foreground color (hex)").option("--bg <color>", "Background color (hex)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (spaceId, name, opts) => {
+        const config = loadConfig();
+        await createSpaceTag(config, spaceId, name, opts.fg, opts.bg);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify({ success: true, spaceId, tag: name }, null, 2));
+        } else {
+          console.log(`Created tag "${name}" in space ${spaceId}`);
+        }
       }
-      const kr = await createKeyResult(config, goalId, name, opts.type ?? "number", target);
+    )
+  );
+  program.command("tag-delete <spaceId> <name>").description("Delete a tag from a space").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (spaceId, name, opts) => {
+      const config = loadConfig();
+      await deleteSpaceTag(config, spaceId, name);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(kr, null, 2));
+        console.log(JSON.stringify({ success: true, spaceId, tag: name }, null, 2));
       } else {
-        console.log(`Created key result "${kr.name}" (${kr.id})`);
+        console.log(`Deleted tag "${name}" from space ${spaceId}`);
       }
-    }
-  )
-);
-program.command("key-result-update <keyResultId>").description("Update a key result").option("--progress <n>", "Current progress value").option("--note <text>", "Progress note").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (keyResultId, opts) => {
+    })
+  );
+  program.command("members").description("List workspace members").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
       const config = loadConfig();
-      const updates = {};
-      if (opts.progress !== void 0) {
-        const p = Number(opts.progress);
-        if (!Number.isFinite(p)) throw new Error("--progress must be a number");
-        updates.progress = p;
+      const members = await listMembers(config);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(members, null, 2));
+      } else if (isTTY()) {
+        console.log(formatMembers(members));
+      } else {
+        console.log(formatMembersMarkdown(members));
       }
-      if (opts.note !== void 0) updates.note = opts.note;
-      const kr = await updateKeyResult(config, keyResultId, updates);
+    })
+  );
+  program.command("fields <listId>").description("List custom fields for a list").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (listId, opts) => {
+      const config = loadConfig();
+      const fields = await listFields(config, listId);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(kr, null, 2));
+        console.log(JSON.stringify(fields, null, 2));
+      } else if (isTTY()) {
+        console.log(formatFields(fields));
       } else {
-        console.log(`Updated key result "${kr.name}" (${kr.id})`);
+        console.log(formatFieldsMarkdown(fields));
       }
-    }
-  )
-);
-program.command("key-result-delete <keyResultId>").description("Delete a key result").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (keyResultId, opts) => {
-    const config = loadConfig();
-    await deleteKeyResult(config, keyResultId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, keyResultId }, null, 2));
-    } else {
-      console.log(`Deleted key result ${keyResultId}`);
-    }
-  })
-);
-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 (metadata + page tree) or a specific page").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (docId, pageId, opts) => {
-    const config = loadConfig();
-    if (pageId) {
-      const page = await getDocPage(config, docId, pageId);
+    })
+  );
+  program.command("duplicate <taskId>").description("Duplicate a task").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (taskId, opts) => {
+      const config = loadConfig();
+      const result = await duplicateTask(config, taskId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Duplicated as "${result.name}" (${result.id})`);
+      }
+    })
+  );
+  const bulkCmd = program.command("bulk").description("Bulk task operations");
+  bulkCmd.command("status <status> <taskIds...>").description("Update status of multiple tasks").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (status, taskIds, opts) => {
+      const config = loadConfig();
+      const result = await bulkUpdateStatus(config, taskIds, status);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Updated ${result.updated} tasks to "${status}"`);
+        if (result.failed.length > 0) {
+          for (const f of result.failed) {
+            console.log(`  Failed ${f.id}: ${f.reason}`);
+          }
+        }
+      }
+    })
+  );
+  program.command("goals").description("List goals in your workspace").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const goals = await listGoals(config);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(page, null, 2));
+        console.log(JSON.stringify(goals, null, 2));
+      } else if (isTTY()) {
+        console.log(formatGoals(goals));
       } else {
-        if (page.name) console.log(`# ${page.name}
+        console.log(formatGoalsMarkdown(goals));
+      }
+    })
+  );
+  program.command("goal-create <name>").description("Create a goal").option("-d, --description <text>", "Goal description").option("--color <hex>", "Goal color (hex)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (name, opts) => {
+        const config = loadConfig();
+        const goal = await createGoal(config, name, {
+          description: opts.description,
+          color: opts.color
+        });
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(goal, null, 2));
+        } else {
+          console.log(`Created goal "${goal.name}" (${goal.id})`);
+        }
+      }
+    )
+  );
+  program.command("goal-update <goalId>").description("Update a goal").option("-n, --name <text>", "New goal name").option("-d, --description <text>", "New description").option("--color <hex>", "New color (hex)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (goalId, opts) => {
+        const config = loadConfig();
+        const goal = await updateGoal(config, goalId, {
+          name: opts.name,
+          description: opts.description,
+          color: opts.color
+        });
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(goal, null, 2));
+        } else {
+          console.log(`Updated goal "${goal.name}" (${goal.id})`);
+        }
+      }
+    )
+  );
+  program.command("goal-delete <goalId>").description("Delete a goal").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (goalId, opts) => {
+      const config = loadConfig();
+      await deleteGoal(config, goalId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify({ success: true, goalId }, null, 2));
+      } else {
+        console.log(`Deleted goal ${goalId}`);
+      }
+    })
+  );
+  program.command("key-results <goalId>").description("List key results for a goal").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (goalId, opts) => {
+      const config = loadConfig();
+      const krs = await listKeyResults(config, goalId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(krs, null, 2));
+      } else if (isTTY()) {
+        console.log(formatKeyResults(krs));
+      } else {
+        console.log(formatKeyResultsMarkdown(krs));
+      }
+    })
+  );
+  program.command("key-result-create <goalId> <name>").description("Create a key result on a goal").option("--type <type>", "Key result type (number or percentage)", "number").option("--target <n>", "Target value", "100").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (goalId, name, opts) => {
+        const config = loadConfig();
+        const target = Number(opts.target ?? 100);
+        if (!Number.isFinite(target) || target <= 0) {
+          throw new Error("--target must be a positive number");
+        }
+        const kr = await createKeyResult(config, goalId, name, opts.type ?? "number", target);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(kr, null, 2));
+        } else {
+          console.log(`Created key result "${kr.name}" (${kr.id})`);
+        }
+      }
+    )
+  );
+  program.command("key-result-update <keyResultId>").description("Update a key result").option("--progress <n>", "Current progress value").option("--note <text>", "Progress note").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (keyResultId, opts) => {
+        const config = loadConfig();
+        const updates = {};
+        if (opts.progress !== void 0) {
+          const p = Number(opts.progress);
+          if (!Number.isFinite(p)) throw new Error("--progress must be a number");
+          updates.progress = p;
+        }
+        if (opts.note !== void 0) updates.note = opts.note;
+        const kr = await updateKeyResult(config, keyResultId, updates);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(kr, null, 2));
+        } else {
+          console.log(`Updated key result "${kr.name}" (${kr.id})`);
+        }
+      }
+    )
+  );
+  program.command("key-result-delete <keyResultId>").description("Delete a key result").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (keyResultId, opts) => {
+      const config = loadConfig();
+      await deleteKeyResult(config, keyResultId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify({ success: true, keyResultId }, null, 2));
+      } else {
+        console.log(`Deleted key result ${keyResultId}`);
+      }
+    })
+  );
+  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 (metadata + page tree) or a specific page").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (docId, pageId, opts) => {
+      const config = loadConfig();
+      if (pageId) {
+        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 ?? "");
+          console.log(page.content ?? "");
+        }
+      } else {
+        const { doc, pages } = await getDocInfo(config, docId);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify({ ...doc, pages }, null, 2));
+        } else if (isTTY()) {
+          console.log(formatDocInfo(doc, pages));
+        } else {
+          console.log(formatDocInfoMarkdown(doc, pages));
+        }
       }
-    } else {
-      const { doc, pages } = await getDocInfo(config, docId);
+    })
+  );
+  program.command("doc-pages <docId>").description("List all pages in a doc with content").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (docId, opts) => {
+      const config = loadConfig();
+      const pages = await getAllDocPages(config, docId);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify({ ...doc, pages }, null, 2));
+        console.log(JSON.stringify(pages, null, 2));
       } else if (isTTY()) {
-        console.log(formatDocInfo(doc, pages));
+        console.log(formatDocPages(pages));
       } else {
-        console.log(formatDocInfoMarkdown(doc, pages));
+        console.log(formatDocPagesMarkdown(pages));
       }
-    }
-  })
-);
-program.command("doc-pages <docId>").description("List all pages in a doc with content").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (docId, opts) => {
-    const config = loadConfig();
-    const pages = await getAllDocPages(config, docId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(pages, null, 2));
-    } else if (isTTY()) {
-      console.log(formatDocPages(pages));
-    } else {
-      console.log(formatDocPagesMarkdown(pages));
-    }
-  })
-);
-program.command("folders <spaceId>").description("List folders in a space (with their lists)").option("--name <partial>", "Filter folders by partial name match").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (spaceId, opts) => {
-    const config = loadConfig();
-    const folders = await listFolders(config, spaceId, opts.name);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(folders, null, 2));
-    } else if (isTTY()) {
-      console.log(formatFolders(folders));
-    } else {
-      console.log(formatFoldersMarkdown(folders));
-    }
-  })
-);
-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) => {
+    })
+  );
+  program.command("folders <spaceId>").description("List folders in a space (with their lists)").option("--name <partial>", "Filter folders by partial name match").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (spaceId, opts) => {
       const config = loadConfig();
-      const page = await createDocPage(config, docId, name, opts.content, opts.parentPage);
+      const folders = await listFolders(config, spaceId, opts.name);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(page, null, 2));
+        console.log(JSON.stringify(folders, null, 2));
+      } else if (isTTY()) {
+        console.log(formatFolders(folders));
       } else {
-        console.log(`Created page "${page.name}" (${page.id}) in doc ${docId}`);
+        console.log(formatFoldersMarkdown(folders));
       }
-    }
-  )
-);
-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) => {
+    })
+  );
+  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 page = await editDocPage(config, docId, pageId, {
-        name: opts.name,
-        content: opts.content
-      });
+      const result = await createDoc(config, title, opts.content);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(JSON.stringify(page, null, 2));
+        console.log(JSON.stringify(result, null, 2));
       } else {
-        console.log(`Updated page "${page.name}" (${page.id})`);
+        console.log(`Created doc "${result.title}" (${result.id})`);
       }
-    }
-  )
-);
-program.command("doc-delete <docId>").description("Delete a doc").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (docId, opts) => {
-    const config = loadConfig();
-    await deleteDoc(config, docId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, docId }, null, 2));
-    } else {
-      console.log(`Deleted doc ${docId}`);
-    }
-  })
-);
-program.command("doc-page-delete <docId> <pageId>").description("Delete a doc page").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (docId, pageId, opts) => {
-    const config = loadConfig();
-    await deleteDocPage(config, docId, pageId);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify({ success: true, docId, pageId }, null, 2));
-    } else {
-      console.log(`Deleted page ${pageId} from doc ${docId}`);
-    }
-  })
-);
-program.command("tag-update <spaceId> <tagName>").description("Update a tag in a space").requiredOption("--name <newName>", "New tag name").option("--fg <color>", "New foreground color (hex)").option("--bg <color>", "New background color (hex)").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(
-    async (spaceId, tagName, opts) => {
+    })
+  );
+  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})`);
+        }
+      }
+    )
+  );
+  program.command("doc-delete <docId>").description("Delete a doc").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (docId, opts) => {
       const config = loadConfig();
-      await updateSpaceTag(config, spaceId, tagName, {
-        name: opts.name,
-        fg: opts.fg,
-        bg: opts.bg
-      });
+      await deleteDoc(config, docId);
       if (shouldOutputJson(opts.json ?? false)) {
-        console.log(
-          JSON.stringify(
-            { success: true, spaceId, oldName: tagName, newName: opts.name },
-            null,
-            2
-          )
-        );
+        console.log(JSON.stringify({ success: true, docId }, null, 2));
       } else {
-        console.log(`Renamed tag "${tagName}" to "${opts.name}" in space ${spaceId}`);
+        console.log(`Deleted doc ${docId}`);
       }
-    }
-  )
-);
-program.command("task-types").description("List custom task types in your workspace").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const types = await listTaskTypes(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(types, null, 2));
-    } else if (isTTY()) {
-      console.log(formatTaskTypes(types));
-    } else {
-      console.log(formatTaskTypesMarkdown(types));
-    }
-  })
-);
-program.command("templates").description("List task templates in your workspace").option("--json", "Force JSON output even in terminal").action(
-  wrapAction(async (opts) => {
-    const config = loadConfig();
-    const templates = await listTemplates(config);
-    if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(templates, null, 2));
-    } else if (isTTY()) {
-      console.log(formatTemplates(templates));
-    } else {
-      console.log(formatTemplatesMarkdown(templates));
-    }
-  })
-);
-var configCmd = program.command("config").description("Manage CLI configuration");
-configCmd.command("get <key>").description("Print a config value").action(
-  wrapAction(async (key) => {
-    const value = getConfigValue(key);
-    if (value !== void 0) {
-      console.log(value);
-    }
-  })
-);
-configCmd.command("set <key> <value>").description("Set a config value").action(
-  wrapAction(async (key, value) => {
-    setConfigValue(key, value);
-  })
-);
-configCmd.command("path").description("Print config file path").action(
-  wrapAction(async () => {
-    console.log(configPath2());
-  })
-);
-program.command("completion <shell>").description("Output shell completion script (bash, zsh, fish)").action(
-  wrapAction(async (shell) => {
-    const script = generateCompletion(shell, programName);
-    process.stdout.write(script);
-  })
-);
+    })
+  );
+  program.command("doc-page-delete <docId> <pageId>").description("Delete a doc page").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (docId, pageId, opts) => {
+      const config = loadConfig();
+      await deleteDocPage(config, docId, pageId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify({ success: true, docId, pageId }, null, 2));
+      } else {
+        console.log(`Deleted page ${pageId} from doc ${docId}`);
+      }
+    })
+  );
+  program.command("tag-update <spaceId> <tagName>").description("Update a tag in a space").requiredOption("--name <newName>", "New tag name").option("--fg <color>", "New foreground color (hex)").option("--bg <color>", "New background color (hex)").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (spaceId, tagName, opts) => {
+        const config = loadConfig();
+        await updateSpaceTag(config, spaceId, tagName, {
+          name: opts.name,
+          fg: opts.fg,
+          bg: opts.bg
+        });
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(
+            JSON.stringify(
+              { success: true, spaceId, oldName: tagName, newName: opts.name },
+              null,
+              2
+            )
+          );
+        } else {
+          console.log(`Renamed tag "${tagName}" to "${opts.name}" in space ${spaceId}`);
+        }
+      }
+    )
+  );
+  program.command("task-types").description("List custom task types in your workspace").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const types = await listTaskTypes(config);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(types, null, 2));
+      } else if (isTTY()) {
+        console.log(formatTaskTypes(types));
+      } else {
+        console.log(formatTaskTypesMarkdown(types));
+      }
+    })
+  );
+  program.command("templates").description("List task templates in your workspace").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (opts) => {
+      const config = loadConfig();
+      const templates = await listTemplates(config);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(templates, null, 2));
+      } else if (isTTY()) {
+        console.log(formatTemplates(templates));
+      } else {
+        console.log(formatTemplatesMarkdown(templates));
+      }
+    })
+  );
+  const configCmd = program.command("config").description("Manage CLI configuration");
+  configCmd.command("get <key>").description("Print a config value").action(
+    wrapAction(async (key) => {
+      const value = getConfigValue(key);
+      if (value !== void 0) {
+        console.log(value);
+      }
+    })
+  );
+  configCmd.command("set <key> <value>").description("Set a config value").action(
+    wrapAction(async (key, value) => {
+      setConfigValue(key, value);
+    })
+  );
+  configCmd.command("path").description("Print config file path").action(
+    wrapAction(async () => {
+      console.log(configPath2());
+    })
+  );
+  program.command("completion <shell>").description("Output shell completion script (bash, zsh, fish)").action(
+    wrapAction(async (shell) => {
+      const script = generateCompletion(shell, programName);
+      process.stdout.write(script);
+    })
+  );
+  return program;
+}
+async function run(argv = process.argv) {
+  const programName = basename(argv[1] ?? "cup");
+  const program = buildProgram(programName);
+  await program.parseAsync(argv);
+}
 process.on("SIGINT", () => {
   process.stderr.write("\nInterrupted\n");
   process.exit(130);
 });
-program.parse();
+var isDirectExecution = process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isDirectExecution) {
+  await run();
+}
+export {
+  buildProgram,
+  run
+};