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

package/README.md

@@ -232,7 +232,7 @@ Status: :white_check_mark: implemented | :construction: planned | :no_entry_sign
 | List spaces  | `cup spaces`            | :white_check_mark: |
 | List lists   | `cup lists <spaceId>`   | :white_check_mark: |
 | Check auth   | `cup auth`              | :white_check_mark: |
-| List folders | `cup folders <spaceId>` | :construction:     |
+| List folders | `cup folders <spaceId>` | :white_check_mark: |
 | List members | `cup members`           | :construction:     |
 
 ### Goals & Key Results
@@ -245,13 +245,14 @@ Status: :white_check_mark: implemented | :construction: planned | :no_entry_sign
 
 ### Docs
 
-| 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: |
+| Feature          | Command                              | Status             |
+| ---------------- | ------------------------------------ | ------------------ |
+| Search docs      | `cup docs [query]`                   | :white_check_mark: |
+| View doc / page  | `cup doc <docId> [pageId]`           | :white_check_mark: |
+| All page content | `cup doc-pages <docId>`              | :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
 

package/dist/index.js

@@ -443,6 +443,21 @@ var ClickUpClient = class {
       body: JSON.stringify(updates)
     });
   }
+  async getDoc(workspaceId, docId) {
+    return this.requestV3(`/workspaces/${workspaceId}/docs/${docId}`);
+  }
+  async getDocPageListing(workspaceId, docId) {
+    const data = await this.requestV3(
+      `/workspaces/${workspaceId}/docs/${docId}/pagelisting`
+    );
+    return data.pages ?? [];
+  }
+  async getDocPages(workspaceId, docId) {
+    const data = await this.requestV3(
+      `/workspaces/${workspaceId}/docs/${docId}/pages?content_format=text/md`
+    );
+    return data.pages ?? [];
+  }
 };
 
 // src/config.ts
@@ -2091,7 +2106,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 docs doc doc-create doc-page-create doc-page-edit 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-pages doc-page-create doc-page-edit folders config completion"
 
   if [[ $cword -eq 1 ]]; then
     COMPREPLY=($(compgen -W "$commands --help --version" -- "$cur"))
@@ -2221,6 +2236,12 @@ function bashCompletion(name) {
     doc)
       COMPREPLY=($(compgen -W "--json" -- "$cur"))
       ;;
+    doc-pages)
+      COMPREPLY=($(compgen -W "--json" -- "$cur"))
+      ;;
+    folders)
+      COMPREPLY=($(compgen -W "--name --json" -- "$cur"))
+      ;;
     doc-create)
       COMPREPLY=($(compgen -W "-c --content --json" -- "$cur"))
       ;;
@@ -2291,10 +2312,12 @@ _${name}() {
     '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:View a doc or doc page'
     'doc-create:Create a new doc'
+    'doc-pages:List all pages in a doc with content'
     'doc-page-create:Create a page in a doc'
     'doc-page-edit:Edit a doc page'
+    'folders:List folders in a space'
     'config:Manage CLI configuration'
     'completion:Output shell completion script'
   )
@@ -2628,6 +2651,17 @@ _${name}() {
             '2:page_id:' \\
             '--json[Force JSON output]'
           ;;
+        doc-pages)
+          _arguments \\
+            '1:doc_id:' \\
+            '--json[Force JSON output]'
+          ;;
+        folders)
+          _arguments \\
+            '1:space_id:' \\
+            '--name[Filter by folder name]:text:' \\
+            '--json[Force JSON output]'
+          ;;
         doc-create)
           _arguments \\
             '1:title:' \\
@@ -2725,10 +2759,12 @@ 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 -d 'View a doc or 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-pages -d 'List all pages in a doc with content'
 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 folders -d 'List folders in a space'
 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'
 
@@ -2886,6 +2922,11 @@ complete -c ${name} -n '__fish_seen_subcommand_from docs' -l json -d 'Force JSON
 
 complete -c ${name} -n '__fish_seen_subcommand_from doc' -l json -d 'Force JSON output'
 
+complete -c ${name} -n '__fish_seen_subcommand_from doc-pages' -l json -d 'Force JSON output'
+
+complete -c ${name} -n '__fish_seen_subcommand_from folders' -l name -d 'Filter by folder name'
+complete -c ${name} -n '__fish_seen_subcommand_from folders' -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'
 
@@ -3296,10 +3337,76 @@ function formatDocsMarkdown(docs) {
 }
 
 // src/commands/doc.ts
