clickup-agent-cli 0.5.1 → 0.5.2

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "clickup",
       "source": "./",
       "description": "ClickUp CLI with 31 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
-      "version": "0.5.1",
+      "version": "0.5.2",
       "homepage": "https://github.com/henryreith/clickup-cli",
       "keywords": ["clickup", "project-management", "tasks", "time-tracking"],
       "category": "productivity"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup",
   "description": "ClickUp CLI with 31 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "author": {
     "name": "Henry Reith"
   },

package/AGENTS.md

@@ -0,0 +1,61 @@
+# ClickUp CLI: Agent Operating Manual
+
+You have (or can install) `clickup`, a command-line tool covering the full ClickUp API v2. This file is the fastest path from zero to productive for any agent on any platform. Everything here works headless.
+
+## Setup
+
+```bash
+npm install -g clickup-agent-cli
+
+# Authenticate: env var (preferred for agents), --token-file, or --token per call
+export CLICKUP_API_TOKEN=pk_your_token
+
+# Verify auth and workspace resolution
+clickup config validate
+
+# One-time workspace binding (auto-selects when the account has one workspace)
+clickup workspace setup
+```
+
+## Discover, never guess
+
+Do not guess command syntax. The CLI is self-describing:
+
+```bash
+clickup skill show clickup          # Root skill: index of all capabilities (~150 tokens)
+clickup skill list                  # All 31 skills (12 resource references, 18 workflows)
+clickup skill show <name>           # Full skill content (JSON with a "content" field when piped)
+clickup skill path <name>           # Skill directory: bundled references/, assets/, scripts/
+clickup schema <resource>           # Actions for a resource (task, list, doc, time, ...)
+clickup schema <resource>.<action>  # Required and optional flags for one action
+```
+
+Skills bundle supporting files per the Agent Skills standard: `assets/report-template.md` (copy the structure for report output), `scripts/*.mjs` (deterministic helpers; pipe JSON in via node), and `references/` (deep detail such as `clickup skill path clickup`/references/gotchas.md).
+
+## Conventions that matter
+
+- **Output**: JSON by default when piped; force with `--format json|table|csv|tsv|quiet|id|md`. `--format id` prints just the first result's ID for capture: `ID=$(clickup task create ... --format id)`.
+- **Exit codes**: 0 ok, 1 general, 2 bad arguments, 3 auth, 4 not found, 5 permission, 6 rate limited, 7 network. Branch on these.
+- **Destructive commands** (`* delete`, `field remove`, `time delete`) require `--confirm` when non-interactive. Pass it deliberately; never bypass a confirmation you were not asked to give.
+- **Dates**: Unix ms/seconds, ISO 8601 (`2026-07-10`), or relative (`today`, `tomorrow`, `3d`, `-1w`, `friday`). Filter flags ending `-gt`/`-lt` take Unix ms only.
+- **Rate limits**: ~100 requests/min; 429s retry automatically. Prefer `task bulk-update`/`task bulk-delete` for batches.
+- **Dry runs**: add `--dry-run` to print the exact request without sending it.
+- Errors and spinners go to stderr; stdout is data only. Safe to pipe.
+
+## Quick example
+
+```bash
+# Find the list, create a task, comment on it
+LIST_ID=$(clickup list list --space-id 123 --filter name="Sprint 12" --format id)
+TASK_ID=$(clickup task create --list-id "$LIST_ID" --name "Fix login redirect" \
+  --priority high --due-date friday --format id)
+clickup comment create --task-id "$TASK_ID" --text "Repro steps in thread"
+```
+
+## For Claude Code specifically
+
+Install as a plugin instead: `/plugin marketplace add henryreith/clickup-cli` then `/plugin install clickup@clickup-agent-cli`. Skills load natively (`/clickup:weekly-review`, etc.).
+
+## Developing this repo
+
+Build/test conventions live in [CLAUDE.md](./CLAUDE.md): `npm run typecheck && npm test && npm run build && npm run lint:skills` must pass. The full command reference is [COMMANDS.md](./COMMANDS.md); architecture is [SPEC.md](./SPEC.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Reith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,11 @@
 # ClickUp CLI
 
+[![npm](https://img.shields.io/npm/v/clickup-agent-cli)](https://www.npmjs.com/package/clickup-agent-cli)
+[![node](https://img.shields.io/node/v/clickup-agent-cli)](https://nodejs.org)
+[![CI](https://github.com/henryreith/clickup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/henryreith/clickup-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/clickup-agent-cli)](./LICENSE)
+[![Agent Skills](https://img.shields.io/badge/agent%20skills-31-blueviolet)](./skills)
+
 Zero-overhead CLI for the ClickUp API v2 -- for AI agents, scripts, and automation. Covers the entire API surface with all MCP capabilities and more.
 
 ## Why This Exists
@@ -187,7 +193,7 @@ This creates `/marketing-weekly` alongside the built-in `/clickup:*` skills.
 
 ### Bootstrap From Any Agent
 
-Any agent that can run shell commands can set up and use the CLI in five steps, no plugin system required:
+The repo and npm package ship an [AGENTS.md](./AGENTS.md) operating manual that agent platforms (Codex, Cursor, Gemini CLI, custom agents) pick up automatically. Any agent that can run shell commands can set up and use the CLI in five steps, no plugin system required:
 
 ```bash
 # 1. Install

package/dist/clickup.js

@@ -4629,7 +4629,7 @@ function registerChatCommands(program, getClient) {
 }
 
 // src/cli.ts
-var VERSION = "0.5.1";
+var VERSION = "0.5.2";
 function createProgram() {
   const program = new Command();
   program.name("clickup").description("ClickUp CLI - Manage ClickUp workspaces from the terminal").version(VERSION).option("--token <token>", "API token").option("--token-file <path>", "Read API token from this file path").option("--profile <name>", "Profile to use (key, workspace name, or nickname)").option("--workspace-id <id>", "Workspace ID").addOption(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup-agent-cli",
-  "version": "0.5.1",
-  "description": "CLI covering the entire ClickUp API v2 surface",
+  "version": "0.5.2",
+  "description": "Zero-overhead ClickUp CLI for AI agents, shell scripts, and automation. Full ClickUp API v2 coverage with 31 bundled agent skills.",
   "type": "module",
   "bin": {
     "clickup": "dist/clickup.js"
@@ -9,7 +9,8 @@
   "files": [
     "dist",
     "skills",
-    ".claude-plugin"
+    ".claude-plugin",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=22.0.0"