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

@krodak/clickup-cli 0.14.0 → 0.15.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 (4) hide show

package/README.md +160 -485
package/dist/index.js +258 -4
package/package.json +1 -1
package/skills/clickup-cli/SKILL.md +12 -1

package/README.md CHANGED Viewed

@@ -8,547 +8,218 @@
 [![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 `cu`, install the skill file, and your agent 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."
-"What's my standup summary? What did I finish yesterday, what's in progress, what's overdue?"
+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.
-"Do exploratory work for task <id>, update the description with your findings, and flag blockers in a comment."
+## Setup
-"Create a subtask under <id> for the edge case we just found."
+You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)).
-"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
-```
+<details open>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/openai/999999" height="16" align="center">&nbsp;<strong>OpenCode</strong></summary>
-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`.
+**1. Install the CLI**
 ```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`
-Create a new task. If `--parent` is given, list is auto-detected from the parent task.
-```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`.
+**2. Install the skill**
 ```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
-```
-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 search "old task" --include-closed
-```
-### `cu summary`
-Daily standup helper. Shows tasks grouped into: recently completed, in progress, and overdue.
-```bash
-cu summary
-cu summary --hours 48
-cu summary --json
+mkdir -p ~/.config/opencode/skills/clickup
+cp $(npm root -g)/@krodak/clickup-cli/skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
 ```
-| Flag          | Description                                        |
-| ------------- | -------------------------------------------------- |
-| `--hours <n>` | Lookback for recently completed tasks (default 24) |
-| `--json`      | Force JSON output                                  |
+</details>
-### `cu overdue`
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/anthropic/D97757" height="16" align="center">&nbsp;<strong>Claude Code</strong></summary>
-List tasks that are past their due date (excludes done/closed tasks by default). Sorted most overdue first.
+**1. Install the CLI**
 ```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
+npm install -g @krodak/clickup-cli
+cu init
 ```
-| 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.
+**2. Install the skill**
 ```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
+mkdir -p ~/.claude/skills/clickup
+cp $(npm root -g)/@krodak/clickup-cli/skills/clickup-cli/SKILL.md ~/.claude/skills/clickup/SKILL.md
 ```
-| 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 move <id>`
-Add or remove a task from a list. Tasks can belong to multiple lists in ClickUp.
+Then reference it in your `CLAUDE.md` or project instructions.
-```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
-```
+</details>
-| Flag                | Description                |
-| ------------------- | -------------------------- |
-| `--to <listId>`     | Add task to this list      |
-| `--remove <listId>` | Remove task from this list |
-| `--json`            | Force JSON output          |
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/anthropic/D97757" height="16" align="center">&nbsp;<strong>Claude Desktop</strong></summary>
-### `cu tag <id>`
+Claude Desktop doesn't run CLI tools directly. Use it alongside a coding agent (Claude Code, OpenCode) that has `cu` installed, or run `cu` commands manually in your terminal.
-Add or remove tags on a task. Both `--add` and `--remove` can be used together.
+**Install the CLI:**
 ```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
+npm install -g @krodak/clickup-cli
+cu init
 ```
-| Flag              | Description                         |
-| ----------------- | ----------------------------------- |
-| `--add <tags>`    | Comma-separated tag names to add    |
-| `--remove <tags>` | Comma-separated tag names to remove |
-| `--json`          | Force JSON output                   |
-### `cu checklist`
+</details>
-Manage checklists on tasks. Six subcommands for full CRUD operations.
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/homebrew/FBB040" height="16" align="center">&nbsp;<strong>Homebrew</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
+brew tap krodak/tap
+brew install clickup-cli
+cu init
 ```
-| 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 |
+Then install the skill for your agent (see OpenCode or Claude Code sections above).
-`edit-item` flags: `--name <text>`, `--resolved`, `--unresolved`, `--assignee <userId>`. All subcommands support `--json`.
+</details>
-Checklists are also shown inline in `cu task <id>` detail view.
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/openai/999999" height="16" align="center">&nbsp;<strong>Codex / Other agents</strong></summary>
-### `cu auth`
-Check authentication status. Validates your API token and shows your user info.
+**1. Install the CLI**
 ```bash
