@krodak/clickup-cli 0.9.0 → 0.10.0

package/README.md

@@ -98,7 +98,7 @@ When output is piped (no TTY), all commands output **Markdown** by default - opt
 
 ## Commands
 
-24 commands total. All support `--help` for full flag details.
+25 commands total. All support `--help` for full flag details.
 
 ### `cu init`
 
@@ -190,6 +190,7 @@ List subtasks of a task or initiative.
 
 ```bash
 cu subtasks abc123
+cu subtasks abc123 --include-closed
 cu subtasks abc123 --json
 ```
 
@@ -205,18 +206,20 @@ cu update abc123 --priority high
 cu update abc123 --due-date 2025-03-15
 cu update abc123 --assignee 12345
 cu update abc123 -n "New name" -s "done" --priority urgent
+cu update abc123 --time-estimate 2h
 cu update abc123 -s "in progress" --json
 ```
 
-| Flag                       | Description                                                                 |
-| -------------------------- | --------------------------------------------------------------------------- |
-| `-n, --name <text>`        | New task name                                                               |
-| `-d, --description <text>` | New description (markdown supported)                                        |
-| `-s, --status <status>`    | New status, supports fuzzy matching (e.g. `"prog"` matches `"in progress"`) |
-| `--priority <level>`       | Priority: `urgent`, `high`, `normal`, `low` (or 1-4)                        |
-| `--due-date <date>`        | Due date (`YYYY-MM-DD`)                                                     |
-| `--assignee <userId>`      | Add assignee by numeric user ID                                             |
-| `--json`                   | Force JSON output even in terminal                                          |
+| Flag                         | Description                                                                 |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| `-n, --name <text>`          | New task name                                                               |
+| `-d, --description <text>`   | New description (markdown supported)                                        |
+| `-s, --status <status>`      | New status, supports fuzzy matching (e.g. `"prog"` matches `"in progress"`) |
+| `--priority <level>`         | Priority: `urgent`, `high`, `normal`, `low` (or 1-4)                        |
+| `--due-date <date>`          | Due date (`YYYY-MM-DD`)                                                     |
+| `--time-estimate <duration>` | Time estimate (e.g. `"2h"`, `"30m"`, `"1h30m"`)                             |
+| `--assignee <userId>`        | Add assignee by numeric user ID                                             |
+| `--json`                     | Force JSON output even in terminal                                          |
 
 ### `cu create`
 
@@ -228,21 +231,25 @@ cu create -n "Subtask name" -p <parentTaskId>    # --list auto-detected
 cu create -n "Task" -l <listId> -d "desc" -s "open"
 cu create -n "Task" -l <listId> --priority high --due-date 2025-06-01
 cu create -n "Task" -l <listId> --assignee 12345 --tags "bug,frontend"
+cu create -n "Initiative" -l <listId> --custom-item-id 1
+cu create -n "Task" -l <listId> --time-estimate 2h
 cu create -n "Fix bug" -l <listId> --json
 ```
 
-| Flag                       | Required         | Description                                          |
-| -------------------------- | ---------------- | ---------------------------------------------------- |
-| `-n, --name <name>`        | yes              | Task name                                            |
-| `-l, --list <listId>`      | if no `--parent` | Target list ID                                       |
-| `-p, --parent <taskId>`    | no               | Parent task (list auto-detected)                     |
-| `-d, --description <text>` | no               | Description (markdown)                               |
-| `-s, --status <status>`    | no               | Initial status                                       |
-| `--priority <level>`       | no               | Priority: `urgent`, `high`, `normal`, `low` (or 1-4) |
-| `--due-date <date>`        | no               | Due date (`YYYY-MM-DD`)                              |
-| `--assignee <userId>`      | no               | Assignee by numeric user ID                          |
-| `--tags <tags>`            | no               | Comma-separated tag names                            |
-| `--json`                   | no               | Force JSON output even in terminal                   |
+| Flag                         | Required         | Description                                          |
+| ---------------------------- | ---------------- | ---------------------------------------------------- |
+| `-n, --name <name>`          | yes              | Task name                                            |
+| `-l, --list <listId>`        | if no `--parent` | Target list ID                                       |
+| `-p, --parent <taskId>`      | no               | Parent task (list auto-detected)                     |
+| `-d, --description <text>`   | no               | Description (markdown)                               |
+| `-s, --status <status>`      | no               | Initial status                                       |
+| `--priority <level>`         | no               | Priority: `urgent`, `high`, `normal`, `low` (or 1-4) |
+| `--due-date <date>`          | no               | Due date (`YYYY-MM-DD`)                              |
+| `--time-estimate <duration>` | no               | Time estimate (e.g. `"2h"`, `"30m"`, `"1h30m"`)      |
+| `--assignee <userId>`        | no               | Assignee by numeric user ID                          |
+| `--tags <tags>`              | no               | Comma-separated tag names                            |
+| `--custom-item-id <id>`      | no               | Custom task type ID (for creating initiatives)       |
+| `--json`                     | no               | Force JSON output even in terminal                   |
 
 ### `cu comment <id>`
 
