@krodak/clickup-cli 1.6.0 → 1.7.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.6.0",
+  "version": "1.7.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -1,18 +1,19 @@
-# cup - ClickUp CLI
-
-> A ClickUp CLI built for AI agents that also works well for humans. Outputs Markdown when piped (optimized for AI context windows), interactive tables when run in a terminal.
-
-[![npm](https://img.shields.io/npm/v/@krodak/clickup-cli)](https://www.npmjs.com/package/@krodak/clickup-cli)
-[![node](https://img.shields.io/node/v/@krodak/clickup-cli)](https://nodejs.org)
-[![license](https://img.shields.io/npm/l/@krodak/clickup-cli)](./LICENSE)
-[![CI](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml)
+<p align="center">
+  <img src="banner.png" alt="cup - ClickUp CLI for AI agents (and humans)" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@krodak/clickup-cli"><img src="https://img.shields.io/npm/v/@krodak/clickup-cli" alt="npm"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@krodak/clickup-cli" alt="node"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@krodak/clickup-cli" alt="license"></a>
+  <a href="https://github.com/krodak/clickup-cli/actions/workflows/ci.yml"><img src="https://github.com/krodak/clickup-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/krodak/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-FBB040?logo=homebrew&logoColor=black" alt="homebrew"></a>
+</p>
 
 ```bash
 npm install -g @krodak/clickup-cli && cup init
 ```
 
-`cup` is the binary name. The previous `cu` name was retired in v0.21.0 to avoid conflict with the Unix [cu(1)](<https://en.wikipedia.org/wiki/Cu_(Unix_utility)>) utility.
-
 ## Talk to your agent
 
 Install the CLI, add the skill file to your agent, and it works with ClickUp. No API knowledge needed.
@@ -29,6 +30,18 @@ Install the CLI, add the skill file to your agent, and it works with ClickUp. No
 
 The agent reads the skill file, picks the right `cup` commands, and handles everything. You don't need to learn the CLI - the agent does.
 
+### Agent mode
+
+When piped (no TTY), output is Markdown optimized for AI context windows. Pass `--json` for structured data.
+
+![Agent Mode - markdown and JSON output](demos/agent-mode.gif)
+
+### Terminal mode
+
+In a terminal, you get interactive tables with colors. Most commands scope to your assigned tasks by default.
+
+![TTY Mode - interactive tables and detail views](demos/tty-mode.gif)
+
 ## 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.
@@ -130,39 +143,22 @@ The skill file follows the [Agent Skills](https://agentskills.io) open standard.
 
 Full CRUD for the core ClickUp workflow:
 
-**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, 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
-
-**Workspace** - spaces, folders, lists, 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, 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, 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                                                       |
+| 🏢 **Workspace**     | Spaces, folders, lists (read + create), 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)
 
-## 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
 
 ### Profiles
@@ -213,23 +209,6 @@ 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.
 
-## Custom Task IDs
-
-ClickUp workspaces can configure custom task IDs with a prefix per space (e.g., `PROJ-123`, `DEV-42`). The CLI detects these automatically - any ID matching the `PREFIX-DIGITS` format (uppercase letters, hyphen, digits) is treated as a custom task ID.
-
-All commands that accept task IDs work with both native IDs and custom IDs:
-
-```bash
-cup task PROJ-123
-cup update DEV-42 --status done
-cup comment PROJ-456 -m "Fixed in latest commit"
-cup subtasks DEV-100
-```
-
-Custom ID resolution uses the `teamId` from your config, which is required (`cup init` sets it up).
-
-**Task links with custom IDs:** The `cup link` command passes both task IDs in a single API request. When both IDs are custom, this works correctly. However, mixing custom and native IDs in a single link command may not work as expected because the ClickUp API applies the `custom_task_ids` flag to all IDs in the request.
-
 ## Development
 
 ```bash

package/dist/index.js

@@ -100,6 +100,12 @@ var ClickUpClient = class {
         ...options.headers
       }
     });
+    if (res.status === 204 || res.headers.get("content-length") === "0") {
+      if (!res.ok) {
+        throw new Error(`ClickUp API error ${res.status}: ${res.statusText}`);
+      }
+      return {};
+    }
     let parsed;
     try {
       parsed = await res.json();
@@ -218,6 +224,12 @@ var ClickUpClient = class {
   async getListWithStatuses(listId) {
     return this.request(`/list/${listId}`);
   }
+  async createSpace(teamId, name) {
+    return this.request(`/team/${teamId}/space`, {
+      method: "POST",
+      body: JSON.stringify({ name, multiple_assignees: true })
+    });
+  }
   async getSpaces(teamId) {
     const data = await this.request(`/team/${teamId}/space?archived=false`);
     return readCollectionField(data, "spaces", "spaces");
@@ -232,6 +244,24 @@ var ClickUpClient = class {
       "custom task types"
     );
   }
+  async createList(spaceId, name) {
+    return this.request(`/space/${spaceId}/list`, {
+      method: "POST",
+      body: JSON.stringify({ name })
+    });
+  }
+  async createFolderList(folderId, name) {
+    return this.request(`/folder/${folderId}/list`, {
+      method: "POST",
+      body: JSON.stringify({ name })
+    });
+  }
+  async createFolder(spaceId, name) {
+    return this.request(`/space/${spaceId}/folder`, {
+      method: "POST",
+      body: JSON.stringify({ name })
+    });
+  }
   async getLists(spaceId) {
     const data = await this.request(`/space/${spaceId}/list?archived=false`);
     return readCollectionField(data, "lists", "space lists");
@@ -1567,7 +1597,10 @@ function parseTimeEstimate(value) {
 }
 function buildUpdatePayload(opts) {
   const payload = {};
-  if (opts.name !== void 0) payload.name = opts.name;
+  if (opts.name !== void 0) {
+    if (!opts.name.trim()) throw new Error("Task name cannot be empty");
+    payload.name = opts.name;
+  }
   if (opts.description !== void 0) payload.markdown_content = opts.description;
   if (opts.status !== void 0) payload.status = opts.status;
   if (opts.priority !== void 0) payload.priority = parsePriority(opts.priority);
@@ -1616,6 +1649,7 @@ async function updateTask(config, taskId, options) {
 
 // src/commands/create.ts
 async function createTask(config, options) {
+  if (!options.name.trim()) throw new Error("Task name cannot be empty");
   const client = new ClickUpClient(config);
   let listId = options.list;
   if (!listId && options.parent) {
@@ -3014,6 +3048,38 @@ var commandMetadata = [
       { section: "read", usage: "folders <spaceId>", description: "List folders in a space" }
     ]
   },
+  {
+    name: "space-create",
+    description: "Create a new space in your workspace",
+    flags: ["--json"],
+    quickReference: [
+      { section: "write", usage: "space-create <name>", description: "Create a space" }
+    ]
+  },
+  {
+    name: "list-create",
+    description: "Create a new list in a space",
+    flags: ["--folder", "--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "list-create <spaceId> <name>",
+        description: "Create a list in a space"
+      }
+    ]
+  },
+  {
+    name: "folder-create",
+    description: "Create a new folder in a space",
+    flags: ["--json"],
+    quickReference: [
+      {
+        section: "write",
+        usage: "folder-create <spaceId> <name>",
+        description: "Create a folder in a space"
+      }
+    ]
+  },
   {
     name: "members",
     description: "List workspace members",
@@ -3824,6 +3890,24 @@ ${renderZshTopLevelCommands(name)}
             '--name[Filter by folder name]:text:' \\
             '--json[Force JSON output]'
           ;;
+        space-create)
+          _arguments \\
+            '1:name:' \\
+            '--json[Force JSON output]'
+          ;;
+        list-create)
+          _arguments \\
+            '1:space_id:' \\
+            '2:name:' \\
+            '--folder[Create inside a folder]:folder_id:' \\
+            '--json[Force JSON output]'
+          ;;
+        folder-create)
+          _arguments \\
+            '1:space_id:' \\
+            '2:name:' \\
+            '--json[Force JSON output]'
+          ;;
         doc-create)
           _arguments \\
             '1:title:' \\
@@ -4772,7 +4856,7 @@ function wrapAction(fn) {
   return async (...args) => {
     await fn(...args).catch((err) => {
       console.error(err instanceof Error ? err.message : String(err));
-      process.exit(1);
+      process.exitCode = 1;
     });
   };
 }
@@ -5622,6 +5706,47 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
       }
     })
   );
+  program.command("space-create <name>").description("Create a new space in your workspace").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (name, opts) => {
+      if (!name.trim()) throw new Error("Space name cannot be empty");
+      const config = loadConfig(getProfileName());
+      const client = new ClickUpClient(config);
+      const space = await client.createSpace(config.teamId, name);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(space, null, 2));
+      } else {
+        console.log(`Created space "${space.name}" (${space.id})`);
+      }
+    })
+  );
+  program.command("list-create <spaceId> <name>").description("Create a new list in a space").option("--folder <folderId>", "Create the list inside a folder").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(
+      async (spaceId, name, opts) => {
+        if (!name.trim()) throw new Error("List name cannot be empty");
+        const config = loadConfig(getProfileName());
+        const client = new ClickUpClient(config);
+        const list = opts.folder ? await client.createFolderList(opts.folder, name) : await client.createList(spaceId, name);
+        if (shouldOutputJson(opts.json ?? false)) {
+          console.log(JSON.stringify(list, null, 2));
+        } else {
+          console.log(`Created list "${list.name}" (${list.id})`);
+        }
+      }
+    )
+  );
+  program.command("folder-create <spaceId> <name>").description("Create a new folder in a space").option("--json", "Force JSON output even in terminal").action(
+    wrapAction(async (spaceId, name, opts) => {
+      if (!name.trim()) throw new Error("Folder name cannot be empty");
+      const config = loadConfig(getProfileName());
+      const client = new ClickUpClient(config);
+      const folder = await client.createFolder(spaceId, name);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(folder, null, 2));
+      } else {
+        console.log(`Created folder "${folder.name}" (${folder.id})`);
+      }
+    })
+  );
   program.command("doc-create <title>").description("Create a new doc").option("-c, --content <text>", "Initial content (markdown)").option("--json", "Force JSON output even in terminal").action(
     wrapAction(async (title, opts) => {
       const config = loadConfig(getProfileName());
@@ -5822,14 +5947,16 @@ async function run(argv = process.argv) {
 }
 process.on("SIGINT", () => {
   process.stderr.write("\nInterrupted\n");
-  process.exit(130);
+  process.exitCode = 130;
 });
-var isDirectExecution = false;
-try {
-  isDirectExecution = process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
-} catch {
-  isDirectExecution = false;
+function checkDirectExecution() {
+  try {
+    return process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
 }
+var isDirectExecution = checkDirectExecution();
 if (isDirectExecution) {
   await run();
 }

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -108,6 +108,9 @@ All commands support `--help` for full flag details. All commands support `--jso
 | `cup doc-page-edit <docId> <pageId> [--name text] [-c content]`                                                                                                                            | Edit doc page                       |
 | `cup doc-delete <docId>`                                                                                                                                                                   | Delete a doc                        |
 | `cup doc-page-delete <docId> <pageId>`                                                                                                                                                     | Delete doc page                     |
+| `cup space-create <name>`                                                                                                                                                                  | Create a space                      |
+| `cup list-create <spaceId> <name> [--folder folderId]`                                                                                                                                     | Create a list in a space or folder  |
+| `cup folder-create <spaceId> <name>`                                                                                                                                                       | Create a folder in a space          |
 | `cup tag-create <spaceId> <name> [--fg color] [--bg color]`                                                                                                                                | Create space tag                    |
 | `cup tag-update <spaceId> <tagName> --name <newName> [--fg c] [--bg c]`                                                                                                                    | Update space tag                    |
 | `cup tag-delete <spaceId> <name>`                                                                                                                                                          | Delete space tag                    |
@@ -215,6 +218,10 @@ cup doc-page-edit <docId> <pageId> -c "# Updated"
 cup spaces --name "Engineering"      # find space ID
 cup folders <spaceId>                # folders with their lists
 cup lists <spaceId>                  # lists in a space
+cup space-create "New Space"         # create a space
+cup folder-create <spaceId> "Q2"     # create a folder
+cup list-create <spaceId> "Backlog"  # create a list
+cup list-create <spaceId> "Sprint" --folder <folderId>
 cup members                          # workspace members
 cup fields <listId>                  # custom fields on a list
 cup task-types                       # custom task types