confluence-cli 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.10.0](https://github.com/pchuri/confluence-cli/compare/v1.9.0...v1.10.0) (2025-12-05)
+
+
+### Features
+
+* export page with attachments ([#18](https://github.com/pchuri/confluence-cli/issues/18)) ([bdd9da4](https://github.com/pchuri/confluence-cli/commit/bdd9da474f13a8b6f96e64836443f65f846257a2))
+
+# [1.9.0](https://github.com/pchuri/confluence-cli/compare/v1.8.0...v1.9.0) (2025-12-04)
+
+
+### Features
+
+* add attachments list and download command ([#17](https://github.com/pchuri/confluence-cli/issues/17)) ([fb3d4f8](https://github.com/pchuri/confluence-cli/commit/fb3d4f81a3926fec832a39c78f4eda3b4a22130a))
+
 # [1.8.0](https://github.com/pchuri/confluence-cli/compare/v1.7.0...v1.8.0) (2025-09-28)
 
 

package/README.md

@@ -10,6 +10,8 @@ A powerful command-line interface for Atlassian Confluence that allows you to re
 - 🏠 **List spaces** - View all available Confluence spaces
 - ✏️ **Create pages** - Create new pages with support for Markdown, HTML, or Storage format
 - 📝 **Update pages** - Update existing page content and titles
+- 📎 **Attachments** - List or download page attachments
+- 📦 **Export** - Save a page and its attachments to a local folder
 - 🛠️ **Edit workflow** - Export page content for editing and re-import
 - 🔧 **Easy setup** - Simple configuration with environment variables or interactive setup
 
@@ -107,6 +109,30 @@ confluence search "search term"
 confluence search "search term" --limit 5
 ```
 
+### List or Download Attachments
+```bash
+# List all attachments on a page
+confluence attachments 123456789
+
+# Filter by filename and limit the number returned
+confluence attachments 123456789 --pattern "*.png" --limit 5
+
+# Download matching attachments to a directory
+confluence attachments 123456789 --pattern "*.png" --download --dest ./downloads
+```
+
+### Export a Page with Attachments
+```bash
+# Export page content (markdown by default) and all attachments
+confluence export 123456789 --dest ./exports
+
+# Custom content format/filename and attachment filtering
+confluence export 123456789 --format html --file content.html --pattern "*.png"
+
+# Skip attachments if you only need the content file
+confluence export 123456789 --skip-attachments
+```
+
 ### List Spaces
 ```bash
 confluence spaces

package/bin/confluence.js

@@ -337,6 +337,191 @@ program
     }
   });
 
+// Attachments command
+program
+  .command('attachments <pageId>')
+  .description('List or download attachments for a page')
+  .option('-l, --limit <limit>', 'Maximum number of attachments to fetch (default: all)')
+  .option('-p, --pattern <glob>', 'Filter attachments by filename (e.g., "*.png")')
+  .option('-d, --download', 'Download matching attachments')
+  .option('--dest <directory>', 'Directory to save downloads (default: current directory)', '.')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+      const maxResults = options.limit ? parseInt(options.limit, 10) : null;
+      const pattern = options.pattern ? options.pattern.trim() : null;
+
+      if (options.limit && (Number.isNaN(maxResults) || maxResults <= 0)) {
+        throw new Error('Limit must be a positive number.');
+      }
+
+      const attachments = await client.getAllAttachments(pageId, { maxResults });
+      const filtered = pattern ? attachments.filter(att => client.matchesPattern(att.title, pattern)) : attachments;
+
+      if (filtered.length === 0) {
+        console.log(chalk.yellow('No attachments found.'));
+        analytics.track('attachments', true);
+        return;
+      }
+
+      console.log(chalk.blue(`Found ${filtered.length} attachment${filtered.length === 1 ? '' : 's'}:`));
+      filtered.forEach((att, index) => {
+        const sizeKb = att.fileSize ? `${Math.max(1, Math.round(att.fileSize / 1024))} KB` : 'unknown size';
+        const typeLabel = att.mediaType || 'unknown';
+        console.log(`${index + 1}. ${chalk.green(att.title)} (ID: ${att.id})`);
+        console.log(`   Type: ${chalk.gray(typeLabel)} • Size: ${chalk.gray(sizeKb)} • Version: ${chalk.gray(att.version)}`);
+      });
+
+      if (options.download) {
+        const fs = require('fs');
+        const path = require('path');
+        const destDir = path.resolve(options.dest || '.');
+        fs.mkdirSync(destDir, { recursive: true });
+
+        const uniquePathFor = (dir, filename) => {
+          const parsed = path.parse(filename);
+          let attempt = path.join(dir, filename);
+          let counter = 1;
+          while (fs.existsSync(attempt)) {
+            const suffix = ` (${counter})`;
+            const nextName = `${parsed.name}${suffix}${parsed.ext}`;
+            attempt = path.join(dir, nextName);
+            counter += 1;
+          }
+          return attempt;
+        };
+
+        const writeStream = (stream, targetPath) => new Promise((resolve, reject) => {
+          const writer = fs.createWriteStream(targetPath);
+          stream.pipe(writer);
+          stream.on('error', reject);
+          writer.on('error', reject);
+          writer.on('finish', resolve);
+        });
+
+        let downloaded = 0;
+        for (const attachment of filtered) {
+          const targetPath = uniquePathFor(destDir, attachment.title);
+          const dataStream = await client.downloadAttachment(pageId, attachment.id);
+          await writeStream(dataStream, targetPath);
+          downloaded += 1;
+          console.log(`⬇️  ${chalk.green(attachment.title)} -> ${chalk.gray(targetPath)}`);
+        }
+
+        console.log(chalk.green(`Downloaded ${downloaded} attachment${downloaded === 1 ? '' : 's'} to ${destDir}`));
+      }
+
+      analytics.track('attachments', true);
+    } catch (error) {
+      analytics.track('attachments', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Export page content with attachments
+program
+  .command('export <pageId>')
+  .description('Export a page to a directory with its attachments')
+  .option('--format <format>', 'Content format (html, text, markdown)', 'markdown')
+  .option('--dest <directory>', 'Base directory to export into', '.')
+  .option('--file <filename>', 'Content filename (default: page.<ext>)')
+  .option('--attachments-dir <name>', 'Subdirectory for attachments', 'attachments')
+  .option('--pattern <glob>', 'Filter attachments by filename (e.g., "*.png")')
+  .option('--skip-attachments', 'Do not download attachments')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+      const fs = require('fs');
+      const path = require('path');
+
+      const format = (options.format || 'markdown').toLowerCase();
+      const formatExt = { markdown: 'md', html: 'html', text: 'txt' };
+      const contentExt = formatExt[format] || 'txt';
+
+      const pageInfo = await client.getPageInfo(pageId);
+      const content = await client.readPage(pageId, format);
+
+      const baseDir = path.resolve(options.dest || '.');
+      const folderName = sanitizeTitle(pageInfo.title || 'page');
+      const exportDir = path.join(baseDir, folderName);
+      fs.mkdirSync(exportDir, { recursive: true });
+
+      const contentFile = options.file || `page.${contentExt}`;
+      const contentPath = path.join(exportDir, contentFile);
+      fs.writeFileSync(contentPath, content);
+
+      console.log(chalk.green('✅ Page exported'));
+      console.log(`Title: ${chalk.blue(pageInfo.title)}`);
+      console.log(`Content: ${chalk.gray(contentPath)}`);
+
+      if (!options.skipAttachments) {
+        const pattern = options.pattern ? options.pattern.trim() : null;
+        const attachments = await client.getAllAttachments(pageId);
+        const filtered = pattern ? attachments.filter(att => client.matchesPattern(att.title, pattern)) : attachments;
+
+        if (filtered.length === 0) {
+          console.log(chalk.yellow('No attachments to download.'));
+        } else {
+          const attachmentsDirName = options.attachmentsDir || 'attachments';
+          const attachmentsDir = path.join(exportDir, attachmentsDirName);
+          fs.mkdirSync(attachmentsDir, { recursive: true });
+
+          const uniquePathFor = (dir, filename) => {
+            const parsed = path.parse(filename);
+            let attempt = path.join(dir, filename);
+            let counter = 1;
+            while (fs.existsSync(attempt)) {
+              const suffix = ` (${counter})`;
+              const nextName = `${parsed.name}${suffix}${parsed.ext}`;
+              attempt = path.join(dir, nextName);
+              counter += 1;
+            }
+            return attempt;
+          };
+
+          const writeStream = (stream, targetPath) => new Promise((resolve, reject) => {
+            const writer = fs.createWriteStream(targetPath);
+            stream.pipe(writer);
+            stream.on('error', reject);
+            writer.on('error', reject);
+            writer.on('finish', resolve);
+          });
+
+          let downloaded = 0;
+          for (const attachment of filtered) {
+            const targetPath = uniquePathFor(attachmentsDir, attachment.title);
+            const dataStream = await client.downloadAttachment(pageId, attachment.id);
+            await writeStream(dataStream, targetPath);
+            downloaded += 1;
+            console.log(`⬇️  ${chalk.green(attachment.title)} -> ${chalk.gray(targetPath)}`);
+          }
+
+          console.log(chalk.green(`Downloaded ${downloaded} attachment${downloaded === 1 ? '' : 's'} to ${attachmentsDir}`));
+        }
+      }
+
+      analytics.track('export', true);
+    } catch (error) {
+      analytics.track('export', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+function sanitizeTitle(value) {
+  const fallback = 'page';
+  if (!value || typeof value !== 'string') {
+    return fallback;
+  }
+  const cleaned = value.replace(/[\\/:*?"<>|]/g, ' ').trim();
+  return cleaned || fallback;
+}
+
 // Copy page tree command
 program
   .command('copy-tree <sourcePageId> <targetParentId> [newTitle]')

package/lib/confluence-client.js

@@ -167,6 +167,76 @@ class ConfluenceClient {
     }));
   }
 
+  /**
+   * List attachments for a page with pagination support
+   */
+  async listAttachments(pageIdOrUrl, options = {}) {
+    const pageId = this.extractPageId(pageIdOrUrl);
+    const limit = this.parsePositiveInt(options.limit, 50);
+    const start = this.parsePositiveInt(options.start, 0);
+    const params = {
+      limit,
+      start
+    };
+
+    if (options.filename) {
+      params.filename = options.filename;
+    }
+
+    const response = await this.client.get(`/content/${pageId}/child/attachment`, { params });
+    const results = Array.isArray(response.data.results)
+      ? response.data.results.map((item) => this.normalizeAttachment(item))
+      : [];
+
+    return {
+      results,
+      nextStart: this.parseNextStart(response.data?._links?.next)
+    };
+  }
+
+  /**
+   * Fetch all attachments for a page, honoring an optional maxResults cap
+   */
+  async getAllAttachments(pageIdOrUrl, options = {}) {
+    const pageSize = this.parsePositiveInt(options.pageSize || options.limit, 50);
+    const maxResults = this.parsePositiveInt(options.maxResults, null);
+    const filename = options.filename;
+    let start = this.parsePositiveInt(options.start, 0);
+    const attachments = [];
+
+    let hasNext = true;
+    while (hasNext) {
+      const page = await this.listAttachments(pageIdOrUrl, {
+        limit: pageSize,
+        start,
+        filename
+      });
+      attachments.push(...page.results);
+
+      if (maxResults && attachments.length >= maxResults) {
+        return attachments.slice(0, maxResults);
+      }
+
+      hasNext = page.nextStart !== null && page.nextStart !== undefined;
+      if (hasNext) {
+        start = page.nextStart;
+      }
+    }
+
+    return attachments;
+  }
+
+  /**
+   * Download an attachment's data stream
+   */
+  async downloadAttachment(pageIdOrUrl, attachmentId, options = {}) {
+    const pageId = this.extractPageId(pageIdOrUrl);
+    const response = await this.client.get(`/content/${pageId}/child/attachment/${attachmentId}/data`, {
+      responseType: options.responseType || 'stream'
+    });
+    return response.data;
+  }
+
   /**
    * Convert markdown to Confluence storage format
    */
@@ -915,6 +985,65 @@ class ConfluenceClient {
       return this.globToRegExp(pattern).test(title);
     });
   }
+
+  matchesPattern(value, patterns) {
+    if (!patterns) {
+      return true;
+    }
+
+    const list = Array.isArray(patterns) ? patterns.filter(Boolean) : [patterns];
+    if (list.length === 0) {
+      return true;
+    }
+
+    return list.some((pattern) => this.globToRegExp(pattern).test(value));
+  }
+
+  normalizeAttachment(raw) {
+    return {
+      id: raw.id,
+      title: raw.title,
+      mediaType: raw.metadata?.mediaType || raw.type || '',
+      fileSize: raw.extensions?.fileSize || 0,
+      version: raw.version?.number || 1,
+      downloadLink: this.toAbsoluteUrl(raw._links?.download)
+    };
+  }
+
+  toAbsoluteUrl(pathOrUrl) {
+    if (!pathOrUrl) {
+      return null;
+    }
+
+    if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
+      return pathOrUrl;
+    }
+
+    const normalized = pathOrUrl.startsWith('/') ? pathOrUrl : `/${pathOrUrl}`;
+    return `https://${this.domain}${normalized}`;
+  }
+
+  parseNextStart(nextLink) {
+    if (!nextLink) {
+      return null;
+    }
+
+    const match = nextLink.match(/[?&]start=(\d+)/);
+    if (!match) {
+      return null;
+    }
+
+    const value = parseInt(match[1], 10);
+    return Number.isNaN(value) ? null : value;
+  }
+
+  parsePositiveInt(value, fallback) {
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+      return fallback;
+    }
+    return parsed;
+  }
 }
 
 module.exports = ConfluenceClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "A command-line interface for Atlassian Confluence with page creation and editing capabilities",
   "main": "index.js",
   "bin": {
@@ -35,6 +35,12 @@
     "eslint": "^8.55.0",
     "jest": "^29.7.0"
   },
