@krodak/clickup-cli 0.6.1 → 0.8.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "clickup-cli",
+  "description": "Claude Code skills for the cu (ClickUp CLI) tool - manage tasks, sprints, initiatives, and comments",
+  "version": "0.6.1",
+  "author": {
+    "name": "Krzysztof Rodak"
+  },
+  "homepage": "https://github.com/krodak/clickup-cli",
+  "repository": "https://github.com/krodak/clickup-cli",
+  "license": "MIT"
+}

package/README.md

@@ -1,127 +1,102 @@
 # cu - ClickUp CLI
 
-A ClickUp CLI for AI agents and humans. Two operating modes: interactive tables with a task picker in terminals, raw JSON when piped.
+A ClickUp CLI built for AI agents that also works well for humans. Outputs JSON when piped, interactive tables when run in a terminal.
 
-## Requirements
-
-- Node 22+
-- A ClickUp personal API token (`pk_...` from https://app.clickup.com/settings/apps)
-
-## Install
+## Quick start
 
 ```bash
-npm install -g @krodak/clickup-cli
+npm install -g @krodak/clickup-cli   # or: brew tap krodak/tap && brew install clickup-cli
+cu init                               # walks you through API token + workspace setup
 ```
 
-## Getting started
-
-```bash
-cu init
-```
+You need Node 22+ and a ClickUp personal API token (`pk_...` from https://app.clickup.com/settings/apps).
 
-Prompts for your API token, verifies it, auto-detects your workspace, and writes `~/.config/cu/config.json`.
+## Using with AI agents
 
-## Operating Modes
+This is the primary use case. Install the tool, install the skill file, and your agent knows how to work with ClickUp.
 
-### Interactive TTY mode (for humans)
+### 1. Install the skill
 
-When run in a terminal (TTY detected), list commands (`cu tasks`, `cu initiatives`, `cu sprint`, `cu inbox`, `cu subtasks`, `cu overdue`) display:
+The repo includes a skill file at `skills/clickup-cli/SKILL.md` that teaches agents all available commands and when to use them. It's also packaged as a Claude Code plugin.
 
-1. A formatted table with auto-sized columns showing task ID, name, status, type, list, and URL.
-2. An interactive checkbox picker (powered by @inquirer/prompts) - navigate with arrow keys, toggle selection with space, confirm with enter.
-3. For selected tasks, a rich detail view showing: name (bold/underlined), ID, status, type, list, assignees, priority, dates, estimate, tracked time, tags, parent, URL, and a description preview (first 3 lines).
-4. A prompt to open the selected tasks in the browser.
+**Claude Code (plugin - recommended):**
 
-Pass `--json` to any list command to bypass interactive mode and get raw JSON output in a terminal.
+The repo ships as a Claude Code plugin. Point Claude Code at the repo or installed npm package:
 
-### JSON piped mode (for AI agents and scripts)
-
-When output is piped (no TTY), all list commands output JSON arrays to stdout. No interactive UI is shown.
-
-- `cu task <id> --json` returns the full JSON response for a single task.
-- All list commands output JSON arrays.
-- Errors go to stderr with exit code 1.
-- Write commands (`update`, `create`, `comment`, `assign`) always output JSON regardless of mode.
-- Set `NO_COLOR` to disable color output.
-
-## For AI agents
+```bash
+claude --plugin-dir ./node_modules/@krodak/clickup-cli
+```
 
-Always use the `--json` flag or pipe output to ensure you get JSON. Parse with `jq` or programmatically.
+Or copy the skill manually:
 
 ```bash
-# List my in-progress tasks
-cu tasks --status "in progress" --json | jq '.[] | {id, name}'
-
-# Get full task details as JSON
-cu task abc123 --json | jq '{id, name, status}'
+mkdir -p ~/.claude/skills/clickup
+cp skills/clickup-cli/SKILL.md ~/.claude/skills/clickup/SKILL.md
+```
 
-# Check current sprint
-cu sprint --json | jq '.[] | select(.status != "done")'
+Then reference it in your `CLAUDE.md` or project instructions.
 
-# Create subtask under initiative
-INITIATIVE_ID=$(cu initiatives --json | jq -r '.[0].id')
-cu create -n "New subtask" -p "$INITIATIVE_ID"
+**OpenCode:**
 
-# Update status when done
-cu update abc123 -s "done"
+```bash
+mkdir -p ~/.config/opencode/skills/clickup
+cp skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
 ```
 
-Write commands (`update`, `create`, `comment`) always return JSON, no `--json` flag needed.
+**Codex / other agents:**
 
-## AI Agents Skill
+Copy the contents of `skills/clickup-cli/SKILL.md` into your system prompt or project instructions. It's a standalone markdown document.
 
-A skill file is included at `skill/SKILL.md` that teaches AI agents how to use `cu`. Install it for your agent of choice:
+### 2. Talk to your agent
 
-### OpenCode
+Once the skill is installed, you just tell the agent what you need in plain language. It figures out which `cu` commands to run.
 
-```bash
-mkdir -p ~/.config/opencode/skills/clickup
-cp skill/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
 ```
+"Read the description of task <id>, do the work, then mark it in review and leave a comment with the commit hash."
 
-### Claude Code
+"Check all subtasks under initiative <id> and improve their descriptions based on what's in the codebase."
 
-```bash
-mkdir -p ~/.claude/skills/clickup
-cp skill/SKILL.md ~/.claude/skills/clickup/SKILL.md
-```
+"What's my standup summary? What did I finish yesterday, what's in progress, what's overdue?"
 
-Then reference it in your `CLAUDE.md` or project instructions.
+"Do exploratory work for task <id>, update the description with your findings, and flag blockers in a comment."
 
-### Codex
+"Create a subtask under <id> for the edge case we just found."
 
-Copy the contents of `skill/SKILL.md` into your Codex system prompt or project instructions file.
+"Check my sprint and tell me what's overdue."
+```
 
-### Other agents
+You don't need to learn the CLI commands yourself. The agent handles it.
 
-The skill file is a standalone markdown document. Feed it to any agent that supports custom instructions or tool documentation.
+### Why a CLI and not MCP?
 
-## Config
+A CLI + skill file has fewer moving parts. No extra server process, no protocol layer. The agent already knows how to run shell commands - the skill file just teaches it which ones exist. This matches what Peter Steinberger and the OpenClaw project have found: for tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.
 
-### Config file
+### Scoped output
 
-`~/.config/cu/config.json` (or `$XDG_CONFIG_HOME/cu/config.json`):
+Most commands return only your tasks by default. `cu tasks`, `cu sprint`, `cu overdue`, `cu summary` all scope to what's assigned to you. `cu spaces --my` filters to spaces where you have tasks. This keeps output small and relevant - important when it's going into an agent's context window.
 
-```json
-{
-  "apiToken": "pk_...",
-  "teamId": "12345678"
-}
-```
+## Using from the terminal
 
-### Environment variables
+When you run `cu` in a terminal directly, you get an interactive mode with tables and a task picker.
 
-Environment variables override config file values:
+```bash
+cu tasks                          # interactive table with checkbox picker
+cu sprint                         # your sprint tasks, auto-detected
+cu summary                        # standup helper: completed / in progress / overdue
+cu overdue                        # tasks past their due date
+cu open "login bug"               # fuzzy search, opens in browser
+cu update abc123 -s "done"        # update status
+cu assign abc123 --to me          # assign yourself
+```
 
-| Variable       | Description                        |
-| -------------- | ---------------------------------- |
-| `CU_API_TOKEN` | ClickUp personal API token (`pk_`) |
-| `CU_TEAM_ID`   | Workspace (team) ID                |
+Pass `--json` to any command to get raw JSON output instead of the interactive UI.
 
-When both are set, the config file is not required. Useful for CI/CD and containerized agents.
+When output is piped (no TTY), all commands automatically output JSON. All commands support `--json` to force JSON output even in a terminal.
 
 ## Commands
 
+24 commands total. All support `--help` for full flag details.
+
 ### `cu init`
 
 First-time setup. Prompts for your API token, verifies it, auto-detects your workspace, and writes `~/.config/cu/config.json`.
@@ -140,7 +115,7 @@ cu tasks --status "in progress"
 cu tasks --name "login"
 cu tasks --list <listId>
 cu tasks --space <spaceId>
-cu tasks --json          # force JSON output
+cu tasks --json
 ```
 
 ### `cu initiatives`
@@ -166,6 +141,15 @@ cu sprint --status "in progress"
 cu sprint --json
 ```
 
+### `cu sprints`
+
+List all sprints across sprint folders. Marks the currently active sprint.
+
+```bash
+cu sprints
+cu sprints --json
+```
+
 ### `cu assigned`
 
 All tasks assigned to me, grouped by pipeline stage (code review, in progress, to do, etc.).
@@ -188,11 +172,11 @@ cu inbox --json
 
 ### `cu task <id>`
 
-Get task details. Pretty summary in terminal, JSON when piped.
+Get task details including custom fields. Pretty summary in terminal, JSON when piped.
 
 ```bash
 cu task abc123
-cu task abc123 --json    # full JSON response
+cu task abc123 --json
 ```
 
 ### `cu subtasks <id>`
@@ -216,16 +200,18 @@ 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 -s "in progress" --json
 ```
 
-| Flag                       | Description                                          |
-| -------------------------- | ---------------------------------------------------- |
-| `-n, --name <text>`        | New task name                                        |
-| `-d, --description <text>` | New description (markdown supported)                 |
-| `-s, --status <status>`    | New status (e.g. `"in progress"`, `"done"`)          |
-| `--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                      |
+| 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                                          |
 
 ### `cu create`
 
@@ -237,6 +223,7 @@ 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 "Fix bug" -l <listId> --json
 ```
 
 | Flag                       | Required         | Description                                          |
@@ -250,6 +237,7 @@ cu create -n "Task" -l <listId> --assignee 12345 --tags "bug,frontend"
 | `--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                   |
 
 ### `cu comment <id>`
 
@@ -268,13 +256,22 @@ cu comments abc123
 cu comments abc123 --json
 ```
 
+### `cu activity <id>`
+
+View task details and comment history together. Combines `cu task` and `cu comments` into a single view.
+
+```bash
+cu activity abc123
+cu activity abc123 --json
+```
+
 ### `cu lists <spaceId>`
 
 List all lists in a space, including lists inside folders. Useful for discovering list IDs needed by `--list` filter and `cu create -l`.
 
 ```bash
 cu lists <spaceId>
-cu lists <spaceId> --name "sprint"    # filter by partial name
+cu lists <spaceId> --name "sprint"
 cu lists <spaceId> --json
 ```
 
@@ -289,8 +286,8 @@ List spaces in your workspace. Useful for getting space IDs for the `--space` fi
 
 ```bash
 cu spaces
-cu spaces --name "eng"   # filter by partial name match (case-insensitive)
-cu spaces --my            # show only spaces you are a member of
+cu spaces --name "eng"
+cu spaces --my
 cu spaces --json
 ```
 
@@ -305,20 +302,31 @@ cu spaces --json
 Open a task in the browser. Accepts a task ID or partial name.
 
 ```bash
-cu open abc123                # open by task ID
-cu open "login bug"           # search by name, open first match
-cu open abc123 --json         # output task JSON instead of opening
+cu open abc123
+cu open "login bug"
+cu open abc123 --json
 ```
 
 If the query matches multiple tasks by name, all matches are listed and the first is opened.
 
+### `cu search <query>`
+
+Search my tasks by name. Supports multi-word queries with case-insensitive matching. Status filter supports fuzzy matching.
+
+```bash
+cu search "login bug"
+cu search auth
+cu search "payment flow" --json
+cu search auth --status "prog"     # fuzzy matches "in progress"
+```
+
 ### `cu summary`
 
 Daily standup helper. Shows tasks grouped into: recently completed, in progress, and overdue.
 
 ```bash
 cu summary
-cu summary --hours 48         # extend completed window to 48 hours
+cu summary --hours 48
 cu summary --json
 ```
 
@@ -329,25 +337,23 @@ cu summary --json
 
 ### `cu overdue`
 
-List tasks that are past their due date (excludes done/closed tasks).
+List tasks that are past their due date (excludes done/closed tasks). Sorted most overdue first.
 
 ```bash
 cu overdue
 cu overdue --json
 ```
 
-Tasks are sorted by due date ascending (most overdue first).
-
 ### `cu assign <id>`
 
 Assign or unassign users from a task. Supports `me` as shorthand for your user ID.
 
 ```bash
-cu assign abc123 --to 12345          # add assignee
-cu assign abc123 --to me             # assign yourself
-cu assign abc123 --remove 12345      # remove assignee
-cu assign abc123 --to me --remove 67890  # both at once
-cu assign abc123 --to me --json      # output updated task JSON
+cu assign abc123 --to 12345
+cu assign abc123 --to me
+cu assign abc123 --remove 12345
+cu assign abc123 --to me --remove 67890
+cu assign abc123 --to me --json
 ```
 
 | Flag                | Description                       |
@@ -356,14 +362,23 @@ cu assign abc123 --to me --json      # output updated task JSON
 | `--remove <userId>` | Remove assignee (user ID or `me`) |
 | `--json`            | Force JSON output                 |
 
+### `cu auth`
+
+Check authentication status. Validates your API token and shows your user info.
+
+```bash
+cu auth
+cu auth --json
+```
+
 ### `cu config`
 
 Manage CLI configuration.
 
 ```bash
-cu config get apiToken        # print a config value
-cu config set teamId 12345    # set a config value
-cu config path                # print config file path
+cu config get apiToken
+cu config set teamId 12345
+cu config path
 ```
 
 Valid keys: `apiToken`, `teamId`. Setting `apiToken` validates the `pk_` prefix.
@@ -373,17 +388,34 @@ Valid keys: `apiToken`, `teamId`. Setting `apiToken` validates the `pk_` prefix.
 Output shell completion script. Supports `bash`, `zsh`, and `fish`.
 
 ```bash
-# Bash - add to ~/.bashrc
-eval "$(cu completion bash)"
+eval "$(cu completion bash)"                                    # Bash
+eval "$(cu completion zsh)"                                     # Zsh
+cu completion fish > ~/.config/fish/completions/cu.fish          # Fish
+```
+
+## Config
 
-# Zsh - add to ~/.zshrc
-eval "$(cu completion zsh)"
+### Config file
+
+`~/.config/cu/config.json` (or `$XDG_CONFIG_HOME/cu/config.json`):
 
-# Fish - save to completions directory
-cu completion fish > ~/.config/fish/completions/cu.fish
+```json
+{
+  "apiToken": "pk_...",
+  "teamId": "12345678"
+}
 ```
 
-Completions cover all commands, flags, and known values (priority levels, status names, config keys).
+### Environment variables
+
+Environment variables override config file values:
+
+| Variable       | Description                        |
+| -------------- | ---------------------------------- |
+| `CU_API_TOKEN` | ClickUp personal API token (`pk_`) |
+| `CU_TEAM_ID`   | Workspace (team) ID                |
+
+When both are set, the config file is not required. Useful for CI/CD and containerized agents.
 
 ## Development
 

package/dist/index.js

@@ -61,9 +61,13 @@ function getConfigPath() {
 function writeConfig(config) {
   const dir = configDir();
   if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(dir, { recursive: true, mode: 448 });
   }
-  fs.writeFileSync(join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
+  const filePath = join(dir, "config.json");
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n", {
+    encoding: "utf-8",
+    mode: 384
+  });
 }
 
 // src/api.ts
@@ -187,6 +191,9 @@ var ClickUpClient = class {
     const data = await this.request("/team");
     return data.teams ?? [];
   }
+  async getSpaceWithStatuses(spaceId) {
+    return this.request(`/space/${spaceId}`);
+  }
   async getSpaces(teamId) {
     const data = await this.request(`/team/${teamId}/space?archived=false`);
     return data.spaces ?? [];
@@ -295,6 +302,40 @@ function descriptionPreview(text, maxLines = 3) {
   ${chalk2.dim(`... (${lines.length - maxLines} more lines)`)}`;
   return result;
 }
+function stringifyFieldValue(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+function formatCustomFieldValue(field) {
+  if (field.value === null || field.value === void 0) return null;
+  const options = field.type_config?.options;
+  switch (field.type) {
+    case "drop_down": {
+      if (!options) return stringifyFieldValue(field.value);
+      const match = options.find((o) => o.id === Number(field.value));
+      return match?.name ?? stringifyFieldValue(field.value);
+    }
+    case "labels": {
+      if (!Array.isArray(field.value) || !options) return stringifyFieldValue(field.value);
+      const names = field.value.map((id) => options.find((o) => o.id === id)?.name).filter((n) => n !== void 0);
+      return names.length > 0 ? names.join(", ") : null;
+    }
+    case "date": {
+      const ts = Number(field.value);
+      if (!Number.isFinite(ts)) return stringifyFieldValue(field.value);
+      return new Date(ts).toLocaleDateString("en-US", {
+        month: "short",
+        day: "numeric",
+        year: "numeric"
+      });
+    }
+    case "checkbox":
+      return field.value === true || field.value === "true" ? "Yes" : "No";
+    default:
+      return stringifyFieldValue(field.value);
+  }
+}
 function formatTaskDetail(task) {
   const lines = [];
   const isInitiative2 = (task.custom_item_id ?? 0) !== 0;
@@ -324,6 +365,16 @@ function formatTaskDetail(task) {
     if (!value) continue;
     lines.push(`  ${chalk2.bold(label.padEnd(maxLabel + 1))} ${value}`);
   }
+  if (task.custom_fields?.length) {
+    const formatted = task.custom_fields.map((f) => [f.name, formatCustomFieldValue(f)]).filter((pair) => pair[1] !== null);
+    if (formatted.length > 0) {
+      lines.push("");
+      lines.push(chalk2.bold("Custom Fields"));
+      for (const [name, value] of formatted) {
+        lines.push(`  ${chalk2.bold(name)}  ${value}`);
+      }
+    }
+  }
   if (task.text_content?.trim()) {
     lines.push("");
     lines.push(descriptionPreview(task.text_content));
@@ -455,6 +506,19 @@ async function printTasks(tasks, forceJson, config) {
   await showDetailsAndOpen(selected, fetchTask);
 }
 
+// src/status.ts
+function matchStatus(input, statuses) {
+  if (!input) return null;
+  const lower = input.toLowerCase();
+  const exact = statuses.find((s) => s.toLowerCase() === lower);
+  if (exact) return exact;
+  const startsWith = statuses.find((s) => s.toLowerCase().startsWith(lower));
+  if (startsWith) return startsWith;
+  const contains = statuses.find((s) => s.toLowerCase().includes(lower));
+  if (contains) return contains;
+  return null;
+}
+
 // src/commands/update.ts
 var PRIORITY_MAP = {
   urgent: 1,
@@ -500,12 +564,30 @@ function buildUpdatePayload(opts) {
 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;
 }
+async function resolveStatus(client, taskId, statusInput) {
+  const task = await client.getTask(taskId);
+  if (!task.space) return statusInput;
+  const space = await client.getSpaceWithStatuses(task.space.id);
+  const available = space.statuses.map((s) => s.status);
+  const matched = matchStatus(statusInput, available);
+  if (!matched) {
+    throw new Error(`No matching status for "${statusInput}". Available: ${available.join(", ")}`);
+  }
+  if (matched.toLowerCase() !== statusInput.toLowerCase()) {
+    process.stderr.write(`Status matched: "${statusInput}" -> "${matched}"
+`);
+  }
+  return matched;
+}
 async function updateTask(config, taskId, options) {
   if (!hasUpdateFields(options))
     throw new Error(
       "Provide at least one of: --name, --description, --status, --priority, --due-date, --assignee"
     );
   const client = new ClickUpClient(config);
+  if (options.status !== void 0) {
+    options.status = await resolveStatus(client, taskId, options.status);
+  }
   const task = await client.updateTask(taskId, options);
   return { id: task.id, name: task.name };
 }
@@ -683,6 +765,83 @@ async function runSprintCommand(config, opts) {
   await printTasks(summaries, opts.json ?? false, config);
 }
 
+// src/commands/sprints.ts
+var SPRINT_COLUMNS = [
+  { key: "id", label: "ID" },
+  { key: "sprint", label: "SPRINT", maxWidth: 60 },
+  { key: "dates", label: "DATES" }
+];
+function formatDate(d) {
+  return `${d.getMonth() + 1}/${d.getDate()}`;
+}
+function buildSprintInfos(lists, folderName, today) {
+  return lists.map((list) => {
+    const dates = parseSprintDates(list.name);
+    const active = dates !== null && today >= dates.start && today <= dates.end;
+    return {
+      id: list.id,
+      name: list.name,
+      folder: folderName,
+      start: dates ? dates.start.toISOString() : null,
+      end: dates ? dates.end.toISOString() : null,
+      active
+    };
+  });
+}
+async function listSprints(config, opts = {}) {
+  const client = new ClickUpClient(config);
+  const [myTasks, allSpaces] = await Promise.all([
+    client.getMyTasks(config.teamId),
+    client.getSpaces(config.teamId)
+  ]);
+  let spaces;
+  if (opts.space) {
+    spaces = allSpaces.filter(
+      (s) => s.name.toLowerCase().includes(opts.space.toLowerCase()) || s.id === opts.space
+    );
+    if (spaces.length === 0) {
+      throw new Error(
+        `No space matching "${opts.space}" found. Use \`cu spaces\` to list available spaces.`
+      );
+    }
+  } else {
+    const mySpaceIds = new Set(
+      myTasks.map((t) => t.space?.id).filter((id) => Boolean(id))
+    );
+    spaces = findRelatedSpaces(mySpaceIds, allSpaces);
+  }
+  const foldersBySpace = await Promise.all(spaces.map((space) => client.getFolders(space.id)));
+  const sprintFolders = foldersBySpace.flat().filter((f) => f.name.toLowerCase().includes("sprint"));
+  const today = /* @__PURE__ */ new Date();
+  const allSprints = [];
+  const listsByFolder = await Promise.all(
+    sprintFolders.map((folder) => client.getFolderLists(folder.id))
+  );
+  for (let i = 0; i < sprintFolders.length; i++) {
+    const folder = sprintFolders[i];
+    const lists = listsByFolder[i];
+    allSprints.push(...buildSprintInfos(lists, folder.name, today));
+  }
+  if (opts.json || !isTTY()) {
+    console.log(JSON.stringify(allSprints, null, 2));
+    return;
+  }
+  if (allSprints.length === 0) {
+    console.log("No sprints found.");
+    return;
+  }
+  const rows = allSprints.map((s) => {
+    const dates = parseSprintDates(s.name);
+    const dateStr = dates ? `${formatDate(dates.start)} - ${formatDate(dates.end)}` : "";
+    return {
+      id: s.id,
+      sprint: s.active ? `* ${s.name}` : s.name,
+      dates: dateStr
+    };
+  });
+  console.log(formatTable(rows, SPRINT_COLUMNS));
+}
+
 // src/commands/subtasks.ts
 async function fetchSubtasks(config, taskId) {
   const client = new ClickUpClient(config);
@@ -700,7 +859,7 @@ async function postComment(config, taskId, text) {
 
 // src/commands/comments.ts
 import chalk3 from "chalk";
-function formatDate(timestamp) {
+function formatDate2(timestamp) {
   return new Date(Number(timestamp)).toLocaleString("en-US", {
     month: "short",
     day: "numeric",
@@ -732,7 +891,7 @@ function printComments(comments, forceJson) {
   for (let i = 0; i < comments.length; i++) {
     const c = comments[i];
     if (i > 0) console.log(separator);
-    console.log(`${chalk3.bold(c.user)}  ${chalk3.dim(formatDate(c.date))}`);
+    console.log(`${chalk3.bold(c.user)}  ${chalk3.dim(formatDate2(c.date))}`);
     console.log(c.text);
     if (i < comments.length - 1) console.log("");
   }
@@ -1148,6 +1307,55 @@ async function assignTask(config, taskId, opts) {
   });
 }
 
+// src/commands/activity.ts
+import chalk4 from "chalk";
+function formatDate3(timestamp) {
+  return new Date(Number(timestamp)).toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    hour: "numeric",
+    minute: "2-digit"
+  });
+}
+async function fetchActivity(config, taskId) {
+  const client = new ClickUpClient(config);
+  const [task, rawComments] = await Promise.all([
+    client.getTask(taskId),
+    client.getTaskComments(taskId)
+  ]);
+  const comments = rawComments.map((c) => ({
+    id: c.id,
+    user: c.user.username,
+    date: c.date,
+    text: c.comment_text
+  }));
+  return { task, comments };
+}
+function printActivity(result, forceJson) {
+  if (forceJson || !isTTY()) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatTaskDetail(result.task));
+  console.log("");
+  console.log(chalk4.bold("Comments"));
+  console.log(chalk4.dim("-".repeat(60)));
+  if (result.comments.length === 0) {
+    console.log("No comments.");
+    return;
+  }
+  for (let i = 0; i < result.comments.length; i++) {
+    const c = result.comments[i];
+    if (i > 0) {
+      console.log("");
+      console.log(chalk4.dim("-".repeat(60)));
+    }
+    console.log(`${chalk4.bold(c.user)}  ${chalk4.dim(formatDate3(c.date))}`);
+    console.log(c.text);
+  }
+}
+
 // src/commands/completion.ts
 function bashCompletion() {
   return `_cu_completions() {
@@ -1552,6 +1760,47 @@ function generateCompletion(shell) {
   }
 }
 
+// src/commands/auth.ts
+async function checkAuth(config) {
+  const client = new ClickUpClient(config);
+  try {
+    const user = await client.getMe();
+    return { authenticated: true, user };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { authenticated: false, error: message };
+  }
+}
+
+// src/commands/search.ts
+async function searchTasks(config, query, opts = {}) {
+  const trimmed = query.trim();
+  if (!trimmed) {
+    throw new Error("Search query cannot be empty");
+  }
+  const client = new ClickUpClient(config);
+  const allTasks = await client.getMyTasks(config.teamId);
+  const words = trimmed.toLowerCase().split(/\s+/);
+  let matched = allTasks.filter((task) => {
+    const name = task.name.toLowerCase();
+    return words.every((word) => name.includes(word));
+  });
+  if (opts.status) {
+    const availableStatuses = [...new Set(allTasks.map((t) => t.status.status))];
+    const resolved = matchStatus(opts.status, availableStatuses);
+    if (resolved) {
+      if (resolved.toLowerCase() !== opts.status.toLowerCase()) {
+        process.stderr.write(`Status matched: "${opts.status}" -> "${resolved}"
+`);
+      }
+      matched = matched.filter((t) => t.status.status.toLowerCase() === resolved.toLowerCase());
+    } else {
+      matched = matched.filter((t) => t.status.status.toLowerCase() === opts.status.toLowerCase());
+    }
+  }
+  return matched.map(summarize);
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1570,6 +1819,20 @@ program.command("init").description("Set up cu for the first time").action(
     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 (opts.json || !isTTY()) {
+      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 {
+      console.error(`Authentication failed: ${result.error ?? "unknown error"}`);
+      process.exit(1);
+    }
+  })
+);
 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("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
@@ -1603,40 +1866,30 @@ program.command("task <taskId>").description("Get task details").option("--json"
     if (opts.json || !isTTY()) {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      const lines = [
-        `ID:          ${result.id}`,
-        `Name:        ${result.name}`,
-        `Status:      ${result.status?.status ?? "unknown"}`,
-        `Type:        ${(result.custom_item_id ?? 0) !== 0 ? "initiative" : "task"}`,
-        `List:        ${result.list?.name ?? "unknown"}`,
-        `URL:         ${result.url}`,
-        ...result.parent ? [`Parent:      ${result.parent}`] : [],
-        ...result.description ? ["", result.description] : []
-      ];
-      console.log(lines.join("\n"));
+      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("--assignee <userId>", "Add assignee by user ID").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("--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);
     const result = await updateTask(config, taskId, payload);
-    if (isTTY()) {
-      console.log(`Updated task ${result.id}: "${result.name}"`);
-    } else {
+    if (opts.json || !isTTY()) {
       console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Updated task ${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").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").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("--json", "Force JSON output even in terminal").action(
   wrapAction(async (opts) => {
     const config = loadConfig();
     const result = await createTask(config, opts);
-    if (isTTY()) {
-      console.log(`Created task ${result.id}: "${result.name}" - ${result.url}`);
-    } else {
+    if (opts.json || !isTTY()) {
       console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Created task ${result.id}: "${result.name}" - ${result.url}`);
     }
   })
 );