-cu auth
-cu auth --json
-```
-### `cu config`
-Manage CLI configuration.
-```bash
-cu config get apiToken
-cu config set teamId 12345
-cu config path
+npm install -g @krodak/clickup-cli
+cu init
 ```
-Valid keys: `apiToken`, `teamId`. Setting `apiToken` validates the `pk_` prefix.
+**2. Add the skill to your agent**
-### `cu completion <shell>`
+Copy `skills/clickup-cli/SKILL.md` into your agent's system prompt or project instructions. It's a standalone markdown document that teaches the agent all available commands.
-Output shell completion script. Supports `bash`, `zsh`, and `fish`.
+</details>
-```bash
-eval "$(cu completion bash)"                                    # Bash
-eval "$(cu completion zsh)"                                     # Zsh
-cu completion fish > ~/.config/fish/completions/cu.fish          # Fish
-```
+## Commands
-## Config
+36 commands total. [Full reference with examples and flags](docs/commands.md).
+### Tasks
+| Command               | Description                                                 |
+| --------------------- | ----------------------------------------------------------- |
+| `cu tasks`            | List my tasks (filter by status, name, type, list, space)   |
+| `cu task <id>`        | Task details with custom fields and checklists              |
+| `cu subtasks <id>`    | List subtasks of a task                                     |
+| `cu create`           | Create a task or subtask                                    |
+| `cu update <id>`      | Update task fields (status, name, priority, assignee, etc.) |
+| `cu delete <id>`      | Delete a task (requires confirmation)                       |
+| `cu assign <id>`      | Assign/unassign users                                       |
+| `cu depend <id>`      | Add/remove task dependencies                                |
+| `cu move <id>`        | Add/remove task from lists                                  |
+| `cu open <query>`     | Open task in browser by ID or name                          |
+| `cu search <query>`   | Search my tasks by name                                     |
+| _`cu duplicate <id>`_ | _Copy a task - coming soon_                                 |
+| _`cu bulk`_           | _Bulk task operations - coming soon_                        |
+### Sprints & Planning
+| Command       | Description                                     |
+| ------------- | ----------------------------------------------- |
+| `cu sprint`   | My tasks in the active sprint (auto-detected)   |
+| `cu sprints`  | List all sprints                                |
+| `cu assigned` | All my tasks grouped by status                  |
+| `cu summary`  | Standup helper: completed, in progress, overdue |
+| `cu overdue`  | Tasks past their due date                       |
+| `cu inbox`    | Recently updated tasks                          |
+### Comments
+| Command                    | Description                      |
+| -------------------------- | -------------------------------- |
+| `cu comment <id>`          | Post a comment on a task         |
+| `cu comments <id>`         | List comments on a task          |
+| `cu comment-edit <id>`     | Edit an existing comment         |
+| `cu activity <id>`         | Task details + comments combined |
+| _`cu comment-delete <id>`_ | _Delete a comment - coming soon_ |
+### Custom Fields
+| Command                | Description                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `cu field <id>`        | Set/remove custom field values (text, number, dropdown, date, checkbox, url, email) |
+| _`cu fields <listId>`_ | _List available custom fields for a list - coming soon_                             |
+### Checklists
+| Command                                  | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `cu checklist view <id>`                 | View all checklists on a task                    |
+| `cu checklist create <id> <name>`        | Create a checklist                               |
+| `cu checklist delete <id>`               | Delete a checklist                               |
+| `cu checklist add-item <id> <name>`      | Add item to a checklist                          |
+| `cu checklist edit-item <id> <itemId>`   | Edit a checklist item (name, resolved, assignee) |
+| `cu checklist delete-item <id> <itemId>` | Delete a checklist item                          |
+### Tags
+| Command               | Description                                         |
+| --------------------- | --------------------------------------------------- |
+| `cu tag <id>`         | Add/remove tags on a task                           |
+| _`cu tags <spaceId>`_ | _List/create/delete space-level tags - coming soon_ |
+### Workspace
+| Command                  | Description                               |
+| ------------------------ | ----------------------------------------- |
+| `cu spaces`              | List workspace spaces                     |
+| `cu lists <spaceId>`     | Lists in a space (including folder lists) |
+| `cu auth`                | Check authentication status               |
+| _`cu folders <spaceId>`_ | _List folders in a space - coming soon_   |
+| _`cu members`_           | _List workspace members - coming soon_    |
+### Time Tracking
+| Command                       | Description                                     |
+| ----------------------------- | ----------------------------------------------- |
+| `cu time start <id>`          | Start tracking time on a task                   |
+| `cu time stop`                | Stop the running timer                          |
+| `cu time status`              | Show the currently running timer                |
+| `cu time log <id> <duration>` | Log a manual time entry (e.g. "2h", "30m")      |
+| `cu time list`                | List recent time entries (default: last 7 days) |
+### Setup
+| Command                 | Description                       |
+| ----------------------- | --------------------------------- |
+| `cu init`               | First-time setup wizard           |
+| `cu config`             | Get/set config values             |
+| `cu completion <shell>` | Shell completions (bash/zsh/fish) |
+## 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.
+## Configuration
 ### Config file
@@ -573,6 +244,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

package/dist/index.js CHANGED Viewed

@@ -120,6 +120,9 @@ var ClickUpClient = class {
   async getSpaceWithStatuses(spaceId) {
     return this.request(`/space/${spaceId}`);
   }
+  async getListWithStatuses(listId) {
+    return this.request(`/list/${listId}`);
+  }
   async getSpaces(teamId) {
     const data = await this.request(`/team/${teamId}/space?archived=false`);
     return data.spaces ?? [];
@@ -235,6 +238,63 @@ var ClickUpClient = class {
       { method: "DELETE" }
     );
   }
+  async startTimeEntry(teamId, taskId, description) {
+    const body = {
+      tid: taskId,
+      start: Date.now(),
+      duration: -1
+    };
+    if (description) body.description = description;
+    const data = await this.request(`/team/${teamId}/time_entries/start`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    return data.data;
+  }
+  async stopTimeEntry(teamId) {
+    const data = await this.request(`/team/${teamId}/time_entries/stop`, {
+      method: "POST"
+    });
+    return data.data;
+  }
+  async getRunningTimeEntry(teamId) {
+    const data = await this.request(
+      `/team/${teamId}/time_entries/current`
+    );
+    return data.data ?? null;
+  }
+  async createTimeEntry(teamId, taskId, duration, opts) {
+    const start = opts?.start ?? Date.now() - duration;
+    const body = {
+      tid: taskId,
+      start,
+      duration
+    };
+    if (opts?.description) body.description = opts.description;
+    const data = await this.request(`/team/${teamId}/time_entries`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    return data.data;
+  }
+  async getTimeEntries(teamId, opts) {
+    const params = new URLSearchParams();
+    if (opts?.startDate != null) params.set("start_date", String(opts.startDate));
+    if (opts?.endDate != null) params.set("end_date", String(opts.endDate));
+    const query = params.toString();
+    const url = `/team/${teamId}/time_entries${query ? `?${query}` : ""}`;
+    const data = await this.request(url);
+    const entries = data.data ?? [];
+    if (opts?.taskId) {
+      return entries.filter((e) => e.task?.id === opts.taskId);
+    }
+    return entries;
+  }
+  async deleteTimeEntry(teamId, timeEntryId) {
+    await this.request(`/team/${teamId}/time_entries/${timeEntryId}`, {
+      method: "DELETE"
+    });
+  }
 };
 // src/config.ts
@@ -865,9 +925,8 @@ function hasUpdateFields(options) {
 }
 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 list = await client.getListWithStatuses(task.list.id);
+  const available = list.statuses.map((s) => s.status);
   const matched = matchStatus(statusInput, available);
   if (!matched) {
     throw new Error(`No matching status for "${statusInput}". Available: ${available.join(", ")}`);
@@ -1749,7 +1808,7 @@ function bashCompletion() {
     cword=$COMP_CWORD
   fi
-  local commands="init auth tasks task update create sprint sprints subtasks comment comment-edit comments activity lists spaces inbox assigned open search summary overdue assign depend move field delete tag checklist config completion"
+  local commands="init auth tasks task update create sprint sprints subtasks comment comment-edit comments activity lists spaces inbox assigned open search summary overdue assign depend move field delete tag checklist time config completion"
   if [[ $cword -eq 1 ]]; then
     COMPREPLY=($(compgen -W "$commands --help --version" -- "$cur"))
@@ -1850,6 +1909,11 @@ function bashCompletion() {
         COMPREPLY=($(compgen -W "view create delete add-item edit-item delete-item" -- "$cur"))
       fi
       ;;
+    time)
+      if [[ $cword -eq 2 ]]; then
+        COMPREPLY=($(compgen -W "start stop status log list" -- "$cur"))
+      fi
+      ;;
     comment-edit)
       COMPREPLY=($(compgen -W "-m --message --resolved --unresolved --json" -- "$cur"))
       ;;
@@ -1906,6 +1970,7 @@ _cu() {
     'delete:Delete a task'
     'tag:Add or remove tags from a task'
     'checklist:Manage checklists on a task'
+    'time:Track time on tasks'
     'comment-edit:Edit an existing comment'
     'config:Manage CLI configuration'
     'completion:Output shell completion script'
@@ -2142,6 +2207,53 @@ _cu() {
               ;;
           esac
           ;;
+        time)
+          local -a time_cmds
+          time_cmds=(
+            'start:Start tracking time on a task'
+            'stop:Stop the running timer'
+            'status:Show the currently running timer'
+            'log:Log a manual time entry'
+            'list:List recent time entries'
+          )
+          _arguments -C \\
+            '1:time command:->time_cmd' \\
+            '*::time_arg:->time_args'
+          case $state in
+            time_cmd)
+              _describe 'time command' time_cmds
+              ;;
+            time_args)
+              case $words[1] in
+                start)
+                  _arguments \\
+                    '1:task_id:' \\
+                    '(-d --description)'{-d,--description}'[Description]:text:' \\
+                    '--json[Force JSON output]'
+                  ;;
+                stop)
+                  _arguments '--json[Force JSON output]'
+                  ;;
+                status)
+                  _arguments '--json[Force JSON output]'
+                  ;;
+                log)
+                  _arguments \\
+                    '1:task_id:' \\
+                    '2:duration:' \\
+                    '(-d --description)'{-d,--description}'[Description]:text:' \\
+                    '--json[Force JSON output]'
+                  ;;
+                list)
+                  _arguments \\
+                    '--days[Number of days to look back]:days:' \\
+                    '--task[Filter by task ID]:task_id:' \\
+                    '--json[Force JSON output]'
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
         comment-edit)
           _arguments \\
             '1:comment_id:' \\
@@ -2217,6 +2329,7 @@ complete -c cu -n __fish_use_subcommand -a field -d 'Set or remove a custom fiel
 complete -c cu -n __fish_use_subcommand -a delete -d 'Delete a task'
 complete -c cu -n __fish_use_subcommand -a tag -d 'Add or remove tags from a task'
 complete -c cu -n __fish_use_subcommand -a checklist -d 'Manage checklists on a task'
+complete -c cu -n __fish_use_subcommand -a time -d 'Track time on tasks'
 complete -c cu -n __fish_use_subcommand -a comment-edit -d 'Edit an existing comment'
 complete -c cu -n __fish_use_subcommand -a config -d 'Manage CLI configuration'
 complete -c cu -n __fish_use_subcommand -a completion -d 'Output shell completion script'
@@ -2339,6 +2452,17 @@ complete -c cu -n '__fish_seen_subcommand_from edit-item' -l resolved -d 'Mark i
 complete -c cu -n '__fish_seen_subcommand_from edit-item' -l unresolved -d 'Mark item as unresolved'
 complete -c cu -n '__fish_seen_subcommand_from edit-item' -l assignee -d 'Assign user by ID'
+complete -c cu -n '__fish_seen_subcommand_from time; and not __fish_seen_subcommand_from start stop status log list' -a start -d 'Start tracking time on a task'
+complete -c cu -n '__fish_seen_subcommand_from time; and not __fish_seen_subcommand_from start stop status log list' -a stop -d 'Stop the running timer'
+complete -c cu -n '__fish_seen_subcommand_from time; and not __fish_seen_subcommand_from start stop status log list' -a status -d 'Show the currently running timer'
+complete -c cu -n '__fish_seen_subcommand_from time; and not __fish_seen_subcommand_from start stop status log list' -a log -d 'Log a manual time entry'
+complete -c cu -n '__fish_seen_subcommand_from time; and not __fish_seen_subcommand_from start stop status log list' -a list -d 'List recent time entries'
+complete -c cu -n '__fish_seen_subcommand_from start stop status log list; and __fish_seen_subcommand_from time' -l json -d 'Force JSON output'
+complete -c cu -n '__fish_seen_subcommand_from start; and __fish_seen_subcommand_from time' -s d -l description -d 'Description'
+complete -c cu -n '__fish_seen_subcommand_from log; and __fish_seen_subcommand_from time' -s d -l description -d 'Description'
+complete -c cu -n '__fish_seen_subcommand_from list; and __fish_seen_subcommand_from time' -l days -d 'Number of days to look back'
+complete -c cu -n '__fish_seen_subcommand_from list; and __fish_seen_subcommand_from time' -l task -d 'Filter by task ID'
 complete -c cu -n '__fish_seen_subcommand_from comment-edit' -s m -l message -d 'New comment text'
 complete -c cu -n '__fish_seen_subcommand_from comment-edit' -l resolved -d 'Mark comment as resolved'
 complete -c cu -n '__fish_seen_subcommand_from comment-edit' -l unresolved -d 'Mark comment as unresolved'
@@ -2651,6 +2775,71 @@ async function editComment(config, commentId, text, resolved) {
   await client.updateComment(commentId, text, resolved);
 }
+// src/commands/time.ts
+import chalk6 from "chalk";
+function formatDuration2(ms) {
+  const totalMinutes = Math.round(Math.abs(ms) / 6e4);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours > 0 && minutes > 0) return `${hours}h ${minutes}m`;
+  if (hours > 0) return `${hours}h`;
+  return `${minutes}m`;
+}
+function formatTimestamp2(ms) {
+  return new Date(Number(ms)).toLocaleString("en-US", {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit"
+  });
+}
+async function startTimer(config, taskId, description) {
+  const client = new ClickUpClient(config);
+  return client.startTimeEntry(config.teamId, taskId, description);
+}
+async function stopTimer(config) {
+  const client = new ClickUpClient(config);
+  return client.stopTimeEntry(config.teamId);
+}
+async function timerStatus(config) {
+  const client = new ClickUpClient(config);
+  return client.getRunningTimeEntry(config.teamId);
+}
+async function logTime(config, taskId, durationStr, description) {
+  const client = new ClickUpClient(config);
+  const duration = parseTimeEstimate(durationStr);
+  return client.createTimeEntry(config.teamId, taskId, duration, { description });
+}
+async function listTimeEntries(config, opts) {
+  const client = new ClickUpClient(config);
+  const days = opts?.days ?? 7;
+  const endDate = Date.now();
+  const startDate = endDate - days * 24 * 60 * 60 * 1e3;
+  return client.getTimeEntries(config.teamId, {
+    startDate,
+    endDate,
+    taskId: opts?.taskId
+  });
+}
+function formatTimeEntry(entry) {
+  const lines = [];
+  const taskName = entry.task?.name ?? "No task";
+  const taskId = entry.task?.id ?? "";
+  const isRunning = entry.duration < 0;
+  const elapsed = isRunning ? Date.now() - Number(entry.start) : entry.duration;
+  const durationStr = formatDuration2(elapsed);
+  const status = isRunning ? chalk6.green("RUNNING") : "";
+  lines.push(`${chalk6.bold(taskName)} ${chalk6.dim(taskId)} ${status}`);
+  lines.push(
+    `  ${durationStr} - ${formatTimestamp2(entry.start)}${entry.description ? ` - ${entry.description}` : ""}`
+  );
+  return lines.join("\n");
+}
+function formatTimeEntries(entries) {
+  if (entries.length === 0) return "No time entries";
+  return entries.map(formatTimeEntry).join("\n");
+}
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -3049,6 +3238,71 @@ checklistCmd.command("delete-item <checklistId> <checklistItemId>").description(
     }
   })
 );
+var timeCmd = program.command("time").description("Track time on tasks");
+timeCmd.command("start <taskId>").description("Start tracking time on a task").option("-d, --description <text>", "Description for the time entry").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (taskId, opts) => {
+    const config = loadConfig();
+    const result = await startTimer(config, taskId, opts.description);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const taskName = result.task?.name ?? taskId;
+      console.log(`Started timer on "${taskName}"`);
+    }
+  })
+);
+timeCmd.command("stop").description("Stop the running timer").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (opts) => {
+    const config = loadConfig();
+    const result = await stopTimer(config);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatTimeEntry(result));
+    }
+  })
+);
+timeCmd.command("status").description("Show the currently running timer").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (opts) => {
+    const config = loadConfig();
+    const result = await timerStatus(config);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result) {
+      console.log(formatTimeEntry(result));
+    } else {
+      console.log("No timer running");
+    }
+  })
+);
+timeCmd.command("log <taskId> <duration>").description('Log a manual time entry (e.g. "2h", "30m", "1h30m")').option("-d, --description <text>", "Description for the time entry").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (taskId, duration, opts) => {
+      const config = loadConfig();
+      const result = await logTime(config, taskId, duration, opts.description);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Logged ${duration} on task ${taskId}`);
+      }
+    }
+  )
+);
+timeCmd.command("list").description("List recent time entries (default: last 7 days)").option("--days <n>", "Number of days to look back", "7").option("--task <taskId>", "Filter by task ID").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (opts) => {
+    const config = loadConfig();
+    const days = opts.days ? Number(opts.days) : 7;
+    if (!Number.isFinite(days) || days <= 0) {
+      throw new Error("--days must be a positive number");
+    }
+    const entries = await listTimeEntries(config, { days, taskId: opts.task });
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(entries, null, 2));
+    } else {
+      console.log(formatTimeEntries(entries));
+    }
+  })
+);
 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 CHANGED Viewed

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