+import chalk8 from "chalk";
+async function getDocInfo(config, docId) {
+  const client = new ClickUpClient(config);
+  const [doc, pages] = await Promise.all([
+    client.getDoc(config.teamId, docId),
+    client.getDocPageListing(config.teamId, docId)
+  ]);
+  return { doc, pages };
+}
+function formatDocInfo(doc, pages, indent = 0) {
+  const lines = [];
+  if (indent === 0) {
+    lines.push(`${chalk8.bold(doc.name)} ${chalk8.dim(doc.id)}`);
+    if (pages.length === 0) {
+      lines.push("  (no pages)");
+    }
+  }
+  for (const page of pages) {
+    const prefix = "  ".repeat(indent + 1);
+    lines.push(`${prefix}${page.name} ${chalk8.dim(page.id)}`);
+    if (page.pages && page.pages.length > 0) {
+      lines.push(formatDocInfo(doc, page.pages, indent + 1));
+    }
+  }
+  return lines.join("\n");
+}
+function formatDocInfoMarkdown(doc, pages, indent = 0) {
+  const lines = [];
+  if (indent === 0) {
+    lines.push(`# ${doc.name}`);
+    lines.push(`ID: ${doc.id}`);
+    lines.push("");
+    if (pages.length === 0) {
+      lines.push("No pages.");
+      return lines.join("\n");
+    }
+    lines.push("## Pages");
+  }
+  for (const page of pages) {
+    const prefix = "  ".repeat(indent);
+    lines.push(`${prefix}- **${page.name}** (${page.id})`);
+    if (page.pages && page.pages.length > 0) {
+      lines.push(formatDocInfoMarkdown(doc, page.pages, indent + 1));
+    }
+  }
+  return lines.join("\n");
+}
 async function getDocPage(config, docId, pageId) {
   const client = new ClickUpClient(config);
   return client.getDocPage(config.teamId, docId, pageId);
 }
+async function getAllDocPages(config, docId) {
+  const client = new ClickUpClient(config);
+  return client.getDocPages(config.teamId, docId);
+}
+function formatDocPages(pages) {
+  if (pages.length === 0) return "No pages found";
+  return pages.map((p) => {
+    const header = `# ${p.name}
+`;
+    return header + (p.content ?? "");
+  }).join("\n\n---\n\n");
+}
+function formatDocPagesMarkdown(pages) {
+  if (pages.length === 0) return "No pages found";
+  return pages.map((p) => {
+    const header = `# ${p.name}`;
+    return header + "\n\n" + (p.content ?? "");
+  }).join("\n\n---\n\n");
+}
 async function createDoc(config, title, content) {
   if (!title.trim()) throw new Error("Doc title cannot be empty");
   const client = new ClickUpClient(config);
@@ -3319,8 +3426,44 @@ async function editDocPage(config, docId, pageId, updates) {
   return client.editDocPage(config.teamId, docId, pageId, updates);
 }
 
+// src/commands/folders.ts
+import chalk9 from "chalk";
+async function listFolders(config, spaceId, nameFilter) {
+  const client = new ClickUpClient(config);
+  const folders = await client.getFolders(spaceId);
+  let filtered = folders;
+  if (nameFilter) {
+    const lower = nameFilter.toLowerCase();
+    filtered = folders.filter((f) => f.name.toLowerCase().includes(lower));
+  }
+  const results = [];
+  for (const folder of filtered) {
+    const lists = await client.getFolderLists(folder.id);
+    results.push({ id: folder.id, name: folder.name, lists });
+  }
+  return results;
+}
+function formatFolders(folders) {
+  if (folders.length === 0) return "No folders found";
+  return folders.map((f) => {
+    const header = `${chalk9.bold(f.name)} ${chalk9.dim(f.id)}`;
+    if (f.lists.length === 0) return header;
+    const listLines = f.lists.map((l) => `  ${l.name} ${chalk9.dim(l.id)}`);
+    return [header, ...listLines].join("\n");
+  }).join("\n\n");
+}
+function formatFoldersMarkdown(folders) {
+  if (folders.length === 0) return "No folders found";
+  return folders.map((f) => {
+    const header = `- **${f.name}** (${f.id})`;
+    if (f.lists.length === 0) return header;
+    const listLines = f.lists.map((l) => `  - ${l.name} (${l.id})`);
+    return [header, ...listLines].join("\n");
+  }).join("\n");
+}
+
 // src/commands/time.ts
-import chalk8 from "chalk";
+import chalk10 from "chalk";
 async function startTimer(config, taskId, description) {
   const client = new ClickUpClient(config);
   return client.startTimeEntry(config.teamId, taskId, description);
@@ -3356,8 +3499,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 ? chalk8.green("RUNNING") : "";
-  lines.push(`${chalk8.bold(taskName)} ${chalk8.dim(taskId)} ${status}`);
+  const status = isRunning ? chalk10.green("RUNNING") : "";
+  lines.push(`${chalk10.bold(taskName)} ${chalk10.dim(taskId)} ${status}`);
   lines.push(
     `  ${durationStr} - ${formatTimestamp(entry.start)}${entry.description ? ` - ${entry.description}` : ""}`
   );
@@ -3936,16 +4079,53 @@ program.command("docs [query]").description("List workspace docs (optionally fil
     }
   })
 );
