confluence-cli 1.4.1 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.6.0](https://github.com/pchuri/confluence-cli/compare/v1.5.0...v1.6.0) (2025-09-05)
+
+
+### Features
+
+* Add copy-tree command for recursive page copying with children ([#9](https://github.com/pchuri/confluence-cli/issues/9)) ([29efa5b](https://github.com/pchuri/confluence-cli/commit/29efa5b2f8edeee1c5072ad8d7077f38f860c2ba))
+
+# [1.5.0](https://github.com/pchuri/confluence-cli/compare/v1.4.1...v1.5.0) (2025-08-13)
+
+
+### Features
+
+* Align README with implementation and fix update command ([#7](https://github.com/pchuri/confluence-cli/issues/7)) ([87f48e0](https://github.com/pchuri/confluence-cli/commit/87f48e03c6310bb9bfc7fda2930247c0d61414ec))
+
 ## [1.4.1](https://github.com/pchuri/confluence-cli/compare/v1.4.0...v1.4.1) (2025-06-30)
 
 

package/README.md

@@ -78,103 +78,114 @@ export CONFLUENCE_API_TOKEN="your-api-token"
 # Read by page ID
 confluence read 123456789
 
-# Read in HTML format
-confluence read 123456789 --format html
+# Read in markdown format
+confluence read 123456789 --format markdown
 
-# Read by URL
-confluence read "https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456789/Page+Title"
+# Read by URL (must contain pageId parameter)
+confluence read "https://your-domain.atlassian.net/wiki/viewpage.action?pageId=123456789"
 ```
 
-### Create a New Page
+### Get Page Information
 ```bash
-# Create with inline content
-confluence create "My New Page" SPACEKEY --content "This is my page content"
-
-# Create from a file
-confluence create "Documentation" SPACEKEY --file ./content.md --format markdown
-
-# Create with HTML content
-confluence create "Rich Content" SPACEKEY --file ./content.html --format html
-
-# Create with Storage format (Confluence native)
-confluence create "Advanced Page" SPACEKEY --file ./content.xml --format storage
+confluence info 123456789
 ```
 
-### Create a Child Page
+### Search Pages
 ```bash
-# Find parent page first
-confluence find "Project Documentation" --space MYTEAM
-
-# Create child page with inline content
-confluence create-child "Meeting Notes" 123456789 --content "This is a child page"
+# Basic search
+confluence search "search term"
 
-# Create child page from file
-confluence create-child "Technical Specifications" 123456789 --file ./content.md --format markdown
+# Limit results
+confluence search "search term" --limit 5
+```
 
-# Create child page with HTML content
-confluence create-child "Report Summary" 123456789 --file ./content.html --format html
+### List Spaces
+```bash
+confluence spaces
 ```
 
-### Find Pages
+### Find a Page by Title
 ```bash
 # Find page by title
 confluence find "Project Documentation"
 
-# Find page by title in specific space
+# Find page by title in a specific space
 confluence find "Project Documentation" --space MYTEAM
 ```
 
-### Update an Existing Page
+### Create a New Page
 ```bash
-# Update content only
-confluence update 123456789 --content "Updated content"
+# Create with inline content and markdown format
+confluence create "My New Page" SPACEKEY --content "**Hello** World!" --format markdown
 
-# Update content from file
-confluence update 123456789 --file ./updated-content.md --format markdown
+# Create from a file
+confluence create "Documentation" SPACEKEY --file ./content.md --format markdown
+```
 
-# Update both title and content
-confluence update 123456789 --title "New Title" --content "New content"
+### Create a Child Page
+```bash
+# Create child page with inline content
+confluence create-child "Meeting Notes" 123456789 --content "This is a child page"
 
-# Update from HTML file
-confluence update 123456789 --file ./content.html --format html
+# Create child page from a file
+confluence create-child "Tech Specs" 123456789 --file ./specs.md --format markdown
 ```
 
-### Edit Workflow
+### Copy Page Tree
 ```bash
-# Export page content for editing
-confluence edit 123456789 --output ./page-content.xml
+# Copy a page and all its children to a new location
+confluence copy-tree 123456789 987654321 "Project Docs (Copy)"
 
-# Edit the file with your preferred editor
-vim ./page-content.xml
+# Copy with maximum depth limit (only 3 levels deep)
+confluence copy-tree 123456789 987654321 --max-depth 3
 
-# Update the page with your changes
-confluence update 123456789 --file ./page-content.xml --format storage
-```
+# Exclude pages by title (supports wildcards * and ?; case-insensitive)
+confluence copy-tree 123456789 987654321 --exclude "temp*,test*,*draft*"
 
-# Read with HTML format
-confluence read 123456789 --format html
+# Control pacing and naming
+confluence copy-tree 123456789 987654321 --delay-ms 150 --copy-suffix " (Backup)"
 
-# Read by URL (with pageId parameter)
-confluence read "https://yourcompany.atlassian.net/wiki/spaces/SPACE/pages/123456789/Page+Title"
-```
+# Dry run (preview only)
+confluence copy-tree 123456789 987654321 --dry-run
 
-### Get Page Information
-```bash
-confluence info 123456789
+# Quiet mode (suppress progress output)
+confluence copy-tree 123456789 987654321 --quiet
 ```
 
-### Search Pages
+Notes:
+- Preserves the original parent-child hierarchy when copying.
+- Continues on errors: failed pages are logged and the copy proceeds.
+- Exclude patterns use simple globbing: `*` matches any sequence, `?` matches any single character, and special regex characters are treated literally.
+- Large trees may take time; the CLI applies a small delay between sibling page creations to avoid rate limits (configurable via `--delay-ms`).
+- Root title suffix defaults to ` (Copy)`; override with `--copy-suffix`. Child pages keep their original titles.
+- Use `--fail-on-error` to exit non-zero if any page fails to copy.
+
+### Update an Existing Page
 ```bash
-# Basic search
-confluence search "search term"
+# Update title only
+confluence update 123456789 --title "A Newer Title for the Page"
 
-# Limit results
-confluence search "search term" --limit 5
+# Update content only from a string
+confluence update 123456789 --content "Updated page content."
+
+# Update content from a file
+confluence update 123456789 --file ./updated-content.md --format markdown
+
+# Update both title and content
+confluence update 123456789 --title "New Title" --content "And new content"
 ```
 
-### List Spaces
+### Edit Workflow
+The `edit` and `update` commands work together to create a seamless editing workflow.
 ```bash
-confluence spaces
+# 1. Export page content to a file (in Confluence storage format)
+confluence edit 123456789 --output ./page-to-edit.xml
+
+# 2. Edit the file with your preferred editor
+vim ./page-to-edit.xml
+
+# 3. Update the page with your changes
+confluence update 123456789 --file ./page-to-edit.xml --format storage
 ```
 
 ### View Usage Statistics
@@ -185,13 +196,19 @@ confluence stats
 ## Commands
 
 | Command | Description | Options |
-|---------|-------------|---------|
-| `init` | Initialize CLI configuration | - |
-| `read <pageId>` | Read page content | `--format <html\|text>` |
-| `info <pageId>` | Get page information | - |
+|---|---|---|
+| `init` | Initialize CLI configuration | |
+| `read <pageId_or_url>` | Read page content | `--format <html\|text\|markdown>` |
+| `info <pageId_or_url>` | Get page information | |
 | `search <query>` | Search for pages | `--limit <number>` |
-| `spaces` | List all spaces | - |
-| `stats` | View your usage statistics | - |
+| `spaces` | List all available spaces | |
+| `find <title>` | Find a page by its title | `--space <spaceKey>` |
+| `create <title> <spaceKey>` | Create a new page | `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>`|
+| `create-child <title> <parentId>` | Create a child page | `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>` |
+| `copy-tree <sourcePageId> <targetParentId> [newTitle]` | Copy page tree with all children | `--max-depth <number>`, `--exclude <patterns>`, `--delay-ms <ms>`, `--copy-suffix <text>`, `--dry-run`, `--fail-on-error`, `--quiet` |
+| `update <pageId>` | Update a page's title or content | `--title <string>`, `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>` |
+| `edit <pageId>` | Export page content for editing | `--output <file>` |
+| `stats` | View your usage statistics | |
 
 ## Examples
 

package/bin/confluence.js

@@ -238,10 +238,15 @@ program
   .action(async (pageId, options) => {
     const analytics = new Analytics();
     try {
+      // Check if at least one option is provided
+      if (!options.title && !options.file && !options.content) {
+        throw new Error('At least one of --title, --file, or --content must be provided.');
+      }
+
       const config = getConfig();
       const client = new ConfluenceClient(config);
       
-      let content = '';
+      let content = null; // Use null to indicate no content change
       
       if (options.file) {
         const fs = require('fs');
@@ -251,8 +256,6 @@ program
         content = fs.readFileSync(options.file, 'utf8');
       } else if (options.content) {
         content = options.content;
-      } else {
-        throw new Error('Either --file or --content option is required');
       }
       
       const result = await client.updatePage(pageId, options.title, content, options.format);
@@ -334,4 +337,126 @@ program
     }
   });
 
+// Copy page tree command
+program
+  .command('copy-tree <sourcePageId> <targetParentId> [newTitle]')
+  .description('Copy a page and all its children to a new location')
+  .option('--max-depth <depth>', 'Maximum depth to copy (default: 10)', '10')
+  .option('--exclude <patterns>', 'Comma-separated patterns to exclude (supports wildcards)')
+  .option('--delay-ms <ms>', 'Delay between sibling creations in ms (default: 100)', '100')
+  .option('--copy-suffix <suffix>', 'Suffix for new root title (default: " (Copy)")', ' (Copy)')
+  .option('-n, --dry-run', 'Preview operations without creating pages')
+  .option('--fail-on-error', 'Exit with non-zero code if any page fails')
+  .option('-q, --quiet', 'Suppress progress output')
+  .action(async (sourcePageId, targetParentId, newTitle, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+      
+      // Parse numeric flags with safe fallbacks
+      const parsedDepth = parseInt(options.maxDepth, 10);
+      const maxDepth = Number.isNaN(parsedDepth) ? 10 : parsedDepth;
+      const parsedDelay = parseInt(options.delayMs, 10);
+      const delayMs = Number.isNaN(parsedDelay) ? 100 : parsedDelay;
+      const copySuffix = options.copySuffix ?? ' (Copy)';
+
+      console.log(chalk.blue('🚀 Starting page tree copy...'));
+      console.log(`Source: ${sourcePageId}`);
+      console.log(`Target parent: ${targetParentId}`);
+      if (newTitle) console.log(`New root title: ${newTitle}`);
+      console.log(`Max depth: ${maxDepth}`);
+      console.log(`Delay: ${delayMs} ms`);
+      if (copySuffix) console.log(`Root suffix: ${copySuffix}`);
+      console.log('');
+
+      // Parse exclude patterns
+      let excludePatterns = [];
+      if (options.exclude) {
+        excludePatterns = options.exclude.split(',').map(p => p.trim()).filter(Boolean);
+        if (excludePatterns.length > 0) {
+          console.log(chalk.yellow(`Exclude patterns: ${excludePatterns.join(', ')}`));
+        }
+      }
+
+      // Progress callback
+      const onProgress = (message) => {
+        console.log(message);
+      };
+
+      // Dry-run: compute plan without creating anything
+      if (options.dryRun) {
+        const info = await client.getPageInfo(sourcePageId);
+        const rootTitle = newTitle || `${info.title}${copySuffix}`;
+        const descendants = await client.getAllDescendantPages(sourcePageId, maxDepth);
+        const filtered = descendants.filter(p => !client.shouldExcludePage(p.title, excludePatterns));
+        console.log(chalk.yellow('Dry run: no changes will be made.'));
+        console.log(`Would create root: ${chalk.blue(rootTitle)} (under parent ${targetParentId})`);
+        console.log(`Would create ${filtered.length} child page(s)`);
+        // Show a preview list (first 50)
+        const tree = client.buildPageTree(filtered, sourcePageId);
+        const lines = [];
+        const walk = (nodes, depth = 0) => {
+          for (const n of nodes) {
+            if (lines.length >= 50) return; // limit output
+            lines.push(`${'  '.repeat(depth)}- ${n.title}`);
+            if (n.children && n.children.length) walk(n.children, depth + 1);
+          }
+        };
+        walk(tree);
+        if (lines.length) {
+          console.log('Planned children:');
+          lines.forEach(l => console.log(l));
+          if (filtered.length > lines.length) {
+            console.log(`...and ${filtered.length - lines.length} more`);
+          }
+        }
+        analytics.track('copy_tree_dry_run', true);
+        return;
+      }
+
+      // Copy the page tree
+      const result = await client.copyPageTree(
+        sourcePageId,
+        targetParentId,
+        newTitle,
+        {
+          maxDepth,
+          excludePatterns,
+          onProgress: options.quiet ? null : onProgress,
+          quiet: options.quiet,
+          delayMs,
+          copySuffix
+        }
+      );
+
+      console.log('');
+      console.log(chalk.green('✅ Page tree copy completed'));
+      console.log(`Root page: ${chalk.blue(result.rootPage.title)} (ID: ${result.rootPage.id})`);
+      console.log(`Total copied pages: ${chalk.blue(result.totalCopied)}`);
+      if (result.failures?.length) {
+        console.log(chalk.yellow(`Failures: ${result.failures.length}`));
+        result.failures.slice(0, 10).forEach(f => {
+          const reason = f.status ? `${f.status}` : '';
+          console.log(` - ${f.title} (ID: ${f.id})${reason ? `: ${reason}` : ''}`);
+        });
+        if (result.failures.length > 10) {
+          console.log(` - ...and ${result.failures.length - 10} more`);
+        }
+      }
+      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result.rootPage._links.webui}`)}`);
+      if (options.failOnError && result.failures?.length) {
+        analytics.track('copy_tree', false);
+        console.error(chalk.red('Completed with failures and --fail-on-error is set.'));
+        process.exit(1);
+      }
+      
+      analytics.track('copy_tree', true);
+    } catch (error) {
+      analytics.track('copy_tree', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/examples/copy-tree-example.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+
+# Confluence CLI - Copy Page Tree Example
+# This script shows how to copy a page and all its descendants to a new location.
+
+echo "📋 Confluence CLI - Copy Page Tree Example"
+echo "=================================================="
+
+# Prerequisites
+echo ""
+echo "📝 Prerequisites:"
+echo "- confluence CLI is set up (confluence init)"
+echo "- You have access to source and target locations"
+echo "- You have permissions to create pages"
+echo ""
+
+# Step 1: Find the source page
+echo "1️⃣ Find the source page"
+echo "=============================="
+echo ""
+echo "Method 1: Find by title"
+echo "confluence find \"Project Docs\" --space MYTEAM"
+echo ""
+echo "Method 2: Search"
+echo "confluence search \"Project\""
+echo ""
+echo "📝 Note the source page ID from the output (e.g., 123456789)"
+echo ""
+
+# Step 2: Find the target parent page
+echo "2️⃣ Find the target parent page"
+echo "========================="
+echo ""
+echo "confluence find \"Backup\" --space BACKUP"
+echo "or"
+echo "confluence find \"Archive\" --space ARCHIVE"
+echo ""
+echo "📝 Note the target parent page ID (e.g., 987654321)"
+echo ""
+
+# Step 3: Run the copy
+echo "3️⃣ Run copy"
+echo "========================"
+echo ""
+
+echo "📄 Basic: copy with all children"
+echo 'confluence copy-tree 123456789 987654321 "Project Docs (Backup)"'
+echo ""
+
+echo "📄 Depth-limited (3 levels)"
+echo 'confluence copy-tree 123456789 987654321 "Project Docs (Summary)" --max-depth 3'
+echo ""
+
+echo "📄 Exclude patterns"
+echo 'confluence copy-tree 123456789 987654321 "Project Docs (Clean)" --exclude "temp*,test*,*draft*"'
+echo ""
+
+echo "📄 Quiet mode"
+echo 'confluence copy-tree 123456789 987654321 --quiet'
+echo ""
+
+echo "📄 Control pacing and naming"
+echo 'confluence copy-tree 123456789 987654321 --delay-ms 150 --copy-suffix " (Backup)"'
+echo ""
+
+# Practical example
+echo "💡 Practical example"
+echo "================="
+echo ""
+echo "# 1. Capture source page ID"
+echo 'SOURCE_ID=$(confluence find "Project Docs" --space MYTEAM | grep "ID:" | awk "{print \$2}")'
+echo ""
+echo "# 2. Capture target parent ID"
+echo 'TARGET_ID=$(confluence find "Backup Folder" --space BACKUP | grep "ID:" | awk "{print \$2}")'
+echo ""
+echo "# 3. Run backup with date suffix"
+echo 'confluence copy-tree $SOURCE_ID $TARGET_ID "Project Docs Backup - $(date +%Y%m%d)"'
+echo ""
+
+# Advanced usage
+echo "🚀 Advanced"
+echo "============="
+echo ""
+echo "1. Large trees with progress"
+echo "   confluence copy-tree 123456789 987654321 | tee copy-log.txt"
+echo ""
+echo "2. Multiple exclude patterns"
+echo "   confluence copy-tree 123456789 987654321 --exclude \"temp*,test*,*draft*,*temp*\""
+echo ""
+echo "3. Shallow copy (only direct children)"
+echo "   confluence copy-tree 123456789 987654321 --max-depth 1"
+echo ""
+
+# Notes and tips
+echo "⚠️  Notes and tips"
+echo "=================="
+echo "- Large trees may take time to copy"
+echo "- A short delay between siblings helps avoid rate limits (tune with --delay-ms)"
+echo "- Partial copies can remain if errors occur"
+echo "- Pages without permission are skipped; run with --fail-on-error to fail the run"
+echo "- Validate links and references after copying"
+echo "- Try with a small tree first"
+echo ""
+
+echo "📊 Verify results"
+echo "================"
+echo "After completion, you can check the results:"
+echo ""
+echo "# Root page info"
+echo "confluence info [NEW_PAGE_ID]"
+echo ""
+echo "# Find copied pages"
+echo "confluence search \"Copy\" --limit 20"
+echo ""
+
+echo "✅ Example complete!"
+echo "Replace example IDs with real ones when running."

package/examples/create-child-page-example.sh

@@ -1,65 +1,67 @@
 #!/bin/bash
 
-# 실제 Project Documentation 페이지 하위에 테스트 페이지 생성 예제
-# 이 스크립트는 일반적인 Confluence 설정에서 작동합니다.
+#!/bin/bash
+
+# Create a test page under the Project Documentation page
+# This script demonstrates typical Confluence CLI usage.
 
-echo "🔍 Project Documentation 페이지 하위에 테스트 페이지 생성"
-echo "=============================================================="
+echo "🔍 Create a test page under Project Documentation"
+echo "================================================"
 
-# 1단계: 부모 페이지 찾기
+# Step 1: Find the parent page
 echo ""
-echo "1️⃣ 부모 페이지 찾기..."
-echo "실행: confluence find \"Project Documentation\" --space MYTEAM"
+echo "1️⃣ Find the parent page..."
+echo "Run: confluence find \"Project Documentation\" --space MYTEAM"
 echo ""
 
-# 실제 실행할 때는 아래 주석을 해제하세요
+# For real execution, uncomment below
 # confluence find "Project Documentation" --space MYTEAM
 
-echo "📝 위 명령어 결과에서 페이지 ID를 확인하세요 (예: 123456789)"
+echo "📝 Note the page ID from the output (e.g., 123456789)"
 echo ""
 
-# 2단계: 페이지 정보 확인
-echo "2️⃣ 페이지 정보 확인..."
-echo "실행: confluence info [페이지ID]"
-echo "예시: confluence info 123456789"
+# Step 2: Inspect page info
+echo "2️⃣ Inspect page info..."
+echo "Run: confluence info [PAGE_ID]"
+echo "Example: confluence info 123456789"
 echo ""
 
-# 3단계: 페이지 내용 읽기 (선택사항)
-echo "3️⃣ 페이지 내용 확인 (선택사항)..."
-echo "실행: confluence read [페이지ID] | head -20"
-echo "예시: confluence read 123456789 | head -20"
+# Step 3: Read page content (optional)
+echo "3️⃣ Read content (optional)..."
+echo "Run: confluence read [PAGE_ID] | head -20"
+echo "Example: confluence read 123456789 | head -20"
 echo ""
 
-# 4단계: 테스트 페이지 생성
-echo "4️⃣ 하위 테스트 페이지 생성..."
+# Step 4: Create a child test page
+echo "4️⃣ Create child test page..."
 echo ""
 
-# 간단한 텍스트 콘텐츠로 테스트 페이지 생성
-echo "📄 방법 1: 간단한 텍스트 콘텐츠로 생성"
-echo 'confluence create-child "Test Page - $(date +%Y%m%d)" [부모페이지ID] --content "이것은 CLI로 생성된 테스트 페이지입니다. 생성 시간: $(date)"'
+# Simple text content
+echo "📄 Option 1: Simple text content"
+echo 'confluence create-child "Test Page - $(date +%Y%m%d)" [PARENT_PAGE_ID] --content "This is a test page created via CLI. Created at: $(date)"'
 echo ""
 
-# 마크다운 파일에서 테스트 페이지 생성
-echo "📄 방법 2: 마크다운 파일에서 생성"
-echo "confluence create-child \"Test Documentation - $(date +%Y%m%d)\" [부모페이지ID] --file ./sample-page.md --format markdown"
+# From Markdown file
+echo "📄 Option 2: From Markdown file"
+echo "confluence create-child \"Test Documentation - $(date +%Y%m%d)\" [PARENT_PAGE_ID] --file ./sample-page.md --format markdown"
 echo ""
 
-# HTML 콘텐츠로 생성
-echo "📄 방법 3: HTML 콘텐츠로 생성"
-echo 'confluence create-child "Test HTML Page" [부모페이지ID] --content "<h1>테스트 페이지</h1><p>이것은 <strong>HTML</strong>로 작성된 테스트 페이지입니다.</p>" --format html'
+# From HTML content
+echo "📄 Option 3: From HTML content"
+echo 'confluence create-child "Test HTML Page" [PARENT_PAGE_ID] --content "<h1>Test Page</h1><p>This is a <strong>HTML</strong> example page.</p>" --format html'
 echo ""
 
-echo "💡 실제 사용 예제:"
+echo "💡 Practical example:"
 echo "=============================="
-echo "# 1. 부모 페이지 ID 찾기"
+echo "# 1. Get parent page ID"
 echo 'PARENT_ID=$(confluence find "Project Documentation" --space MYTEAM | grep "ID:" | cut -d" " -f2)'
 echo ""
-echo "# 2. 테스트 페이지 생성"
-echo 'confluence create-child "테스트 페이지 - $(date +%Y%m%d_%H%M)" $PARENT_ID --content "CLI 테스트용 페이지입니다."'
+echo "# 2. Create test page"
+echo 'confluence create-child "Test Page - $(date +%Y%m%d_%H%M)" $PARENT_ID --content "Page for CLI testing."'
 echo ""
 
-echo "⚠️  주의사항:"
-echo "- confluence CLI가 올바르게 설정되어 있어야 합니다 (confluence init)"
-echo "- 해당 Confluence 인스턴스에 대한 적절한 권한이 있어야 합니다"
-echo "- 페이지 생성 권한이 있는지 확인하세요"
-echo "- 테스트 후에는 불필요한 페이지를 정리하세요"
+echo "⚠️  Notes:"
+echo "- confluence CLI must be set up (confluence init)"
+echo "- You need appropriate permissions on the Confluence instance"
+echo "- Ensure you have page creation permission"
+echo "- Clean up test pages afterward"

package/lib/confluence-client.js

@@ -552,17 +552,28 @@ class ConfluenceClient {
    * Update an existing Confluence page
    */
   async updatePage(pageId, title, content, format = 'storage') {
-    // First, get the current page to get the version number
-    const currentPage = await this.client.get(`/content/${pageId}`);
+    // First, get the current page to get the version number and existing content
+    const currentPage = await this.client.get(`/content/${pageId}`, {
+      params: {
+        expand: 'body.storage,version,space'
+      }
+    });
     const currentVersion = currentPage.data.version.number;
 
-    let storageContent = content;
-    
-    if (format === 'markdown') {
-      storageContent = this.markdownToStorage(content);
-    } else if (format === 'html') {
-      // Convert HTML directly to storage format (no macro wrapper)
-      storageContent = content;
+    let storageContent;
+
+    if (content !== undefined && content !== null) {
+      // If new content is provided, convert it to storage format
+      if (format === 'markdown') {
+        storageContent = this.markdownToStorage(content);
+      } else if (format === 'html') {
+        storageContent = this.htmlToConfluenceStorage(content); // Using the conversion function for robustness
+      } else { // 'storage' format
+        storageContent = content;
+      }
+    } else {
+      // If no new content, use the existing content
+      storageContent = currentPage.data.body.storage.value;
     }
 
     const pageData = {
@@ -637,6 +648,246 @@ class ConfluenceClient {
       url: content._links?.webui || ''
     };
   }
+
+  /**
+   * Get child pages of a given page
+   */
+  async getChildPages(pageId, limit = 500) {
+    const response = await this.client.get(`/content/${pageId}/child/page`, {
+      params: {
+        limit: limit,
+        // Fetch lightweight payload; content fetched on-demand when copying
+        expand: 'space,version'
+      }
+    });
+
+    return response.data.results.map(page => ({
+      id: page.id,
+      title: page.title,
+      type: page.type,
+      status: page.status,
+      space: page.space,
+      version: page.version?.number || 1
+    }));
+  }
+
+  /**
+   * Get all descendant pages recursively
+   */
+  async getAllDescendantPages(pageId, maxDepth = 10, currentDepth = 0) {
+    if (currentDepth >= maxDepth) {
+      return [];
+    }
+
+    const children = await this.getChildPages(pageId);
+    // Attach parentId so we can later reconstruct hierarchy if needed
+    const childrenWithParent = children.map(child => ({ ...child, parentId: pageId }));
+    let allDescendants = [...childrenWithParent];
+
+    for (const child of children) {
+      const grandChildren = await this.getAllDescendantPages(
+        child.id, 
+        maxDepth, 
+        currentDepth + 1
+      );
+      allDescendants = allDescendants.concat(grandChildren);
+    }
+
+    return allDescendants;
+  }
+
+  /**
+   * Copy a page tree (page and all its descendants) to a new location
+   */
+  async copyPageTree(sourcePageId, targetParentId, newTitle = null, options = {}) {
+    const {
+      maxDepth = 10,
+      excludePatterns = [],
+      onProgress = null,
+      quiet = false,
+      delayMs = 100,
+      copySuffix = ' (Copy)'
+    } = options;
+
+    // Get source page information
+    const sourcePage = await this.getPageForEdit(sourcePageId);
+    const sourceInfo = await this.getPageInfo(sourcePageId);
+    
+    // Determine new title
+    const finalTitle = newTitle || `${sourcePage.title}${copySuffix}`;
+    
+    if (!quiet && onProgress) {
+      onProgress(`Copying root: ${sourcePage.title} -> ${finalTitle}`);
+    }
+
+    // Create the root copied page
+    const newRootPage = await this.createChildPage(
+      finalTitle,
+      sourceInfo.space.key,
+      targetParentId,
+      sourcePage.content,
+      'storage'
+    );
+
+    if (!quiet && onProgress) {
+      onProgress(`Root page created: ${newRootPage.title} (ID: ${newRootPage.id})`);
+    }
+
+    const result = {
+      rootPage: newRootPage,
+      copiedPages: [newRootPage],
+      failures: [],
+      totalCopied: 1,
+    };
+
+    // Precompile exclude patterns once for efficiency
+    const compiledExclude = Array.isArray(excludePatterns)
+      ? excludePatterns.filter(Boolean).map(p => this.globToRegExp(p))
+      : [];
+
+    await this.copyChildrenRecursive(
+      sourcePageId,
+      newRootPage.id,
+      0,
+      {
+        spaceKey: sourceInfo.space.key,
+        maxDepth,
+        excludePatterns,
+        compiledExclude,
+        onProgress,
+        quiet,
+        delayMs,
+      },
+      result
+    );
+
+    result.totalCopied = result.copiedPages.length;
+    return result;
+  }
+
+  /**
+   * Build a tree structure from flat array of pages
+   */
+  buildPageTree(pages, rootPageId) {
+    const pageMap = new Map();
+    const tree = [];
+
+    // Create nodes
+    pages.forEach(page => {
+      pageMap.set(page.id, { ...page, children: [] });
+    });
+
+    // Link by parentId if available; otherwise attach to root
+    pages.forEach(page => {
+      const node = pageMap.get(page.id);
+      const parentId = page.parentId;
+      if (parentId && pageMap.has(parentId)) {
+        pageMap.get(parentId).children.push(node);
+      } else if (parentId === rootPageId || !parentId) {
+        tree.push(node);
+      } else {
+        // Parent not present in the list; treat as top-level under root
+        tree.push(node);
+      }
+    });
+
+    return tree;
+  }
+
+  /**
+   * Recursively copy pages maintaining hierarchy
+   */
+  async copyChildrenRecursive(sourceParentId, targetParentId, currentDepth, opts, result) {
+    const { spaceKey, maxDepth, excludePatterns, compiledExclude = [], onProgress, quiet, delayMs = 100 } = opts || {};
+
+    if (currentDepth >= maxDepth) {
+      return;
+    }
+
+    const children = await this.getChildPages(sourceParentId);
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      const patterns = (compiledExclude && compiledExclude.length) ? compiledExclude : excludePatterns;
+      if (this.shouldExcludePage(child.title, patterns)) {
+        if (!quiet && onProgress) {
+          onProgress(`Skipped: ${child.title}`);
+        }
+        continue;
+      }
+
+      if (!quiet && onProgress) {
+        onProgress(`Copying: ${child.title}`);
+      }
+
+      try {
+        // Fetch full content to ensure complete copy
+        const fullChild = await this.getPageForEdit(child.id);
+        const newPage = await this.createChildPage(
+          fullChild.title,
+          spaceKey,
+          targetParentId,
+          fullChild.content,
+          'storage'
+        );
+
+        result.copiedPages.push(newPage);
+        if (!quiet && onProgress) {
+          onProgress(`Created: ${newPage.title} (ID: ${newPage.id})`);
+        }
+
+        // Rate limiting safety: only pause between siblings
+        if (delayMs > 0 && i < children.length - 1) {
+          await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+
+        // Recurse into this child's subtree
+        await this.copyChildrenRecursive(child.id, newPage.id, currentDepth + 1, opts, result);
+      } catch (error) {
+        if (!quiet && onProgress) {
+          const status = error?.response?.status;
+          const statusText = error?.response?.statusText;
+          const msg = status ? `${status} ${statusText || ''}`.trim() : error.message;
+          onProgress(`Failed: ${child.title} - ${msg}`);
+        }
+        result.failures.push({
+          id: child.id,
+          title: child.title,
+          error: error.message,
+          status: error?.response?.status || null
+        });
+        // Continue with other pages (do not throw)
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Convert a simple glob pattern to a safe RegExp
+   * Supports '*' → '.*' and '?' → '.', escapes other regex metacharacters.
+   */
+  globToRegExp(pattern, flags = 'i') {
+    // Escape regex special characters: . + ^ $ { } ( ) | [ ] \
+    // Note: backslash must be escaped properly in string and class contexts
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const regexPattern = escaped
+      .replace(/\*/g, '.*')
+      .replace(/\?/g, '.');
+    return new RegExp(`^${regexPattern}$`, flags);
+  }
+
+  /**
+   * Check if a page should be excluded based on patterns
+   */
+  shouldExcludePage(title, excludePatterns) {
+    if (!excludePatterns || excludePatterns.length === 0) {
+      return false;
+    }
+
+    return excludePatterns.some(pattern => {
+      if (pattern instanceof RegExp) return pattern.test(title);
+      return this.globToRegExp(pattern).test(title);
+    });
+  }
 }
 
 module.exports = ConfluenceClient;

package/llms.txt

@@ -0,0 +1,46 @@
+# Confluence CLI
+
+> A powerful command-line interface for Atlassian Confluence that allows you to read, search, and manage your Confluence content from the terminal.
+
+This CLI tool provides a comprehensive set of commands for interacting with Confluence. Key features include creating, reading, updating, and searching for pages. It supports various content formats like markdown and HTML.
+
+To get started, install the tool via npm and initialize the configuration:
+```sh
+npm install -g confluence-cli
+confluence init
+```
+
+## Documentation
+
+- [README.md](./README.md): Main documentation with installation, usage, and command reference.
+
+## Core Source Code
+
+- [bin/confluence.js](./bin/confluence.js): The main entry point for the CLI, defines commands and argument parsing.
+- [lib/confluence-client.js](./lib/confluence-client.js): The client library for interacting with the Confluence REST API.
+- [package.json](./package.json): Project metadata, dependencies, and scripts.
+
+## Recent Changes & Fixes
+
+This section summarizes recent improvements to align the codebase with its documentation and fix bugs.
+
+### `update` Command Logic and Documentation:
+- **Inconsistency:** The `README.md` suggested that updating a page's title without changing its content was possible. However, the implementation in `bin/confluence.js` incorrectly threw an error if the `--content` or `--file` flags were not provided, making title-only updates impossible.
+- **Fix:**
+    - Modified `updatePage` in `lib/confluence-client.js` to fetch and re-use existing page content if no new content is provided.
+    - Adjusted validation in `bin/confluence.js` for the `update` command to only require one of `--title`, `--content`, or `--file`.
+    - Updated `README.md` with an example of a title-only update.
+
+### Incomplete `README.md` Command Reference:
+- **Inconsistency:** The main command table in `README.md` was missing several commands (`create`, `create-child`, `update`, `edit`, `find`).
+- **Fix:** Expanded the command table in `README.md` to include all available commands.
+
+### Misleading `read` Command URL Examples:
+- **Inconsistency:** The documentation for the `read` command used "display" or "pretty" URLs, which are not supported by the `extractPageId` function.
+- **Fix:** Removed incorrect URL examples and clarified that only URLs with a `pageId` query parameter are supported.
+
+## Next Steps
+
+- Refer to [README.md](./README.md) for detailed usage instructions and advanced configuration.
+- For troubleshooting or to contribute, visit the project's GitHub repository at https://github.com/pchuri/confluence-cli.
+- If you encounter issues, open an issue or check the FAQ section in the documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "A command-line interface for Atlassian Confluence with page creation and editing capabilities",
   "main": "index.js",
   "bin": {

package/tests/confluence-client.test.js

@@ -154,4 +154,72 @@ describe('ConfluenceClient', () => {
       expect(typeof client.findPageByTitle).toBe('function');
     });
   });
+
+  describe('page tree operations', () => {
+    test('should have required methods for tree operations', () => {
+      expect(typeof client.getChildPages).toBe('function');
+      expect(typeof client.getAllDescendantPages).toBe('function');
+      expect(typeof client.copyPageTree).toBe('function');
+      expect(typeof client.buildPageTree).toBe('function');
+      expect(typeof client.shouldExcludePage).toBe('function');
+    });
+
+    test('should correctly exclude pages based on patterns', () => {
+      const patterns = ['temp*', 'test*', '*draft*'];
+
+      expect(client.shouldExcludePage('temporary document', patterns)).toBe(true);
+      expect(client.shouldExcludePage('test page', patterns)).toBe(true);
+      expect(client.shouldExcludePage('my draft page', patterns)).toBe(true);
+      expect(client.shouldExcludePage('normal document', patterns)).toBe(false);
+      expect(client.shouldExcludePage('production page', patterns)).toBe(false);
+    });
+
+    test('should handle empty exclude patterns', () => {
+      expect(client.shouldExcludePage('any page', [])).toBe(false);
+      expect(client.shouldExcludePage('any page', null)).toBe(false);
+      expect(client.shouldExcludePage('any page', undefined)).toBe(false);
+    });
+
+    test('globToRegExp should escape regex metacharacters and match case-insensitively', () => {
+      const patterns = [
+        'file.name*',   // dot should be literal
+        '[draft]?',     // brackets should be literal
+        'Plan (Q1)?',   // parentheses literal, ? wildcard
+        'DATA*SET',     // case-insensitive
+      ];
+      const rx = patterns.map(p => client.globToRegExp(p));
+      expect('file.name.v1').toMatch(rx[0]);
+      expect('filexname').not.toMatch(rx[0]);
+      expect('[draft]1').toMatch(rx[1]);
+      expect('[draft]AB').not.toMatch(rx[1]);
+      expect('Plan (Q1)A').toMatch(rx[2]);
+      expect('Plan Q1A').not.toMatch(rx[2]);
+      expect('data big set').toMatch(rx[3]);
+    });
+
+    test('buildPageTree should link children by parentId and collect orphans at root', () => {
+      const rootId = 'root';
+      const pages = [
+        { id: 'a', title: 'A', parentId: rootId },
+        { id: 'b', title: 'B', parentId: 'a' },
+        { id: 'c', title: 'C', parentId: 'missing' }, // orphan
+      ];
+      const tree = client.buildPageTree(pages, rootId);
+      // tree should contain A and C at top-level (B is child of A)
+      const topTitles = tree.map(n => n.title).sort();
+      expect(topTitles).toEqual(['A', 'C']);
+      const a = tree.find(n => n.title === 'A');
+      expect(a.children.map(n => n.title)).toEqual(['B']);
+    });
+
+    test('exclude parser should tolerate spaces and empty items', () => {
+      const raw = ' temp* , , *draft* ,,test? ';
+      const patterns = raw.split(',').map(p => p.trim()).filter(Boolean);
+      expect(patterns).toEqual(['temp*', '*draft*', 'test?']);
+      expect(client.shouldExcludePage('temp file', patterns)).toBe(true);
+      expect(client.shouldExcludePage('my draft page', patterns)).toBe(true);
+      expect(client.shouldExcludePage('test1', patterns)).toBe(true);
+      expect(client.shouldExcludePage('production', patterns)).toBe(false);
+    });
+  });
 });