npm - @krodak/clickup-cli - Versions diffs - 0.14.0 → 0.16.0 - Mend

@krodak/clickup-cli 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/.claude-plugin/plugin.json +2 -2
package/README.md +213 -477
package/dist/index.js +420 -4
package/package.json +1 -1
package/skills/clickup-cli/SKILL.md +57 -34

package/README.md CHANGED Viewed

@@ -8,547 +8,279 @@
 [![CI](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml)
 ```bash
-npm install -g @krodak/clickup-cli   # or: brew tap krodak/tap && brew install clickup-cli
-cu init                               # walks you through API token + workspace setup
+npm install -g @krodak/clickup-cli && cu init
 ```
-You need a ClickUp personal API token (`pk_...` from https://app.clickup.com/settings/apps).
+## Talk to your agent
-## Using with AI agents
+Install the CLI, add the skill file to your agent, and it works with ClickUp. No API knowledge needed.
-This is the primary use case. Install the tool, install the skill file, and your agent knows how to work with ClickUp.
+> **"Read task abc123, do the work, then mark it in review and leave a comment with the commit hash."**
-### 1. Install the skill
+> **"What's my standup? What did I finish, what's in progress, what's overdue?"**
-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.
+> **"Create a subtask under the initiative for the edge case we found."**
-**Claude Code (plugin - recommended):**
+> **"Check my sprint and tell me what's behind schedule."**
-The repo ships as a Claude Code plugin. Point Claude Code at the repo or installed npm package:
+> **"Update the description with your findings and flag blockers in a comment."**
-```bash
-claude --plugin-dir ./node_modules/@krodak/clickup-cli
-```
-Or copy the skill manually:
-```bash
-mkdir -p ~/.claude/skills/clickup
-cp skills/clickup-cli/SKILL.md ~/.claude/skills/clickup/SKILL.md
-```
-Then reference it in your `CLAUDE.md` or project instructions.
-**OpenCode:**
-```bash
-mkdir -p ~/.config/opencode/skills/clickup
-cp skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
-```
-**Codex / other agents:**
-Copy the contents of `skills/clickup-cli/SKILL.md` into your system prompt or project instructions. It's a standalone markdown document.
-### 2. Talk to your agent
-Once the skill is installed, you just tell the agent what you need in plain language. It figures out which `cu` commands to run.
-```
-"Read the description of task <id>, do the work, then mark it in review and leave a comment with the commit hash."
-"Check all subtasks under initiative <id> and improve their descriptions based on what's in the codebase."
+The agent reads the skill file, picks the right `cu` commands, and handles everything. You don't need to learn the CLI - the agent does.
-"What's my standup summary? What did I finish yesterday, what's in progress, what's overdue?"
+## Install
-"Do exploratory work for task <id>, update the description with your findings, and flag blockers in a comment."
+You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)).
-"Create a subtask under <id> for the edge case we just found."
-"Check my sprint and tell me what's overdue."
-```
-You don't need to learn the CLI commands yourself. The agent handles it.
-### Why a CLI and not MCP?
-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.
-### Scoped output
-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.
-## Using from the terminal
-When you run `cu` in a terminal directly, you get an interactive mode with tables and a task picker.
-```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
-```
-Pass `--json` to any read command to force JSON output instead of the default format.
-When output is piped (no TTY), all commands output **Markdown** by default - optimized for AI agent context windows. Pass `--json` to any command for JSON output. Set `CU_OUTPUT=json` environment variable to always get JSON when piped.
-## Commands
-31 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`.
+<details open>
+<summary>&nbsp;<img src="https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white" height="18" align="center">&nbsp;<strong>npm</strong></summary>
 ```bash
+npm install -g @krodak/clickup-cli
 cu init
 ```
-### `cu tasks`
-List tasks assigned to me. By default shows all task types. Use `--type` to filter by task type.
-```bash
-cu tasks
-cu tasks --status "in progress"
-cu tasks --name "login"
-cu tasks --type task                  # regular tasks only
-cu tasks --type initiative            # initiatives only
-cu tasks --type "Bug"                 # custom task type by name
-cu tasks --list <listId>
-cu tasks --space <spaceId>
-cu tasks --include-closed
-cu tasks --json
-```
-### `cu sprint`
-List my tasks in the currently active sprint (auto-detected from sprint folder date ranges).
-```bash
-cu sprint
-cu sprint --status "in progress"
-cu sprint --include-closed
-cu sprint --json
-```
-### `cu sprints`
-List all sprints across sprint folders. Marks the currently active sprint.
-```bash
-cu sprints
-cu sprints --space "Engineering"
-cu sprints --json
-```
-### `cu assigned`
-All tasks assigned to me, grouped by pipeline stage (code review, in progress, to do, etc.).
-```bash
-cu assigned
-cu assigned --status "in progress"
-cu assigned --include-closed
-cu assigned --json
-```
-### `cu inbox`
-Tasks assigned to me that were recently updated, grouped by time period (today, yesterday, last 7 days, etc.). Default lookback is 30 days.
-```bash
-cu inbox
-cu inbox --days 7
-cu inbox --include-closed
-cu inbox --json
-```
-### `cu task <id>`
-Get task details including custom fields and checklists. Pretty summary in terminal, JSON when piped.
-```bash
-cu task abc123
-cu task abc123 --json
-```
-**Note:** When piped, `cu task` outputs a structured Markdown summary of the task. For the full raw API response with all fields (custom fields, checklists, etc.), use `--json`.
-### `cu subtasks <id>`
-List subtasks of a task.
-```bash
-cu subtasks abc123
-cu subtasks abc123 --status "in progress"
-cu subtasks abc123 --name "auth"
-cu subtasks abc123 --include-closed
-cu subtasks abc123 --json
-```
-### `cu update <id>`
-Update a task. Provide at least one option.
-```bash
-cu update abc123 -s "in progress"
-cu update abc123 -n "New task name"
-cu update abc123 -d "Updated description with **markdown**"
-cu update abc123 --priority high
-cu update abc123 --due-date 2025-03-15
-cu update abc123 --assignee me
-cu update abc123 --assignee 12345
-cu update abc123 -n "New name" -s "done" --priority urgent
-cu update abc123 --time-estimate 2h
-cu update abc123 --parent parentTaskId   # make it a subtask
-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`)                                                     |
-| `--time-estimate <duration>` | Time estimate (e.g. `"2h"`, `"30m"`, `"1h30m"`)                             |
-| `--assignee <userId>`        | Add assignee by user ID or `"me"`                                           |
-| `--parent <taskId>`          | Set parent task (makes this a subtask)                                      |
-| `--json`                     | Force JSON output even in terminal                                          |
-### `cu create`
+</details>
-Create a new task. If `--parent` is given, list is auto-detected from the parent task.
+<details>
+<summary>&nbsp;<img src="https://img.shields.io/badge/Homebrew-FBB040?logo=homebrew&logoColor=black" height="18" align="center">&nbsp;<strong>Homebrew</strong></summary>
 ```bash
-cu create -n "Fix login bug" -l <listId>
-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 me --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`)                              |
-| `--time-estimate <duration>` | no               | Time estimate (e.g. `"2h"`, `"30m"`, `"1h30m"`)      |
-| `--assignee <userId>`        | no               | Assignee by user ID or `"me"`                        |
-| `--tags <tags>`              | no               | Comma-separated tag names                            |
-| `--custom-item-id <id>`      | no               | Custom task type ID (e.g. for creating initiatives)  |
-| `--json`                     | no               | Force JSON output even in terminal                   |
-### `cu delete <id>`
-Delete a task. **DESTRUCTIVE - cannot be undone.**
-```bash
-cu delete abc123
-cu delete abc123 --confirm
-cu delete abc123 --confirm --json
-```
-In TTY mode without `--confirm`: shows the task name and prompts for confirmation (default: No). In non-interactive/piped mode, `--confirm` is required.
-| Flag        | Description                                                 |
-| ----------- | ----------------------------------------------------------- |
-| `--confirm` | Skip confirmation prompt (required in non-interactive mode) |
-| `--json`    | Force JSON output                                           |
-### `cu field <id>`
-Set or remove a custom field value. Field names are resolved case-insensitively; errors list available fields/options.
-```bash
-cu field abc123 --set "Priority Level" high
-cu field abc123 --set "Story Points" 5
-cu field abc123 --set "Approved" true
-cu field abc123 --set "Category" "Bug Fix"
-cu field abc123 --set "Due" 2025-06-01
-cu field abc123 --set "Website" "https://example.com"
-cu field abc123 --set "Contact" "user@example.com"
-cu field abc123 --remove "Priority Level"
-cu field abc123 --set "Points" 3 --remove "Old Field"
-cu field abc123 --set "Points" 3 --json
-```
-| Flag                       | Description                                                                                                                      |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `--set "Field Name" <val>` | Set a custom field by name. Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email |
-| `--remove "Field Name"`    | Remove a custom field value                                                                                                      |
-| `--json`                   | Force JSON output                                                                                                                |
-Both `--set` and `--remove` can be used together in one invocation.
-### `cu comment <id>`
-Post a comment on a task.
-```bash
-cu comment abc123 -m "Addressed in PR #42"
-cu comment abc123 -m "Done" --json
-```
-### `cu comments <id>`
-List comments on a task. Formatted view in terminal, JSON when piped.
-```bash
-cu comments abc123
-cu comments abc123 --json
-```
-### `cu comment-edit <commentId>`
-Edit an existing comment on a task.
-```bash
-cu comment-edit <commentId> -m "Updated text"
-cu comment-edit <commentId> -m "Fixed" --resolved
-cu comment-edit <commentId> -m "Reopening" --unresolved
-cu comment-edit <commentId> -m "Updated" --json
-```
-| Flag            | Required | Description                |
-| --------------- | -------- | -------------------------- |
-| `-m, --message` | yes      | New comment text           |
-| `--resolved`    | no       | Mark comment as resolved   |
-| `--unresolved`  | no       | Mark comment as unresolved |
-| `--json`        | no       | Force JSON output          |
-### `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"
-cu lists <spaceId> --json
-```
-| Flag               | Description                        |
-| ------------------ | ---------------------------------- |
-| `--name <partial>` | Filter lists by partial name match |
-| `--json`           | Force JSON output                  |
-### `cu spaces`
-List spaces in your workspace. Useful for getting space IDs for the `--space` filter.
-```bash
-cu spaces
-cu spaces --name "eng"
-cu spaces --my
-cu spaces --json
-```
-| Flag               | Description                                  |
-| ------------------ | -------------------------------------------- |
-| `--name <partial>` | Filter spaces by partial name match          |
-| `--my`             | Show only spaces where I have assigned tasks |
-| `--json`           | Force JSON output                            |
-### `cu open <query>`
-Open a task in the browser. Accepts a task ID or partial name.
-```bash
-cu open abc123
-cu open "login bug"
-cu open abc123 --json
+brew tap krodak/tap
+brew install clickup-cli
+cu init
 ```
-If the query matches multiple tasks by name, all matches are listed and the first is opened.
-### `cu search <query>`
+</details>
-Search my tasks by name. Supports multi-word queries with case-insensitive matching. Status filter supports fuzzy matching.
+## Set up your agent
-```bash
-cu search "login bug"
-cu search auth
-cu search "payment flow" --json
-cu search auth --status "prog"     # fuzzy matches "in progress"
-cu search "old task" --include-closed
-```
+The package includes a [skill file](https://agentskills.io) that teaches agents all available commands and when to use them. All three major coding agents support skills natively:
-### `cu summary`
+<details open>
+<summary>&nbsp;<img src="https://img.shields.io/badge/Claude_Code-D97757?logo=anthropic&logoColor=white" height="18" align="center">&nbsp;<strong>Claude Code</strong></summary>
-Daily standup helper. Shows tasks grouped into: recently completed, in progress, and overdue.
+**Install as a [plugin](https://docs.anthropic.com/en/docs/claude-code/plugins)** (recommended):
 ```bash
-cu summary
-cu summary --hours 48
-cu summary --json
+claude plugin add $(npm root -g)/@krodak/clickup-cli
 ```
-| Flag          | Description                                        |
-| ------------- | -------------------------------------------------- |
-| `--hours <n>` | Lookback for recently completed tasks (default 24) |
-| `--json`      | Force JSON output                                  |
+This registers the skill under the `clickup-cli:` namespace. Claude loads it automatically when you work with ClickUp tasks.
-### `cu overdue`
-List tasks that are past their due date (excludes done/closed tasks by default). Sorted most overdue first.
+**Or install as a personal skill** (no namespace prefix):
 ```bash
-cu overdue
-cu overdue --include-closed
-cu overdue --json
-```
-### `cu assign <id>`
-Assign or unassign users from a task. Supports `me` as shorthand for your user ID.
-```bash
-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
+SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
+mkdir -p ~/.claude/skills/clickup
+cp "$SKILL/SKILL.md" ~/.claude/skills/clickup/SKILL.md
 ```
-| Flag                | Description                       |
-| ------------------- | --------------------------------- |
-| `--to <userId>`     | Add assignee (user ID or `me`)    |
-| `--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
-```
+</details>
-| 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                           |
+<details>
+<summary>&nbsp;<img src="https://img.shields.io/badge/Codex-412991?logo=openai&logoColor=white" height="18" align="center">&nbsp;<strong>Codex</strong></summary>
-### `cu move <id>`
+Codex supports [agent skills](https://developers.openai.com/codex/skills) across CLI, IDE extension, and web. Skills use the same `SKILL.md` format with YAML frontmatter.
-Add or remove a task from a list. Tasks can belong to multiple lists in ClickUp.
+**Install as a user skill** (available across all your projects):
 ```bash
-cu move abc123 --to <listId>                    # add task to a list
-cu move abc123 --remove <listId>                # remove task from a list
-cu move abc123 --to <newListId> --remove <oldListId>  # move between lists
-cu move abc123 --to <listId> --json
+SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
+mkdir -p ~/.agents/skills/clickup
+cp "$SKILL/SKILL.md" ~/.agents/skills/clickup/SKILL.md
 ```
-| Flag                | Description                |
-| ------------------- | -------------------------- |
-| `--to <listId>`     | Add task to this list      |
-| `--remove <listId>` | Remove task from this list |
-| `--json`            | Force JSON output          |
-### `cu tag <id>`
-Add or remove tags on a task. Both `--add` and `--remove` can be used together.
+**Or install as a project skill** (checked into your repo):
 ```bash
-cu tag abc123 --add "bug"
-cu tag abc123 --add "bug,frontend,urgent"
-cu tag abc123 --remove "wontfix"
-cu tag abc123 --add "bug" --remove "triage"
-cu tag abc123 --add "bug" --json
+SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
+mkdir -p .agents/skills/clickup
+cp "$SKILL/SKILL.md" .agents/skills/clickup/SKILL.md
 ```
-| Flag              | Description                         |
-| ----------------- | ----------------------------------- |
-| `--add <tags>`    | Comma-separated tag names to add    |
-| `--remove <tags>` | Comma-separated tag names to remove |
-| `--json`          | Force JSON output                   |
+You can also use the built-in installer: `$skill-installer clickup`
-### `cu checklist`
+</details>
-Manage checklists on tasks. Six subcommands for full CRUD operations.
+<details>
+<summary>&nbsp;<img src="https://img.shields.io/badge/OpenCode-24292e?logoColor=white" height="18" align="center">&nbsp;<strong>OpenCode</strong></summary>
 ```bash
-cu checklist view abc123                           # view all checklists on a task
-cu checklist create abc123 "QA Checklist"           # add a checklist
-cu checklist delete <checklistId>                   # remove a checklist
-cu checklist add-item <checklistId> "Run tests"     # add an item
-cu checklist edit-item <clId> <itemId> --resolved   # mark item done
-cu checklist delete-item <clId> <itemId>            # remove an item
+SKILL=$(npm root -g)/@krodak/clickup-cli/skills/clickup-cli
+mkdir -p ~/.config/opencode/skills/clickup
+cp "$SKILL/SKILL.md" ~/.config/opencode/skills/clickup/SKILL.md
 ```
-| Subcommand    | Arguments                        | Description           |
-| ------------- | -------------------------------- | --------------------- |
-| `view`        | `<taskId>`                       | Show all checklists   |
-| `create`      | `<taskId> <name>`                | Create a checklist    |
-| `delete`      | `<checklistId>`                  | Delete a checklist    |
-| `add-item`    | `<checklistId> <name>`           | Add checklist item    |
-| `edit-item`   | `<checklistId> <itemId> [flags]` | Edit checklist item   |
-| `delete-item` | `<checklistId> <itemId>`         | Delete checklist item |
+</details>
-`edit-item` flags: `--name <text>`, `--resolved`, `--unresolved`, `--assignee <userId>`. All subcommands support `--json`.
+<details>
+<summary>&nbsp;<strong>Other agents</strong></summary>
+The skill file follows the [Agent Skills](https://agentskills.io) open standard. Copy `skills/clickup-cli/SKILL.md` into your agent's skill directory, system prompt, or `AGENTS.md`.
+</details>
+## API Coverage
-Checklists are also shown inline in `cu task <id>` detail view.
+[Full command reference with examples and flags](docs/commands.md).
+Status: :white_check_mark: implemented | :construction: planned | :no_entry_sign: won't add
+### Tasks
+| Feature              | Command                | Status             |
+| -------------------- | ---------------------- | ------------------ |
+| List my tasks        | `cu tasks`             | :white_check_mark: |
+| Get task details     | `cu task <id>`         | :white_check_mark: |
+| Create task          | `cu create`            | :white_check_mark: |
+| Update task          | `cu update <id>`       | :white_check_mark: |
+| Delete task          | `cu delete <id>`       | :white_check_mark: |
+| Search tasks         | `cu search <query>`    | :white_check_mark: |
+| Open in browser      | `cu open <query>`      | :white_check_mark: |
+| List subtasks        | `cu subtasks <id>`     | :white_check_mark: |
+| Assign / unassign    | `cu assign <id>`       | :white_check_mark: |
+| Duplicate task       | `cu duplicate <id>`    | :construction:     |
+| Create from template | `cu create --template` | :construction:     |
+| Bulk operations      | `cu bulk`              | :construction:     |
+### Dependencies & Relations
+| Feature              | Command                   | Status             |
+| -------------------- | ------------------------- | ------------------ |
+| Add dependency       | `cu depend <id>`          | :white_check_mark: |
+| Remove dependency    | `cu depend <id> --remove` | :white_check_mark: |
+| Add/remove task link | `cu link <id> <linksTo>`  | :white_check_mark: |
-### `cu auth`
+### Multi-list
-Check authentication status. Validates your API token and shows your user info.
+| Feature          | Command                 | Status             |
+| ---------------- | ----------------------- | ------------------ |
+| Add task to list | `cu move <id> --add`    | :white_check_mark: |
+| Remove from list | `cu move <id> --remove` | :white_check_mark: |
+### Sprints & Planning
+| Feature                  | Command       | Status             |
+| ------------------------ | ------------- | ------------------ |
+| Active sprint tasks      | `cu sprint`   | :white_check_mark: |
+| List all sprints         | `cu sprints`  | :white_check_mark: |
+| Assigned tasks by status | `cu assigned` | :white_check_mark: |
+| Standup summary          | `cu summary`  | :white_check_mark: |
+| Overdue tasks            | `cu overdue`  | :white_check_mark: |
+| Recently updated         | `cu inbox`    | :white_check_mark: |
+### Comments
+| Feature                  | Command                             | Status             |
+| ------------------------ | ----------------------------------- | ------------------ |
+| List comments            | `cu comments <id>`                  | :white_check_mark: |
+| Post comment             | `cu comment <id>`                   | :white_check_mark: |
+| Edit comment             | `cu comment-edit <id>`              | :white_check_mark: |
+| Task + comments combined | `cu activity <id>`                  | :white_check_mark: |
+| Delete comment           | `cu comment-delete <id>`            | :white_check_mark: |
+| Threaded replies         | `cu replies <id>` / `cu reply <id>` | :white_check_mark: |
+### Checklists
-```bash
-cu auth
-cu auth --json
-```
+| Feature          | Command                                  | Status             |
+| ---------------- | ---------------------------------------- | ------------------ |
+| View checklists  | `cu checklist view <id>`                 | :white_check_mark: |
+| Create checklist | `cu checklist create <id> <name>`        | :white_check_mark: |
+| Delete checklist | `cu checklist delete <id>`               | :white_check_mark: |
+| Add item         | `cu checklist add-item <id> <name>`      | :white_check_mark: |
+| Edit item        | `cu checklist edit-item <id> <itemId>`   | :white_check_mark: |
+| Delete item      | `cu checklist delete-item <id> <itemId>` | :white_check_mark: |
-### `cu config`
+### Custom Fields
-Manage CLI configuration.
+| Feature               | Command                  | Status             |
+| --------------------- | ------------------------ | ------------------ |
+| Set field value       | `cu field <id> --set`    | :white_check_mark: |
+| Remove field value    | `cu field <id> --remove` | :white_check_mark: |
+| List available fields | `cu fields <listId>`     | :construction:     |
-```bash
-cu config get apiToken
-cu config set teamId 12345
-cu config path
-```
+### Tags
-Valid keys: `apiToken`, `teamId`. Setting `apiToken` validates the `pk_` prefix.
+| Feature                 | Command             | Status             |
+| ----------------------- | ------------------- | ------------------ |
+| Add/remove tag on task  | `cu tag <id>`       | :white_check_mark: |
+| List space tags         | `cu tags <spaceId>` | :construction:     |
+| Create/delete space tag |                     | :construction:     |
-### `cu completion <shell>`
+### Time Tracking
-Output shell completion script. Supports `bash`, `zsh`, and `fish`.
+| Feature        | Command                       | Status             |
+| -------------- | ----------------------------- | ------------------ |
+| Start timer    | `cu time start <id>`          | :white_check_mark: |
+| Stop timer     | `cu time stop`                | :white_check_mark: |
+| Timer status   | `cu time status`              | :white_check_mark: |
+| Log time entry | `cu time log <id> <duration>` | :white_check_mark: |
+| List entries   | `cu time list`                | :white_check_mark: |
+| Update entry   | `cu time update <id>`         | :construction:     |
+| Delete entry   | `cu time delete <id>`         | :construction:     |
+### Workspace
+| Feature      | Command                | Status             |
+| ------------ | ---------------------- | ------------------ |
+| List spaces  | `cu spaces`            | :white_check_mark: |
+| List lists   | `cu lists <spaceId>`   | :white_check_mark: |
+| Check auth   | `cu auth`              | :white_check_mark: |
+| List folders | `cu folders <spaceId>` | :construction:     |
+| List members | `cu members`           | :construction:     |
+### Goals & Key Results
+| Feature            | Command    | Status         |
+| ------------------ | ---------- | -------------- |
+| List goals         | `cu goals` | :construction: |
+| Create/update goal |            | :construction: |
+| Key results CRUD   |            | :construction: |
+### Docs
+| Feature           | Command           | Status         |
+| ----------------- | ----------------- | -------------- |
+| Search docs       | `cu docs <query>` | :construction: |
+| View page content | `cu doc <id>`     | :construction: |
+### Attachments
+| Feature          | Command                 | Status         |
+| ---------------- | ----------------------- | -------------- |
+| Upload file      | `cu attach <id> <file>` | :construction: |
+| List attachments |                         | :construction: |
+### :no_entry_sign: Won't add
+| Feature               | Why                                                                         |
+| --------------------- | --------------------------------------------------------------------------- |
+| Webhooks              | Server-side. A CLI can't listen for events.                                 |
+| OAuth flow            | `cu init` already handles auth with API tokens.                             |
+| Guest/ACL             | Enterprise admin. Not what you reach for in a terminal.                     |
+| Chat/DM               | Use the ClickUp app. Chat doesn't belong in a CLI.                          |
+| Audit logs            | Enterprise admin.                                                           |
+| User/group management | Too destructive for a CLI - removing someone from a workspace is permanent. |
+| View CRUD             | Views are visual layouts. Configure them in the UI.                         |
+### Setup
+| Feature           | Command                 | Status             |
+| ----------------- | ----------------------- | ------------------ |
+| First-time setup  | `cu init`               | :white_check_mark: |
+| Get/set config    | `cu config`             | :white_check_mark: |
+| Shell completions | `cu completion <shell>` | :white_check_mark: |
+## Output Modes
+| Context        | Default                     | Override                     |
+| -------------- | --------------------------- | ---------------------------- |
+| Terminal (TTY) | Interactive tables + picker | `--json`                     |
+| Piped (no TTY) | Markdown (optimized for AI) | `--json` or `CU_OUTPUT=json` |
+Most commands scope to your assigned tasks by default - keeping output small and relevant for agent context windows.
-```bash
-eval "$(cu completion bash)"                                    # Bash
-eval "$(cu completion zsh)"                                     # Zsh
-cu completion fish > ~/.config/fish/completions/cu.fish          # Fish
-```
-## Config
+## Configuration
 ### Config file
@@ -573,6 +305,10 @@ Environment variables override config file values:
 When both are set, the config file is not required. Useful for CI/CD and containerized agents.
+## Why a CLI and not MCP?
+A CLI + skill file has fewer moving parts. No server process, no protocol layer. The agent already knows how to run shell commands - the skill file teaches it which ones exist. For tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.
 ## Development
 ```bash