@krodak/clickup-cli 1.18.1 → 1.19.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup-cli",
   "description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cup command",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -14,6 +14,16 @@
 npm install -g @krodak/clickup-cli && cup init
 ```
 
+## For AI Agents
+
+Paste this into any AI agent to get started immediately:
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md
+```
+
+Or install the skill permanently with `cup skill` (see [Set up your agent](#set-up-your-agent) below).
+
 ## Talk to your agent
 
 Install the CLI, add the skill file to your agent, and it works with ClickUp. No API knowledge needed.
@@ -73,13 +83,13 @@ cup init
 
 ## Set up your agent
 
-The package includes a [skill file](https://agentskills.io) that teaches agents all available commands. Install it with:
+After installing `cup`, run:
 
 ```bash
 cup skill
 ```
 
-This detects which agents you have (Claude Code, Codex, OpenCode) and installs the skill to the right locations. Run it again after updating `cup` to refresh the skill.
+This detects which agents you have (Claude Code, Codex, OpenCode) and installs the [skill file](https://agentskills.io) to the right locations. Run it again after updating `cup` to refresh the skill.
 
 <details>
 <summary>Manual install options</summary>
@@ -126,13 +136,19 @@ cup skill --path ~/.config/opencode/skills/clickup/SKILL.md
 </details>
 
 <details>
-<summary>&nbsp;<strong>Other agents</strong></summary>
+<summary>&nbsp;<strong>Other agents / npx</strong></summary>
+
+Without installing globally, you can use `npx`:
 
 ```bash
-cup skill --print > SKILL.md   # output skill content to a file
+npx @krodak/clickup-cli skill --print > SKILL.md
 ```
 
-Or copy `skills/clickup-cli/SKILL.md` into your agent's skill directory or `AGENTS.md`.
+Or install the skill directly from GitHub via the [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add https://github.com/krodak/clickup-cli
+```
 
 </details>
 
@@ -142,20 +158,21 @@ Or copy `skills/clickup-cli/SKILL.md` into your agent's skill directory or `AGEN
 
 Full CRUD for the core ClickUp workflow:
 
-| Area                 | Capabilities                                                                                                            |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| ✅ **Tasks**         | Create, read, update, delete, duplicate, search, subtasks, assign, dependencies, links, multi-list, bulk status updates |
-| 💬 **Comments**      | Post, edit, delete, threaded replies, notify all                                                                        |
-| 📄 **Docs**          | List, read, create, edit, delete (v3 API)                                                                               |
-| ⏱️ **Time Tracking** | Start/stop timer, log entries, list/update/delete history                                                               |
-| ☑️ **Checklists**    | View, create, delete, add/edit/delete items                                                                             |
-| 🔧 **Custom Fields** | List, create, set, remove values (dropdown, date, checkbox, text, etc.)                                                 |
-| 🏷️ **Tags**          | Add/remove on tasks, space-level create/update/delete                                                                   |
-| 🎯 **Goals & OKRs**  | Goals CRUD, key results CRUD                                                                                            |
-| 🏃 **Sprints**       | Auto-detect active sprint, flexible date parsing, config override                                                       |
-| 👁️ **Views**         | List, get, create, update, delete views on lists                                                                        |
-| 🏢 **Workspace**     | Spaces, folders, lists (read + create + from template), members, task types, templates                                  |
-| 📎 **Attachments**   | Upload files to tasks, shown in detail views                                                                            |
+| Area                 | Capabilities                                                                                                                           |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| ✅ **Tasks**         | Create, read, update, delete, duplicate, search, subtasks, assign, dependencies, links, multi-list, bulk status updates                |
+| 💬 **Comments**      | Post, edit, delete by ID or by task scope for your own comments, threaded replies, notify all                                          |
+| 📄 **Docs**          | List, read, create, edit, delete (v3 API)                                                                                              |
+| ⏱️ **Time Tracking** | Start/stop timer, log entries, list/update/delete history                                                                              |
+| ☑️ **Checklists**    | View, create, delete, add/edit/delete items                                                                                            |
+| 🔧 **Custom Fields** | List, create, set, remove values (dropdown, date, checkbox, text, etc.)                                                                |
+| 🏷️ **Tags**          | Add/remove on tasks, space-level create/update/delete                                                                                  |
+| 🎯 **Goals & OKRs**  | Goals CRUD, key results CRUD                                                                                                           |
+| 🏃 **Sprints**       | Auto-detect active sprint, `sprint:current` pseudo-ID for move/create, flexible date parsing, config override, favorite sprint folders |
+| ⭐ **Favorites**     | Local favorites for quick access to sprint folders, spaces, lists, folders, views, tasks                                               |
+| 👁️ **Views**         | List, get, create, update, delete views on lists                                                                                       |
+| 🏢 **Workspace**     | Spaces, folders, lists (read + create + from template), members, task types, templates                                                 |
+| 📎 **Attachments**   | Upload files to tasks, shown in detail views                                                                                           |
 
 [Full API coverage details](docs/api-coverage.md) | [Command reference](docs/commands.md)
 
@@ -209,6 +226,20 @@ Environment variables override config file values:
 
 When both `CU_API_TOKEN` and `CU_TEAM_ID` are set, the config file is not required. Useful for CI/CD and containerized agents.
 
+## Troubleshooting
+
+**"No config file found"** - Run `cup init` to set up your API token and workspace.
+
+**"Config missing apiToken"** - Set `CU_API_TOKEN` environment variable or run `cup init`.
+
+**No output from `cup`** - Make sure you're on v1.5.2+. Older versions had a symlink bug. Update: `npm install -g @krodak/clickup-cli`
+
+**Sprint not detected** - Your sprint folder needs "sprint", "iteration", "cycle", or "scrum" in the name. Or pin it: `cup config set sprintFolderId <id>`. You can also favorite a sprint folder: `cup favorite add sprint-folder <id>`
+
+**Custom field filter fails** - `--field` requires `--list` to resolve field names to IDs: `cup tasks --list <id> --field "Sprint" "Week 1"`
+
+**Wrong workspace** - Switch profile: `cup profile use <name>` or use `-p <name>` for one command.
+
 ## Development
 
 ```bash