-program.command("doc <docId> <pageId>").description("View a doc page").option("--json", "Force JSON output even in terminal").action(
+program.command("doc <docId> [pageId]").description("View a doc (metadata + page tree) or a specific 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 (pageId) {
+      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 ?? "");
+      }
+    } else {
+      const { doc, pages } = await getDocInfo(config, docId);
+      if (shouldOutputJson(opts.json ?? false)) {
+        console.log(JSON.stringify({ ...doc, pages }, null, 2));
+      } else if (isTTY()) {
+        console.log(formatDocInfo(doc, pages));
+      } else {
+        console.log(formatDocInfoMarkdown(doc, pages));
+      }
+    }
+  })
+);
+program.command("doc-pages <docId>").description("List all pages in a doc with content").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (docId, opts) => {
+    const config = loadConfig();
+    const pages = await getAllDocPages(config, docId);
     if (shouldOutputJson(opts.json ?? false)) {
-      console.log(JSON.stringify(page, null, 2));
+      console.log(JSON.stringify(pages, null, 2));
+    } else if (isTTY()) {
+      console.log(formatDocPages(pages));
     } else {
-      if (page.name) console.log(`# ${page.name}
-`);
-      console.log(page.content ?? "");
+      console.log(formatDocPagesMarkdown(pages));
+    }
+  })
+);
+program.command("folders <spaceId>").description("List folders in a space (with their lists)").option("--name <partial>", "Filter folders by partial name match").option("--json", "Force JSON output even in terminal").action(
+  wrapAction(async (spaceId, opts) => {
+    const config = loadConfig();
+    const folders = await listFolders(config, spaceId, opts.name);
+    if (shouldOutputJson(opts.json ?? false)) {
+      console.log(JSON.stringify(folders, null, 2));
+    } else if (isTTY()) {
+      console.log(formatFolders(folders));
+    } else {
+      console.log(formatFoldersMarkdown(folders));
     }
   })
 );

package/package.json

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

package/skills/clickup-cli/SKILL.md

@@ -52,8 +52,10 @@ 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 folders <spaceId> [--name partial] [--json]`                                                   | Folders in a space (with their lists)              |
 | `cup docs [query] [--json]`                                                                         | List workspace docs (optionally filter by name)    |
-| `cup doc <docId> <pageId> [--json]`                                                                 | View a doc page (markdown content)                 |
+| `cup doc <docId> [pageId] [--json]`                                                                 | View doc metadata + page tree, or a specific page  |
+| `cup doc-pages <docId> [--json]`                                                                    | All pages in a doc with content                    |
 
 ### Write
 
@@ -129,8 +131,10 @@ 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 folders`               | List folders in a space with their contained lists                                                                                                                                                                                                        |
 | `cup docs`                  | List and search workspace docs by name                                                                                                                                                                                                                    |
-| `cup doc`                   | View a doc page content (markdown)                                                                                                                                                                                                                        |
+| `cup doc`                   | View doc metadata + page tree (no pageId), or a specific page (with pageId)                                                                                                                                                                               |
+| `cup doc-pages`             | Dump all pages in a doc with full content                                                                                                                                                                                                                 |
 | `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                                                                                                                                                                                                                           |
@@ -210,7 +214,9 @@ cup delete abc123def --confirm          # irreversible!
 ```bash
 cup docs                                       # list all docs
 cup docs "design"                              # search docs by name
+cup doc <docId>                                # doc metadata + page tree
 cup doc <docId> <pageId>                       # view page content
+cup doc-pages <docId>                          # all pages with 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
@@ -224,6 +230,8 @@ cup doc-page-edit <docId> <pageId> -c "# Updated content" # edit content
 ```bash
 cup spaces                           # all spaces
 cup spaces --name "Engineering"      # find space ID by name
+cup folders <spaceId>                # folders with their lists
+cup folders <spaceId> --name "sprint"  # filter folders by name
 cup lists <spaceId>                  # lists in a space (needs ID from cup spaces)
 cup sprints                          # all sprints across folders
 cup auth                             # verify token works