package/skills/clickup-cli/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: clickup
-description: 'Use when managing ClickUp tasks, 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, setting custom fields, deleting tasks, managing tags, managing checklists, editing comments.'
+description: 'Use when managing ClickUp tasks, 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, setting custom fields, deleting tasks, managing tags, managing checklists, editing comments, time tracking.'
 ---
 # ClickUp CLI (`cu`)
@@ -73,6 +73,11 @@ All commands support `--help` for full flag details.
 | `cu checklist add-item <checklistId> <name> [--json]`                                                                                                                              | Add item to a checklist                     |
 | `cu checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--json]`                                                                    | Edit a checklist item                       |
 | `cu checklist delete-item <checklistId> <itemId> [--json]`                                                                                                                         | Delete a checklist item                     |
+| `cu time start <taskId> [-d desc] [--json]`                                                                                                                                        | Start tracking time on a task               |
+| `cu time stop [--json]`                                                                                                                                                            | Stop the running timer                      |
+| `cu time status [--json]`                                                                                                                                                          | Show currently running timer                |
+| `cu time log <taskId> <duration> [-d desc] [--json]`                                                                                                                               | Log manual time entry (e.g. "2h", "30m")    |
+| `cu time list [--days n] [--task id] [--json]`                                                                                                                                     | List recent time entries                    |
 | `cu config get <key>` / `cu config set <key> <value>` / `cu config path`                                                                                                           | Manage CLI config                           |
 | `cu completion <shell>`                                                                                                                                                            | Shell completions (bash/zsh/fish)           |