@@ -1646,6 +1899,12 @@ program.command("sprint").description("List my tasks in the current active sprin
     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("--json", "Force JSON output even in terminal").action(
   wrapAction(async (taskId, opts) => {
     const config = loadConfig();
@@ -1671,6 +1930,13 @@ program.command("comments <taskId>").description("List comments on a task").opti
     printComments(comments, opts.json ?? false);
   })
 );
+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();
@@ -1708,6 +1974,13 @@ program.command("open <query>").description("Open a task in the browser by ID or
     await openTask(config, query, opts);
   })
 );
+program.command("search <query>").description("Search my tasks by name").option("--status <status>", "Filter by status").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 });
+    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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krodak/clickup-cli",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "ClickUp CLI for AI agents and humans",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,8 @@
   },
   "files": [
     "dist",
+    ".claude-plugin",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/clickup-cli/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: clickup
+description: 'Use when managing ClickUp tasks, initiatives, sprints, or comments via the `cu` CLI tool. Covers task queries, status updates, sprint tracking, and project management workflows.'
+---
+
+# ClickUp CLI (`cu`)
+
+Reference for AI agents using the `cu` command-line tool to interact with ClickUp. Covers task management, sprint tracking, initiatives, and comments.
+
+Keywords: ClickUp, task management, sprint, initiative, project management, agile, backlog, subtasks
+
+## Setup
+
+Config at `~/.config/cu/config.json` (or `$XDG_CONFIG_HOME/cu/config.json`) with `apiToken` and `teamId`. Run `cu init` to set up.
+
+Alternatively, set `CU_API_TOKEN` and `CU_TEAM_ID` environment variables (overrides config file, no file needed when both are set).
+
+## Commands
+
+All commands support `--help` for full flag details.
+
+### Read
+
+| Command                                                                    | What it returns                                    |
+| -------------------------------------------------------------------------- | -------------------------------------------------- |
+| `cu tasks [--status s] [--name q] [--list id] [--space id] [--json]`       | My tasks (workspace-wide)                          |
+| `cu initiatives [--status s] [--name q] [--list id] [--space id] [--json]` | My initiatives                                     |
+| `cu assigned [--include-closed] [--json]`                                  | All my tasks grouped by status                     |
+| `cu sprint [--status s] [--space nameOrId] [--json]`                       | Tasks in active sprint (auto-detected)             |
+| `cu inbox [--days n] [--json]`                                             | Tasks updated in last n days (default 30)          |
+| `cu task <id> [--json]`                                                    | Single task details                                |
+| `cu subtasks <id> [--json]`                                                | Subtasks of a task or initiative                   |
+| `cu comments <id> [--json]`                                                | List comments on a task                            |
+| `cu spaces [--name partial] [--my] [--json]`                               | List/filter workspace spaces                       |
+| `cu lists <spaceId> [--name partial] [--json]`                             | List all lists in a space (including folder lists) |
+| `cu open <query> [--json]`                                                 | Open task in browser by ID or name                 |
+| `cu summary [--hours n] [--json]`                                          | Standup helper: completed, in-progress, overdue    |
+| `cu overdue [--json]`                                                      | Tasks past their due date                          |
+| `cu search <query> [--status s] [--json]`                                  | Search my tasks by name (multi-word, fuzzy status) |
+| `cu activity <id> [--json]`                                                | Task details + comment history combined            |
+| `cu auth [--json]`                                                         | Check authentication status                        |
+| `cu sprints [--space nameOrId] [--json]`                                   | List all sprints (marks active with \*)            |
+
+### 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 from a task            |
+| `cu config get <key>` / `cu config set <key> <value>` / `cu config path`                                                              | Manage CLI config                            |
+| `cu completion <shell>`                                                                                                               | Output shell completions (bash/zsh/fish)     |
+
+## Output modes
+
+- **TTY (terminal)**: Interactive picker UI. Use `--json` to bypass.
+- **Piped / non-TTY**: Always JSON. This is what agents get by default.
+- **Agents should always pass `--json`** to guarantee machine-readable output.
+- Set `NO_COLOR` to disable color output (tables still render, just without color).
+
+## Key facts
+
+- All task IDs are stable alphanumeric strings (e.g. `abc123def`)
+- Initiatives are detected via `custom_item_id !== 0` (not `task_type`)
+- `--list` is optional in `cu create` when `--parent` is given (list auto-detected from parent)
+- `cu sprint` auto-detects active sprint from spaces where user has tasks, using view API and date range parsing from sprint names like "Acme Sprint 4 (3/1 - 3/14)"
+- `--name` on tasks/initiatives filters by partial name match (case-insensitive)
+- `--space` on sprint/tasks accepts partial name match (e.g. `--space Acm`)
+- `--priority` accepts names (`urgent`, `high`, `normal`, `low`) or numbers (1-4)
+- `--due-date` accepts `YYYY-MM-DD` format
+- `--assignee` takes a numeric user ID (use `cu task <id> --json` to find assignee IDs)
+- `cu assign` supports `me` as a shorthand for your own user ID
+- `cu open` tries task ID lookup first, then falls back to name search
+- `cu summary` categories: completed (done/complete/closed within N hours), in progress, overdue
+- `cu overdue` excludes done/complete/closed tasks, sorted most overdue first
+- `--tags` accepts comma-separated tag names (e.g. `--tags "bug,frontend"`)
+- `cu lists <spaceId>` discovers list IDs needed for `--list` and `cu create -l`
+- Strict argument parsing - excess/unknown arguments are rejected
+- `cu update -s` supports fuzzy status matching (exact > starts-with > contains). Prints matched status to stderr when fuzzy-resolved.
+- `cu task` shows custom fields in detail view (read-only)
+- `cu search` matches all query words against task name (case-insensitive). `--status` supports fuzzy matching.
+- Errors go to stderr with exit code 1
+
+## Agent workflow example
+
+```bash
+# List my in-progress tasks
+cu tasks --status "in progress" --json
+
+# Find tasks by partial name
+cu tasks --name "login" --json
+
+# Check current sprint
+cu sprint --json | jq '.[].name'
+
+# Get full details on a task
+cu task abc123def --json
+
+# List subtasks of an initiative
+cu subtasks abc123def --json
+
+# Read comments on a task
+cu comments abc123def --json
+
+# Update task status
+cu update abc123def -s "done"
+
+# Update priority and due date
+cu update abc123def --priority high --due-date 2025-03-15
+
+# Create subtask under initiative (no --list needed)
+cu create -n "Fix the thing" -p abc123def
+
+# Create task with priority and tags
+cu create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
+
+# Post a comment
+cu comment abc123def -m "Completed in PR #42"
+
+# Discover lists in a space
+cu lists <spaceId> --json
+
+# Open a task in the browser
+cu open abc123def
+
+# Standup summary
+cu summary --json
+
+# Check overdue tasks
+cu overdue --json
+
+# Assign yourself to a task
+cu assign abc123def --to me
+
+# Check/set config
+cu config get teamId
+cu config set apiToken pk_example_token
+
+cu search "login bug" --json
+
+cu activity abc123def --json
+
+cu auth --json
+
+cu sprints --json
+
+cu update abc123def -s "prog"
+```