@krodak/clickup-cli 1.0.0 → 1.1.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.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -29,6 +29,10 @@ 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.
 
+## 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.
+
 ## Install
 
 You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)).
@@ -241,10 +245,13 @@ Status: :white_check_mark: implemented | :construction: planned | :no_entry_sign
 
 ### Docs
 
-| Feature           | Command            | Status         |
-| ----------------- | ------------------ | -------------- |
-| Search docs       | `cup docs <query>` | :construction: |
-| View page content | `cup doc <id>`     | :construction: |
+| Feature           | Command                              | Status             |
+| ----------------- | ------------------------------------ | ------------------ |
+| Search docs       | `cup docs [query]`                   | :white_check_mark: |
+| View page content | `cup doc <docId> <pageId>`           | :white_check_mark: |
+| Create doc        | `cup doc-create <title>`             | :white_check_mark: |
+| Create page       | `cup doc-page-create <docId> <name>` | :white_check_mark: |
+| Edit page         | `cup doc-page-edit <docId> <pageId>` | :white_check_mark: |
 
 ### Attachments
 
@@ -338,10 +345,6 @@ Custom ID resolution uses the `teamId` from your config, which is required (`cup
 
 **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.
 
-## 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

@@ -7,6 +7,7 @@ import { createRequire } from "module";
 
 // src/api.ts
 var BASE_URL = "https://api.clickup.com/api/v2";
+var BASE_URL_V3 = "https://api.clickup.com/api/v3";
 var MAX_PAGES = 100;
 function isCustomTaskId(id) {
   return /^[A-Z]+-\d+$/i.test(id);
@@ -56,6 +57,29 @@ var ClickUpClient = class {
     }
     return data;
   }
+  async requestV3(path, options = {}) {
+    const res = await fetch(`${BASE_URL_V3}${path}`, {
+      ...options,
+      signal: AbortSignal.timeout(3e4),
+      headers: {
+        Authorization: this.apiToken,
+        ...options.body ? { "Content-Type": "application/json" } : {},
+        ...options.headers
+      }
+    });
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new Error(`ClickUp API error ${res.status}: response was not valid JSON`);
+    }
+    if (!res.ok) {
+      const raw = data.err ?? data.error ?? data.ECODE ?? res.statusText;
+      const msg = typeof raw === "string" ? raw : JSON.stringify(raw);
+      throw new Error(`ClickUp API error ${res.status}: ${msg}`);
+    }
+    return data;
+  }
   async getMe() {
     if (this.meCache) return this.meCache;
     const data = await this.request("/user");
@@ -383,6 +407,42 @@ var ClickUpClient = class {
     }
     return data;
   }
+  async getDocs(workspaceId) {
+    const data = await this.requestV3(`/workspaces/${workspaceId}/docs`);
+    return data.docs ?? [];
+  }
+  async getDocPage(workspaceId, docId, pageId) {
+    return this.requestV3(
+      `/workspaces/${workspaceId}/docs/${docId}/pages/${pageId}?content_format=text/md`
+    );
+  }
+  async createDoc(workspaceId, title, content, parentId) {
+    const body = { title };
+    if (content) body.content = content;
+    if (parentId) {
+      body.parent_id = parentId;
+      body.parent_type = "doc";
+    }
+    return this.requestV3(`/workspaces/${workspaceId}/docs`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async createDocPage(workspaceId, docId, name, content, parentPageId) {
+    const body = { name, content_format: "text/md" };
+    if (content) body.content = content;
+    if (parentPageId) body.parent_page_id = parentPageId;
+    return this.requestV3(`/workspaces/${workspaceId}/docs/${docId}/pages`, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async editDocPage(workspaceId, docId, pageId, updates) {
+    return this.requestV3(`/workspaces/${workspaceId}/docs/${docId}/pages/${pageId}`, {
+      method: "PUT",
+      body: JSON.stringify(updates)
+    });
+  }
 };
 
 // src/config.ts
@@ -2031,7 +2091,7 @@ function bashCompletion(name) {
     cword=$COMP_CWORD
   fi
 
-  local commands="init auth tasks task update create sprint sprints subtasks comment comment-edit comment-delete comments replies reply activity lists spaces inbox assigned open search summary overdue assign depend link attach move field delete tag checklist time config completion"
+  local commands="init auth tasks task update create sprint sprints subtasks comment comment-edit comment-delete comments replies reply activity lists spaces inbox assigned open search summary overdue assign depend link attach move field delete tag checklist time docs doc doc-create doc-page-create doc-page-edit config completion"
 
   if [[ $cword -eq 1 ]]; then
     COMPREPLY=($(compgen -W "$commands --help --version" -- "$cur"))
@@ -2155,6 +2215,21 @@ function bashCompletion(name) {
     attach)
       COMPREPLY=($(compgen -f -- "$cur"))
       ;;
+    docs)
+      COMPREPLY=($(compgen -W "--json" -- "$cur"))
+      ;;
+    doc)
+      COMPREPLY=($(compgen -W "--json" -- "$cur"))
+      ;;
+    doc-create)
+      COMPREPLY=($(compgen -W "-c --content --json" -- "$cur"))
+      ;;
+    doc-page-create)
+      COMPREPLY=($(compgen -W "-c --content --parent-page --json" -- "$cur"))
+      ;;
+    doc-page-edit)
+      COMPREPLY=($(compgen -W "--name -c --content --json" -- "$cur"))
+      ;;
     config)
       if [[ $cword -eq 2 ]]; then
         COMPREPLY=($(compgen -W "get set path" -- "$cur"))
@@ -2215,6 +2290,11 @@ _${name}() {
     'reply:Reply to a comment'
     'link:Add or remove a link between two tasks'
     'attach:Upload a file attachment to a task'
+    'docs:List workspace docs'
+    'doc:View a doc page'
+    'doc-create:Create a new doc'
+    'doc-page-create:Create a page in a doc'
+    'doc-page-edit:Edit a doc page'
     'config:Manage CLI configuration'
     'completion:Output shell completion script'
   )
@@ -2537,6 +2617,39 @@ _${name}() {
             '2:file_path:_files' \\
             '--json[Force JSON output]'
           ;;
+        docs)
+          _arguments \\
+            '1:query:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc)
+          _arguments \\
+            '1:doc_id:' \\
+            '2:page_id:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc-create)
+          _arguments \\
+            '1:title:' \\
+            '(-c --content)'{-c,--content}'[Initial content]:text:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc-page-create)
+          _arguments \\
+            '1:doc_id:' \\
+            '2:name:' \\
+            '(-c --content)'{-c,--content}'[Page content]:text:' \\
+            '--parent-page[Parent page ID]:page_id:' \\
+            '--json[Force JSON output]'
+          ;;
+        doc-page-edit)
+          _arguments \\
+            '1:doc_id:' \\
+            '2:page_id:' \\
+            '--name[New page name]:text:' \\
+            '(-c --content)'{-c,--content}'[New page content]:text:' \\
+            '--json[Force JSON output]'
+          ;;
         config)
           local -a config_cmds
           config_cmds=(
@@ -2611,6 +2724,11 @@ complete -c ${name} -n __fish_use_subcommand -a replies -d 'List threaded replie
 complete -c ${name} -n __fish_use_subcommand -a reply -d 'Reply to a comment'
 complete -c ${name} -n __fish_use_subcommand -a link -d 'Add or remove a link between two tasks'
 complete -c ${name} -n __fish_use_subcommand -a attach -d 'Upload a file attachment to a task'
+complete -c ${name} -n __fish_use_subcommand -a docs -d 'List workspace docs'
+complete -c ${name} -n __fish_use_subcommand -a doc -d 'View a doc page'
+complete -c ${name} -n __fish_use_subcommand -a doc-create -d 'Create a new doc'
+complete -c ${name} -n __fish_use_subcommand -a doc-page-create -d 'Create a page in a doc'
+complete -c ${name} -n __fish_use_subcommand -a doc-page-edit -d 'Edit a doc page'
 complete -c ${name} -n __fish_use_subcommand -a config -d 'Manage CLI configuration'
 complete -c ${name} -n __fish_use_subcommand -a completion -d 'Output shell completion script'
 
@@ -2764,6 +2882,21 @@ complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l resolved -d
 complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l unresolved -d 'Mark comment as unresolved'
 complete -c ${name} -n '__fish_seen_subcommand_from comment-edit' -l json -d 'Force JSON output'
 
+complete -c ${name} -n '__fish_seen_subcommand_from docs' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc-create' -s c -l content -d 'Initial content'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-create' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-create' -s c -l content -d 'Page content'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-create' -l parent-page -d 'Parent page ID'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-create' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-edit' -l name -d 'New page name'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-edit' -s c -l content -d 'New page content'
+complete -c ${name} -n '__fish_seen_subcommand_from doc-page-edit' -l json -d 'Force JSON output'
+
 complete -c ${name} -n '__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from get set path' -a get -d 'Print a config value'
 complete -c ${name} -n '__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from get set path' -a set -d 'Set a config value'
 complete -c ${name} -n '__fish_seen_subcommand_from config; and not __fish_seen_subcommand_from get set path' -a path -d 'Print config file path'
@@ -3142,8 +3275,52 @@ async function attachFile(config, taskId, filePath) {
   return client.createTaskAttachment(taskId, filePath);
 }
 
-// src/commands/time.ts
+// src/commands/docs.ts
 import chalk7 from "chalk";
+async function listDocs(config, query) {
+  const client = new ClickUpClient(config);
+  const docs = await client.getDocs(config.teamId);
+  if (query) {
+    const lower = query.toLowerCase();
+    return docs.filter((d) => d.name.toLowerCase().includes(lower));
+  }
+  return docs;
+}
+function formatDocs(docs) {
+  if (docs.length === 0) return "No docs found";
+  return docs.map((d) => `${chalk7.bold(d.name)} ${chalk7.dim(d.id)}`).join("\n");
+}
+function formatDocsMarkdown(docs) {
+  if (docs.length === 0) return "No docs found";
+  return docs.map((d) => `- **${d.name}** (${d.id})`).join("\n");
+}
+
+// src/commands/doc.ts
+async function getDocPage(config, docId, pageId) {
+  const client = new ClickUpClient(config);
+  return client.getDocPage(config.teamId, docId, pageId);
+}
+async function createDoc(config, title, content) {
+  if (!title.trim()) throw new Error("Doc title cannot be empty");
+  const client = new ClickUpClient(config);
+  const doc = await client.createDoc(config.teamId, title, content);
+  return { id: doc.id, title: doc.name ?? title };
+}
+async function createDocPage(config, docId, name, content, parentPageId) {
+  if (!name.trim()) throw new Error("Page name cannot be empty");
+  const client = new ClickUpClient(config);
+  return client.createDocPage(config.teamId, docId, name, content, parentPageId);
+}
+async function editDocPage(config, docId, pageId, updates) {
+  if (!updates.name && !updates.content) {
+    throw new Error("Provide --name or --content to update");
+  }
+  const client = new ClickUpClient(config);
+  return client.editDocPage(config.teamId, docId, pageId, updates);
+}
+
+// src/commands/time.ts
+import chalk8 from "chalk";
 async function startTimer(config, taskId, description) {
   const client = new ClickUpClient(config);
   return client.startTimeEntry(config.teamId, taskId, description);
@@ -3179,8 +3356,8 @@ function formatTimeEntry(entry) {
   const isRunning = entry.duration < 0;
   const elapsed = isRunning ? Date.now() - Number(entry.start) : entry.duration;
   const durationStr = formatDuration(elapsed);
-  const status = isRunning ? chalk7.green("RUNNING") : "";
-  lines.push(`${chalk7.bold(taskName)} ${chalk7.dim(taskId)} ${status}`);
+  const status = isRunning ? chalk8.green("RUNNING") : "";
+  lines.push(`${chalk8.bold(taskName)} ${chalk8.dim(taskId)} ${status}`);
   lines.push(
     `  ${durationStr} - ${formatTimestamp(entry.start)}${entry.description ? ` - ${entry.description}` : ""}`
   );
@@ -3746,6 +3923,72 @@ timeCmd.command("list").description("List recent time entries (default: last 7 d
     }
   })
 );
+program.command("docs [query]").description("List workspace docs (optionally filter by name)").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (query, opts) => {
+    const config = loadConfig();
+    const docs = await listDocs(config, query);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(docs, null, 2));
+    } else if (isTTY()) {
+      console.log(formatDocs(docs));
+    } else {
+      console.log(formatDocsMarkdown(docs));
+    }
+  })
+);
+program.command("doc <docId> <pageId>").description("View a doc page").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (docId, pageId, opts) => {
+    const config = loadConfig();
+    const page = await getDocPage(config, docId, pageId);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(page, null, 2));
+    } else {
+      if (page.name) console.log(`# ${page.name}
+`);
+      console.log(page.content ?? "");
+    }
+  })
+);
+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();
+    const result = await createDoc(config, title, opts.content);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Created doc "${result.title}" (${result.id})`);
+    }
+  })
+);
+program.command("doc-page-create <docId> <name>").description("Create a page in a doc").option("-c, --content <text>", "Page content (markdown)").option("--parent-page <pageId>", "Parent page ID for nesting").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (docId, name, opts) => {
+      const config = loadConfig();
+      const page = await createDocPage(config, docId, name, opts.content, opts.parentPage);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(page, null, 2));
+      } else {
+        console.log(`Created page "${page.name}" (${page.id}) in doc ${docId}`);
+      }
+    }
+  )
+);
+program.command("doc-page-edit <docId> <pageId>").description("Edit a doc page").option("--name <text>", "New page name").option("-c, --content <text>", "New page content (markdown)").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(
+    async (docId, pageId, opts) => {
+      const config = loadConfig();
+      const page = await editDocPage(config, docId, pageId, {
+        name: opts.name,
+        content: opts.content
+      });
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify(page, null, 2));
+      } else {
+        console.log(`Updated page "${page.name}" (${page.id})`);
+      }
+    }
+  )
+);
 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

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