@@ -106,6 +111,7 @@ All commands support `--help` for full flag details.
 | `cu overdue`            | Excludes closed tasks, sorted most overdue first                                                       |
 | `cu open`               | Tries task ID first, falls back to name search                                                         |
 | `cu checklist`          | Full CRUD for task checklists: view, create, delete, add-item, edit-item, delete-item                  |
+| `cu time`               | Track time: start/stop timer, log entries, list history. Duration format: "2h", "30m", "1h30m"         |
 | `cu comment-edit`       | Edit comment text and resolution status                                                                |
 | `cu task`               | Shows custom fields and checklists in detail view                                                      |
 | `cu lists`              | Discovers list IDs needed for `--list` and `cu create -l`                                              |
@@ -164,6 +170,11 @@ cu checklist create abc123def "QA Steps"              # add checklist
 cu checklist add-item <clId> "Run unit tests"         # add item
 cu checklist edit-item <clId> <itemId> --resolved     # check off item
 cu comment-edit <commentId> -m "Updated findings"     # edit a comment
+cu time start abc123def -d "Working on feature"  # start timer
+cu time status                                    # check running timer
+cu time stop                                      # stop timer
+cu time log abc123def 2h -d "Code review"         # log manual entry
+cu time list --days 7                             # recent entries
 cu delete abc123def --confirm          # irreversible!
 ```