@@ -367,6 +374,25 @@ cu assign abc123 --to me --json
 | `--remove <userId>` | Remove assignee (user ID or `me`) |
 | `--json`            | Force JSON output                 |
 
+### `cu depend <id>`
+
+Add or remove task dependencies. Set a task as waiting on or blocking another task.
+
+```bash
+cu depend abc123 --on def456          # abc123 depends on (waits for) def456
+cu depend abc123 --blocks def456      # abc123 blocks def456
+cu depend abc123 --on def456 --remove # remove the dependency
+cu depend abc123 --blocks def456 --remove
+cu depend abc123 --on def456 --json
+```
+
+| Flag                | Description                                 |
+| ------------------- | ------------------------------------------- |
+| `--on <taskId>`     | Task that this task depends on (waiting on) |
+| `--blocks <taskId>` | Task that this task blocks                  |
+| `--remove`          | Remove the dependency instead of adding it  |
+| `--json`            | Force JSON output                           |
+
 ### `cu auth`
 
 Check authentication status. Validates your API token and shows your user info.

package/dist/index.js

@@ -135,6 +135,7 @@ var ClickUpClient = class {
     const baseParams = new URLSearchParams({
       subtasks: String(filters.subtasks ?? true)
     });
+    if (filters.includeClosed) baseParams.set("include_closed", "true");
     baseParams.append("assignees[]", String(me.id));
     for (const s of filters.statuses ?? []) baseParams.append("statuses[]", s);
     for (const id of filters.listIds ?? []) baseParams.append("list_ids[]", id);
@@ -161,9 +162,11 @@ var ClickUpClient = class {
     const data = await this.request(`/task/${taskId}/comment`);
     return data.comments ?? [];
   }
-  async getTasksFromList(listId, params = {}) {
+  async getTasksFromList(listId, params = {}, options = {}) {
     return this.paginate((page) => {
-      const qs = new URLSearchParams({ subtasks: "true", page: String(page), ...params }).toString();
+      const base = { subtasks: "true", page: String(page), ...params };
+      if (options.includeClosed) base["include_closed"] = "true";
+      const qs = new URLSearchParams(base).toString();
       return `/list/${listId}/task?${qs}`;
     });
   }
@@ -220,6 +223,23 @@ var ClickUpClient = class {
   async getViewTasks(viewId) {
     return this.paginate((page) => `/view/${viewId}/task?page=${page}`);
   }
+  async addDependency(taskId, opts) {
+    const body = {};
+    if (opts.dependsOn) body.depends_on = opts.dependsOn;
+    if (opts.dependencyOf) body.dependency_of = opts.dependencyOf;
+    await this.request(`/task/${taskId}/dependency`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async deleteDependency(taskId, opts) {
+    const params = new URLSearchParams();
+    if (opts.dependsOn) params.set("depends_on", opts.dependsOn);
+    if (opts.dependencyOf) params.set("dependency_of", opts.dependencyOf);
+    await this.request(`/task/${taskId}/dependency?${params.toString()}`, {
+      method: "DELETE"
+    });
+  }
 };
 
 // src/output.ts
@@ -677,6 +697,18 @@ function parseAssigneeId(value) {
   if (!Number.isInteger(id)) throw new Error("Assignee must be a numeric user ID");
   return id;
 }
+function parseTimeEstimate(value) {
+  const pattern = /^(?:(\d+)h)?(?:(\d+)m)?$/i;
+  const match = value.match(pattern);
+  if (match && (match[1] || match[2])) {
+    const hours = Number(match[1] ?? 0);
+    const minutes = Number(match[2] ?? 0);
+    return (hours * 60 + minutes) * 60 * 1e3;
+  }
+  const ms = Number(value);
+  if (Number.isFinite(ms) && ms > 0) return ms;
+  throw new Error('Time estimate must be a duration (e.g. "2h", "30m", "1h30m") or milliseconds');
+}
 function buildUpdatePayload(opts) {
   const payload = {};
   if (opts.name !== void 0) payload.name = opts.name;
@@ -690,10 +722,13 @@ function buildUpdatePayload(opts) {
   if (opts.assignee !== void 0) {
     payload.assignees = { add: [parseAssigneeId(opts.assignee)] };
   }
+  if (opts.timeEstimate !== void 0) {
+    payload.time_estimate = parseTimeEstimate(opts.timeEstimate);
+  }
   return payload;
 }
 function hasUpdateFields(options) {
-  return options.name !== void 0 || options.description !== void 0 || options.status !== void 0 || options.priority !== void 0 || options.due_date !== void 0 || options.assignees !== void 0;
+  return options.name !== void 0 || options.description !== void 0 || options.status !== void 0 || options.priority !== void 0 || options.due_date !== void 0 || options.time_estimate !== void 0 || options.assignees !== void 0;
 }
 async function resolveStatus(client, taskId, statusInput) {
   const task = await client.getTask(taskId);
@@ -713,7 +748,7 @@ async function resolveStatus(client, taskId, statusInput) {
 async function updateTask(config, taskId, options) {
   if (!hasUpdateFields(options))
     throw new Error(
-      "Provide at least one of: --name, --description, --status, --priority, --due-date, --assignee"
+      "Provide at least one of: --name, --description, --status, --priority, --due-date, --time-estimate, --assignee"
     );
   const client = new ClickUpClient(config);
   if (options.status !== void 0) {
@@ -753,6 +788,15 @@ async function createTask(config, options) {
   if (options.tags !== void 0) {
     payload.tags = options.tags.split(",").map((t) => t.trim());
   }
+  if (options.customItemId !== void 0) {
+    const id = Number(options.customItemId);
+    if (!Number.isInteger(id) || id < 0)
+      throw new Error("Custom item ID must be a non-negative integer");
+    payload.custom_item_id = id;
+  }
+  if (options.timeEstimate !== void 0) {
+    payload.time_estimate = parseTimeEstimate(options.timeEstimate);
+  }
   const task = await client.createTask(listId, payload);
   return { id: task.id, name: task.name, url: task.url };
 }
@@ -974,10 +1018,14 @@ async function listSprints(config, opts = {}) {
 }
 
 // src/commands/subtasks.ts
-async function fetchSubtasks(config, taskId) {
+async function fetchSubtasks(config, taskId, options = {}) {
   const client = new ClickUpClient(config);
   const parent = await client.getTask(taskId);
-  const tasks = await client.getTasksFromList(parent.list.id, { parent: taskId, subtasks: "false" });
+  const tasks = await client.getTasksFromList(
+    parent.list.id,
+    { parent: taskId, subtasks: "false" },
+    { includeClosed: options.includeClosed }
+  );
   return tasks.map(summarize);
 }
 
@@ -1244,7 +1292,9 @@ function groupByStatus(tasks, includeClosed) {
 }
 async function runAssignedCommand(config, opts) {
   const client = new ClickUpClient(config);
-  const allTasks = await client.getMyTasks(config.teamId);
+  const allTasks = await client.getMyTasks(config.teamId, {
+    includeClosed: opts.includeClosed
+  });
   const groups = groupByStatus(allTasks, opts.includeClosed ?? false);
   if (shouldOutputJson(opts.json ?? false)) {
     const result = {};
@@ -1970,6 +2020,31 @@ async function searchTasks(config, query, opts = {}) {
   return matched.map(summarize);
 }
 
+// src/commands/depend.ts
+async function manageDependency(config, taskId, opts) {
+  if (!opts.on && !opts.blocks) {
+    throw new Error("Provide --on <taskId> or --blocks <taskId>");
+  }
+  if (opts.on && opts.blocks) {
+    throw new Error("Provide only one of --on or --blocks per invocation");
+  }
+  const client = new ClickUpClient(config);
+  if (opts.remove) {
+    await client.deleteDependency(taskId, {
+      dependsOn: opts.on,
+      dependencyOf: opts.blocks
+    });
+    if (opts.on) return `Removed dependency: ${taskId} no longer depends on ${opts.on}`;
+    return `Removed dependency: ${taskId} no longer blocks ${opts.blocks}`;
+  }
+  await client.addDependency(taskId, {
+    dependsOn: opts.on,
+    dependencyOf: opts.blocks
+  });
+  if (opts.on) return `Added dependency: ${taskId} depends on ${opts.on}`;
+  return `Added dependency: ${taskId} blocks ${opts.blocks}`;
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -2041,7 +2116,7 @@ program.command("task <taskId>").description("Get task details").option("--json"
     }
   })
 );
-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("--assignee <userId>", "Add assignee by user ID").option("--json", "Force JSON output even in terminal").action(
+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").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
     const payload = buildUpdatePayload(opts);
@@ -2053,7 +2128,7 @@ program.command("update <taskId>").description("Update a task").option("-n, --na
     }
   })
 );
-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").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").option("--tags <tags>", "Comma-separated tag names").option("--json", "Force JSON output even in terminal").action(
+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").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").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("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     const result = await createTask(config, opts);
@@ -2076,10 +2151,10 @@ program.command("sprints").description("List all sprints in sprint folders").opt
     await listSprints(config, opts);
   })
 );
-program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--json", "Force JSON output even in terminal").action(
+program.command("subtasks <taskId>").description("List subtasks of a task or initiative").option("--include-closed", "Include closed/done subtasks").option("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
-    const tasks = await fetchSubtasks(config, taskId);
+    const tasks = await fetchSubtasks(config, taskId, { includeClosed: opts.includeClosed });
     await printTasks(tasks, opts.json ?? false, config);
   })
 );
@@ -2181,6 +2256,17 @@ program.command("assign <taskId>").description("Assign or unassign users from a
     }
   })
 );