package/skills/clickup-cli/SKILL.md

@@ -52,6 +52,8 @@ All commands support `--help` for full flag details.
 | `cup lists <spaceId> [--name partial] [--json]`                                                     | Lists in a space (including folder lists)          |
 | `cup open <query> [--json]`                                                                         | Open task in browser by ID or name                 |
 | `cup auth [--json]`                                                                                 | Check authentication status                        |
+| `cup docs [query] [--json]`                                                                         | List workspace docs (optionally filter by name)    |
+| `cup doc <docId> <pageId> [--json]`                                                                 | View a doc page (markdown content)                 |
 
 ### Write
 
@@ -83,6 +85,9 @@ All commands support `--help` for full flag details.
 | `cup time status [--json]`                                                                                                                                                          | Show currently running timer                               |
 | `cup time log <taskId> <duration> [-d desc] [--json]`                                                                                                                               | Log manual time entry (e.g. "2h", "30m")                   |
 | `cup time list [--days n] [--task id] [--json]`                                                                                                                                     | List recent time entries                                   |
+| `cup doc-create <title> [-c content] [--json]`                                                                                                                                      | Create a new doc                                           |
+| `cup doc-page-create <docId> <name> [-c content] [--parent-page pageId] [--json]`                                                                                                   | Create a page in a doc                                     |
+| `cup doc-page-edit <docId> <pageId> [--name text] [-c content] [--json]`                                                                                                            | Edit a doc page                                            |
 | `cup config get <key>` / `cup config set <key> <value>` / `cup config path`                                                                                                         | Manage CLI config (keys: apiToken, teamId, sprintFolderId) |
 | `cup completion <shell>`                                                                                                                                                            | Shell completions (bash/zsh/fish)                          |
 