+  "overrides": {
+    "js-yaml": "^4.1.1",
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "^3.14.2"
+    }
+  },
   "engines": {
     "node": ">=14.0.0"
   },

package/tests/confluence-client.test.js

@@ -274,4 +274,26 @@ describe('ConfluenceClient', () => {
       expect(client.shouldExcludePage('production', patterns)).toBe(false);
     });
   });
+
+  describe('attachments', () => {
+    test('should have required methods for attachment handling', () => {
+      expect(typeof client.listAttachments).toBe('function');
+      expect(typeof client.getAllAttachments).toBe('function');
+      expect(typeof client.downloadAttachment).toBe('function');
+    });
+
+    test('matchesPattern should respect glob patterns', () => {
+      expect(client.matchesPattern('report.png', '*.png')).toBe(true);
+      expect(client.matchesPattern('report.png', '*.jpg')).toBe(false);
+      expect(client.matchesPattern('report.png', ['*.jpg', 'report.*'])).toBe(true);
+      expect(client.matchesPattern('report.png', null)).toBe(true);
+      expect(client.matchesPattern('report.png', [])).toBe(true);
+    });
+
+    test('parseNextStart should read start query param when present', () => {
+      expect(client.parseNextStart('/rest/api/content/1/child/attachment?start=25')).toBe(25);
+      expect(client.parseNextStart('/rest/api/content/1/child/attachment?limit=50')).toBeNull();
+      expect(client.parseNextStart(null)).toBeNull();
+    });
+  });
 });