+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, ...opts, message }, null, 2));
+    } else {
+      console.log(message);
+    }
+  })
+);
 var configCmd = program.command("config").description("Manage CLI configuration");
 configCmd.command("get <key>").description("Print a config value").action(
   wrapAction(async (key) => {

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clickup
-description: 'Use when managing ClickUp tasks, initiatives, sprints, or comments via the `cu` CLI tool. Triggers: task queries, status updates, sprint tracking, creating subtasks, posting comments, standup summaries, searching tasks, checking overdue items.'
+description: 'Use when managing ClickUp tasks, initiatives, sprints, or comments via the `cu` CLI tool. Triggers: task queries, status updates, sprint tracking, creating subtasks, posting comments, standup summaries, searching tasks, checking overdue items, assigning tasks, listing spaces and lists, opening tasks in browser, checking auth or config.'
 ---
 
 # ClickUp CLI (`cu`)
@@ -43,7 +43,7 @@ All commands support `--help` for full flag details.
 | `cu sprints [--space nameOrId] [--json]`                                   | List all sprints (marks active with \*)            |
 | `cu search <query> [--status s] [--json]`                                  | Search my tasks by name (multi-word, fuzzy status) |
 | `cu task <id> [--json]`                                                    | Single task details                                |
-| `cu subtasks <id> [--json]`                                                | Subtasks of a task or initiative                   |
+| `cu subtasks <id> [--include-closed] [--json]`                             | Subtasks of a task or initiative                   |
 | `cu comments <id> [--json]`                                                | Comments on a task                                 |
 | `cu activity <id> [--json]`                                                | Task details + comment history combined            |
 | `cu inbox [--days n] [--json]`                                             | Tasks updated in last n days (default 30)          |
@@ -56,14 +56,15 @@ All commands support `--help` for full flag details.
 
 ### Write
 
-| Command                                                                                                                               | What it does                                 |
-| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `cu update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d] [--assignee id] [--json]`                               | Update task fields                           |
-| `cu create -n name [-l listId] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--assignee id] [--tags t] [--json]` | Create task (list auto-detected from parent) |
-| `cu comment <id> -m text`                                                                                                             | Post comment on task                         |
-| `cu assign <id> [--to userId\|me] [--remove userId\|me] [--json]`                                                                     | Assign/unassign users                        |
-| `cu config get <key>` / `cu config set <key> <value>` / `cu config path`                                                              | Manage CLI config                            |
-| `cu completion <shell>`                                                                                                               | Shell completions (bash/zsh/fish)            |
+| Command                                                                                                                                                                        | What it does                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| `cu update <id> [-n name] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id] [--json]`                                                    | Update task fields                           |
+| `cu create -n name [-l listId] [-p parentId] [-d desc] [-s status] [--priority p] [--due-date d] [--time-estimate t] [--assignee id] [--tags t] [--custom-item-id n] [--json]` | Create task (list auto-detected from parent) |
+| `cu comment <id> -m text`                                                                                                                                                      | Post comment on task                         |
+| `cu assign <id> [--to userId\|me] [--remove userId\|me] [--json]`                                                                                                              | Assign/unassign users                        |
+| `cu depend <id> [--on taskId] [--blocks taskId] [--remove] [--json]`                                                                                                           | Add/remove task dependencies                 |
+| `cu config get <key>` / `cu config set <key> <value>` / `cu config path`                                                                                                       | Manage CLI config                            |
+| `cu completion <shell>`                                                                                                                                                        | Shell completions (bash/zsh/fish)            |
 
 ## Quick Reference
 
@@ -77,8 +78,12 @@ All commands support `--help` for full flag details.
 | `--due-date`        | `YYYY-MM-DD` format                                                               |
 | `--assignee`        | Numeric user ID (find via `cu task <id> --json`)                                  |
 | `--tags`            | Comma-separated (e.g. `--tags "bug,frontend"`)                                    |
+| `--time-estimate`   | Duration format: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds                  |
+| `--custom-item-id`  | Custom task type ID (e.g. `1` for initiative)                                     |
+| `--on` / `--blocks` | Task dependency direction (used with `cu depend`)                                 |
 | `--space`           | Partial name match or exact ID                                                    |
 | `--name`            | Partial match, case-insensitive                                                   |
+| `--include-closed`  | Include closed/done tasks (on `subtasks` and `assigned`)                          |
 | `cu assign --to me` | Shorthand for your own user ID                                                    |
 | `cu search`         | Matches all query words against task name, case-insensitive                       |
 | `cu sprint`         | Auto-detects active sprint via view API and date range parsing                    |
@@ -96,7 +101,8 @@ All commands support `--help` for full flag details.
 
 ```bash
 cu task abc123def                   # markdown summary
-cu subtasks abc123def               # child tasks
+cu subtasks abc123def               # child tasks (open only)
+cu subtasks abc123def --include-closed  # all child tasks
 cu comments abc123def               # discussion
 cu activity abc123def               # task + comments combined
 ```
@@ -119,17 +125,22 @@ cu inbox --days 7                   # recently updated
 ```bash
 cu update abc123def -s "done"
 cu update abc123def --priority high --due-date 2025-03-15
+cu update abc123def --time-estimate 2h
 cu create -n "Fix the thing" -p abc123def
 cu create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
+cu create -n "Q3 Roadmap" -l <listId> --custom-item-id 1  # create initiative
 cu comment abc123def -m "Completed in PR #42"
 cu assign abc123def --to me
+cu depend task3 --on task2            # task3 waits for task2
+cu depend task1 --blocks task2        # task1 blocks task2
 ```
 
 ### Discover workspace structure
 
 ```bash
 cu spaces                           # all spaces
-cu lists <spaceId>                  # lists in a space (needed for --list flag)
+cu spaces --name "Engineering"      # find space ID by name
+cu lists <spaceId>                  # lists in a space (needs ID from cu spaces)
 cu sprints                          # all sprints across folders
 cu auth                             # verify token works
 ```