@@ -124,6 +129,11 @@ All commands support `--help` for full flag details.
 | `cup link` + custom IDs     | Both IDs must be the same type (both custom or both native). Mixing may not work                                                                                                                                                                          |
 | `cup link`                  | Link/unlink tasks (different from dependencies)                                                                                                                                                                                                           |
 | `cup attach`                | Upload files to tasks. Attachments shown in `cup task` detail view                                                                                                                                                                                        |
+| `cup docs`                  | List and search workspace docs by name                                                                                                                                                                                                                    |
+| `cup doc`                   | View a doc page content (markdown)                                                                                                                                                                                                                        |
+| `cup doc-create`            | Create a new doc with optional initial content                                                                                                                                                                                                            |
+| `cup doc-page-create`       | Create a page in a doc, optionally nested under a parent page                                                                                                                                                                                             |
+| `cup doc-page-edit`         | Edit a doc page name or content                                                                                                                                                                                                                           |
 | `cup task`                  | Shows custom fields, checklists, attachments, dependencies, and linked tasks in detail view                                                                                                                                                               |
 | `cup lists`                 | Discovers list IDs needed for `--list` and `cup create -l`                                                                                                                                                                                                |
 | Errors                      | stderr with exit code 1                                                                                                                                                                                                                                   |
@@ -195,6 +205,20 @@ cup time list --days 7                             # recent entries
 cup delete abc123def --confirm          # irreversible!
 ```
 
+### Work with docs
+
+```bash
+cup docs                                       # list all docs
+cup docs "design"                              # search docs by name
+cup doc <docId> <pageId>                       # view page content
+cup doc-create "Architecture Notes"            # create a doc
+cup doc-create "Notes" -c "# Draft"            # create with content
+cup doc-page-create <docId> "New Section"      # add page to doc
+cup doc-page-create <docId> "Sub" --parent-page <pageId>  # nested page
+cup doc-page-edit <docId> <pageId> --name "Renamed"       # rename page
+cup doc-page-edit <docId> <pageId> -c "# Updated content" # edit content
+```
+
 ### Discover workspace structure
 
 ```bash