confluence-cli 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.14.0](https://github.com/pchuri/confluence-cli/compare/v1.13.0...v1.14.0) (2026-02-03)
+
+
+### Features
+
+* add comments support to CLI ([d40de55](https://github.com/pchuri/confluence-cli/commit/d40de55573aa71409b3aa2743531f2a4cb5a4eda)), closes [#28](https://github.com/pchuri/confluence-cli/issues/28)
+
 # [1.13.0](https://github.com/pchuri/confluence-cli/compare/v1.12.1...v1.13.0) (2026-01-08)
 
 

package/README.md

@@ -12,6 +12,7 @@ A powerful command-line interface for Atlassian Confluence that allows you to re
 - 📝 **Update pages** - Update existing page content and titles
 - 🗑️ **Delete pages** - Delete (or move to trash) pages by ID or URL
 - 📎 **Attachments** - List or download page attachments
+- 💬 **Comments** - List, create, and delete page comments (footer or inline)
 - 📦 **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
@@ -127,6 +128,33 @@ confluence attachments 123456789 --pattern "*.png" --limit 5
 confluence attachments 123456789 --pattern "*.png" --download --dest ./downloads
 ```
 
+### Comments
+```bash
+# List all comments (footer + inline)
+confluence comments 123456789
+
+# List inline comments as markdown
+confluence comments 123456789 --location inline --format markdown
+
+# Create a footer comment
+confluence comment 123456789 --content "Looks good to me!"
+
+# Create an inline comment
+confluence comment 123456789 \
+  --location inline \
+  --content "Consider renaming this" \
+  --inline-selection "foo" \
+  --inline-original-selection "foo"
+
+# Reply to a comment
+confluence comment 123456789 --parent 998877 --content "Agree with this"
+
+# Delete a comment
+confluence comment-delete 998877
+```
+
+Inline comment creation note (Confluence Cloud): Creating inline comments requires editor-generated highlight metadata (`matchIndex`, `lastFetchTime`, `serializedHighlights`, plus the selection text). The public REST API does not provide these fields, so inline creation and inline replies can fail with a 400 unless you supply the full `--inline-properties` payload captured from the editor. Footer comments and replies are fully supported.
+
 ### Export a Page with Attachments
 ```bash
 # Export page content (markdown by default) and all attachments
@@ -284,6 +312,9 @@ confluence stats
 | `delete <pageId_or_url>` | Delete a page by ID or URL | `--yes` |
 | `edit <pageId>` | Export page content for editing | `--output <file>` |
 | `attachments <pageId_or_url>` | List or download attachments for a page | `--limit <number>`, `--pattern <glob>`, `--download`, `--dest <directory>` |
+| `comments <pageId_or_url>` | List comments for a page | `--format <text\|markdown\|json>`, `--limit <number>`, `--start <number>`, `--location <inline\|footer\|resolved>`, `--depth <root\|all>`, `--all` |
+| `comment <pageId_or_url>` | Create a comment on a page | `--content <string>`, `--file <path>`, `--format <storage\|html\|markdown>`, `--parent <commentId>`, `--location <inline\|footer>`, `--inline-selection <text>`, `--inline-original-selection <text>`, `--inline-marker-ref <ref>`, `--inline-properties <json>` |
+| `comment-delete <commentId>` | Delete a comment by ID | `--yes` |
 | `export <pageId_or_url>` | Export a page to a directory with its attachments | `--format <html\|text\|markdown>`, `--dest <directory>`, `--file <filename>`, `--attachments-dir <name>`, `--pattern <glob>`, `--referenced-only`, `--skip-attachments` |
 | `stats` | View your usage statistics | |
 
@@ -352,7 +383,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - [ ] Export pages to different formats
 - [ ] Integration with other Atlassian tools (Jira)
 - [ ] Page attachments management
-- [ ] Comments and reviews
+- [x] Comments
+- [ ] Reviews
 
 ## Support & Feedback
 

package/bin/confluence.js

@@ -29,8 +29,7 @@ program
   .action(async (pageId, options) => {
     const analytics = new Analytics();
     try {
-      const config = getConfig();
-      const client = new ConfluenceClient(config);
+      const client = new ConfluenceClient(getConfig());
       const content = await client.readPage(pageId, options.format);
       console.log(content);
       analytics.track('read', true);
@@ -48,8 +47,7 @@ program
   .action(async (pageId) => {
     const analytics = new Analytics();
     try {
-      const config = getConfig();
-      const client = new ConfluenceClient(config);
+      const client = new ConfluenceClient(getConfig());
       const info = await client.getPageInfo(pageId);
       console.log(chalk.blue('Page Information:'));
       console.log(`Title: ${chalk.green(info.title)}`);
@@ -75,8 +73,7 @@ program
   .action(async (query, options) => {
     const analytics = new Analytics();
     try {
-      const config = getConfig();
-      const client = new ConfluenceClient(config);
+      const client = new ConfluenceClient(getConfig());
       const results = await client.search(query, parseInt(options.limit));
       
       if (results.length === 0) {
@@ -466,6 +463,320 @@ program
     }
   });
 
+// Comments command
+program
+  .command('comments <pageId>')
+  .description('List comments for a page by ID or URL')
+  .option('-f, --format <format>', 'Output format (text, markdown, json)', 'text')
+  .option('-l, --limit <limit>', 'Maximum number of comments to fetch (default: 25)')
+  .option('--start <start>', 'Start index for results (default: 0)', '0')
+  .option('--location <location>', 'Filter by location (inline, footer, resolved). Comma-separated')
+  .option('--depth <depth>', 'Comment depth ("" for root only, "all")')
+  .option('--all', 'Fetch all comments (ignores pagination)')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+
+      const format = (options.format || 'text').toLowerCase();
+      if (!['text', 'markdown', 'json'].includes(format)) {
+        throw new Error('Format must be one of: text, markdown, json');
+      }
+
+      const limit = options.limit ? parseInt(options.limit, 10) : null;
+      if (options.limit && (Number.isNaN(limit) || limit <= 0)) {
+        throw new Error('Limit must be a positive number.');
+      }
+
+      const start = options.start ? parseInt(options.start, 10) : 0;
+      if (options.start && (Number.isNaN(start) || start < 0)) {
+        throw new Error('Start must be a non-negative number.');
+      }
+
+      const locationValues = parseLocationOptions(options.location);
+      const invalidLocations = locationValues.filter(value => !['inline', 'footer', 'resolved'].includes(value));
+      if (invalidLocations.length > 0) {
+        throw new Error(`Invalid location value(s): ${invalidLocations.join(', ')}`);
+      }
+      const locationParam = locationValues.length === 0
+        ? null
+        : (locationValues.length === 1 ? locationValues[0] : locationValues);
+
+      let comments = [];
+      let nextStart = null;
+
+      if (options.all) {
+        comments = await client.getAllComments(pageId, {
+          maxResults: limit || null,
+          start,
+          location: locationParam,
+          depth: options.depth
+        });
+      } else {
+        const response = await client.listComments(pageId, {
+          limit: limit || undefined,
+          start,
+          location: locationParam,
+          depth: options.depth
+        });
+        comments = response.results;
+        nextStart = response.nextStart;
+      }
+
+      if (comments.length === 0) {
+        console.log(chalk.yellow('No comments found.'));
+        analytics.track('comments', true);
+        return;
+      }
+
+      if (format === 'json') {
+        const resolvedPageId = await client.extractPageId(pageId);
+        const output = {
+          pageId: resolvedPageId,
+          commentCount: comments.length,
+          comments: comments.map(comment => ({
+            ...comment,
+            bodyStorage: comment.body,
+            bodyText: client.formatCommentBody(comment.body, 'text')
+          }))
+        };
+        if (!options.all) {
+          output.nextStart = nextStart;
+        }
+        console.log(JSON.stringify(output, null, 2));
+        analytics.track('comments', true);
+        return;
+      }
+
+      const commentTree = buildCommentTree(comments);
+      console.log(chalk.blue(`Found ${comments.length} comment${comments.length === 1 ? '' : 's'}:`));
+
+      const renderComments = (nodes, path = []) => {
+        nodes.forEach((comment, index) => {
+          const currentPath = [...path, index + 1];
+          const level = currentPath.length - 1;
+          const indent = '  '.repeat(level);
+          const branchGlyph = level > 0 ? (index === nodes.length - 1 ? '└─ ' : '├─ ') : '';
+          const headerPrefix = `${indent}${chalk.dim(branchGlyph)}`;
+          const bodyIndent = level === 0
+            ? '   '
+            : `${indent}${' '.repeat(branchGlyph.length)}`;
+
+          const isReply = Boolean(comment.parentId);
+          const location = comment.location || 'unknown';
+          const author = comment.author?.displayName || 'Unknown';
+          const createdAt = comment.createdAt || 'unknown date';
+          const metaParts = [`Created: ${createdAt}`];
+          if (comment.status) metaParts.push(`Status: ${comment.status}`);
+          if (comment.version) metaParts.push(`Version: ${comment.version}`);
+          if (!isReply && comment.resolution) metaParts.push(`Resolution: ${comment.resolution}`);
+
+          const label = isReply ? chalk.gray('[reply]') : chalk.cyan(`[${location}]`);
+          console.log(`${headerPrefix}${currentPath.join('.')}. ${chalk.green(author)} ${chalk.gray(`(ID: ${comment.id})`)} ${label}`);
+          console.log(chalk.dim(`${bodyIndent}${metaParts.join(' • ')}`));
+
+          if (!isReply) {
+            const inlineProps = comment.inlineProperties || {};
+            const selectionText = inlineProps.selection || inlineProps.originalSelection;
+            if (selectionText) {
+              const selectionLabel = inlineProps.selection ? 'Highlight' : 'Highlight (original)';
+              console.log(chalk.dim(`${bodyIndent}${selectionLabel}: ${selectionText}`));
+            }
+            if (inlineProps.markerRef) {
+              console.log(chalk.dim(`${bodyIndent}Marker ref: ${inlineProps.markerRef}`));
+            }
+          }
+
+          const body = client.formatCommentBody(comment.body, format);
+          if (body) {
+            console.log(`${bodyIndent}${chalk.yellowBright('Body:')}`);
+            console.log(formatBodyBlock(body, `${bodyIndent}  `));
+          }
+
+          if (comment.children && comment.children.length > 0) {
+            renderComments(comment.children, currentPath);
+          }
+        });
+      };
+
+      renderComments(commentTree);
+
+      if (!options.all && nextStart !== null && nextStart !== undefined) {
+        console.log(chalk.gray(`Next start: ${nextStart}`));
+      }
+
+      analytics.track('comments', true);
+    } catch (error) {
+      analytics.track('comments', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Comment creation command
+program
+  .command('comment <pageId>')
+  .description('Create a comment on a page by ID or URL (footer or inline)')
+  .option('-f, --file <file>', 'Read content from file')
+  .option('-c, --content <content>', 'Comment content as string')
+  .option('--format <format>', 'Content format (storage, html, markdown)', 'storage')
+  .option('--parent <commentId>', 'Reply to a comment by ID')
+  .option('--location <location>', 'Comment location (inline or footer)', 'footer')
+  .option('--inline-selection <text>', 'Inline selection text')
+  .option('--inline-original-selection <text>', 'Original inline selection text')
+  .option('--inline-marker-ref <ref>', 'Inline marker reference (optional)')
+  .option('--inline-properties <json>', 'Inline properties JSON (advanced)')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    let location = null;
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+
+      let content = '';
+
+      if (options.file) {
+        const fs = require('fs');
+        if (!fs.existsSync(options.file)) {
+          throw new Error(`File not found: ${options.file}`);
+        }
+        content = fs.readFileSync(options.file, 'utf8');
+      } else if (options.content) {
+        content = options.content;
+      } else {
+        throw new Error('Either --file or --content option is required');
+      }
+
+      location = (options.location || 'footer').toLowerCase();
+      if (!['inline', 'footer'].includes(location)) {
+        throw new Error('Location must be either "inline" or "footer".');
+      }
+
+      let inlineProperties = {};
+      if (options.inlineProperties) {
+        try {
+          const parsed = JSON.parse(options.inlineProperties);
+          if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Inline properties must be a JSON object.');
+          }
+          inlineProperties = { ...parsed };
+        } catch (error) {
+          throw new Error(`Invalid --inline-properties JSON: ${error.message}`);
+        }
+      }
+
+      if (options.inlineSelection) {
+        inlineProperties.selection = options.inlineSelection;
+      }
+      if (options.inlineOriginalSelection) {
+        inlineProperties.originalSelection = options.inlineOriginalSelection;
+      }
+      if (options.inlineMarkerRef) {
+        inlineProperties.markerRef = options.inlineMarkerRef;
+      }
+
+      if (Object.keys(inlineProperties).length > 0 && location !== 'inline') {
+        throw new Error('Inline properties can only be used with --location inline.');
+      }
+
+      const parentId = options.parent;
+
+      if (location === 'inline') {
+        const hasSelection = inlineProperties.selection || inlineProperties.originalSelection;
+        if (!hasSelection && !parentId) {
+          throw new Error('Inline comments require --inline-selection or --inline-original-selection when starting a new inline thread.');
+        }
+        if (hasSelection) {
+          if (!inlineProperties.originalSelection && inlineProperties.selection) {
+            inlineProperties.originalSelection = inlineProperties.selection;
+          }
+          if (!inlineProperties.markerRef) {
+            inlineProperties.markerRef = `comment-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+          }
+        }
+      }
+
+      const result = await client.createComment(pageId, content, options.format, {
+        parentId,
+        location,
+        inlineProperties: location === 'inline' ? inlineProperties : null
+      });
+
+      console.log(chalk.green('✅ Comment created successfully!'));
+      console.log(`ID: ${chalk.blue(result.id)}`);
+      if (result.container?.id) {
+        console.log(`Page ID: ${chalk.blue(result.container.id)}`);
+      }
+      if (result._links?.webui) {
+        const url = client.toAbsoluteUrl(result._links.webui);
+        console.log(`URL: ${chalk.gray(url)}`);
+      }
+
+      analytics.track('comment_create', true);
+    } catch (error) {
+      analytics.track('comment_create', false);
+      console.error(chalk.red('Error:'), error.message);
+      if (error.response?.data) {
+        const detail = typeof error.response.data === 'string'
+          ? error.response.data
+          : JSON.stringify(error.response.data, null, 2);
+        console.error(chalk.red('API response:'), detail);
+      }
+      const apiErrors = error.response?.data?.data?.errors || error.response?.data?.errors || [];
+      const errorKeys = apiErrors
+        .map((entry) => entry?.message?.key || entry?.message || entry?.key)
+        .filter(Boolean);
+      const needsInlineMeta = ['matchIndex', 'lastFetchTime', 'serializedHighlights']
+        .every((key) => errorKeys.includes(key));
+      if (location === 'inline' && needsInlineMeta) {
+        console.error(chalk.yellow('Inline comment creation requires editor highlight metadata (matchIndex, lastFetchTime, serializedHighlights).'));
+        console.error(chalk.yellow('Try replying to an existing inline comment or use footer comments instead.'));
+      }
+      process.exit(1);
+    }
+  });
+
+// Comment delete command
+program
+  .command('comment-delete <commentId>')
+  .description('Delete a comment by ID')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(async (commentId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+
+      if (!options.yes) {
+        const { confirmed } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'confirmed',
+            default: false,
+            message: `Delete comment ${commentId}?`
+          }
+        ]);
+
+        if (!confirmed) {
+          console.log(chalk.yellow('Cancelled.'));
+          analytics.track('comment_delete_cancel', true);
+          return;
+        }
+      }
+
+      const result = await client.deleteComment(commentId);
+
+      console.log(chalk.green('✅ Comment deleted successfully!'));
+      console.log(`ID: ${chalk.blue(result.id)}`);
+      analytics.track('comment_delete', true);
+    } catch (error) {
+      analytics.track('comment_delete', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Export page content with attachments
 program
   .command('export <pageId>')
@@ -584,6 +895,49 @@ function sanitizeTitle(value) {
   return cleaned || fallback;
 }
 
+function parseLocationOptions(raw) {
+  if (!raw) {
+    return [];
+  }
+  if (Array.isArray(raw)) {
+    return raw.flatMap(item => String(item).split(','))
+      .map(value => value.trim().toLowerCase())
+      .filter(Boolean);
+  }
+  return String(raw).split(',').map(value => value.trim().toLowerCase()).filter(Boolean);
+}
+
+function formatBodyBlock(text, indent = '') {
+  return text.split('\n').map(line => `${indent}${chalk.white(line)}`).join('\n');
+}
+
+function buildCommentTree(comments) {
+  const nodes = comments.map((comment, index) => ({
+    ...comment,
+    _order: index,
+    children: []
+  }));
+  const byId = new Map(nodes.map(node => [String(node.id), node]));
+  const roots = [];
+
+  nodes.forEach((node) => {
+    const parentId = node.parentId ? String(node.parentId) : null;
+    if (parentId && byId.has(parentId)) {
+      byId.get(parentId).children.push(node);
+    } else {
+      roots.push(node);
+    }
+  });
+
+  const sortNodes = (list) => {
+    list.sort((a, b) => a._order - b._order);
+    list.forEach((child) => sortNodes(child.children));
+  };
+
+  sortNodes(roots);
+  return roots;
+}
+
 // Copy page tree command
 program
   .command('copy-tree <sourcePageId> <targetParentId> [newTitle]')

package/eslint.config.js

@@ -0,0 +1,33 @@
+const util = require('util');
+const js = require('@eslint/js');
+const globals = require('globals');
+
+if (typeof global.structuredClone !== 'function') {
+  global.structuredClone = typeof util.structuredClone === 'function'
+    ? util.structuredClone
+    : (value) => JSON.parse(JSON.stringify(value));
+}
+
+module.exports = [
+  js.configs.recommended,
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2021,
+      sourceType: 'module',
+      globals: {
+        ...globals.node,
+        ...globals.jest
+      }
+    },
+    rules: {
+      indent: ['error', 2],
+      'linebreak-style': ['error', 'unix'],
+      quotes: ['error', 'single'],
+      semi: ['error', 'always'],
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', caughtErrors: 'none' }],
+      'no-console': 'off',
+      'no-process-exit': 'off'
+    }
+  }
+];

package/lib/confluence-client.js

@@ -449,6 +449,263 @@ class ConfluenceClient {
     }
   }
 
+  /**
+   * List comments for a page with pagination support
+   */
+  async listComments(pageIdOrUrl, options = {}) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    const limit = this.parsePositiveInt(options.limit, 25);
+    const start = this.parsePositiveInt(options.start, 0);
+    const params = {
+      limit,
+      start
+    };
+
+    const expand = options.expand || 'body.storage,history,version,extensions.inlineProperties,extensions.resolution,ancestors';
+    if (expand) {
+      params.expand = expand;
+    }
+
+    if (options.parentVersion !== undefined && options.parentVersion !== null) {
+      params.parentVersion = options.parentVersion;
+    }
+
+    if (options.location) {
+      params.location = options.location;
+    }
+
+    if (options.depth) {
+      params.depth = options.depth;
+    }
+
+    const paramsSerializer = (input) => {
+      const searchParams = new URLSearchParams();
+      Object.entries(input || {}).forEach(([key, value]) => {
+        if (value === undefined || value === null || value === '') {
+          return;
+        }
+        if (Array.isArray(value)) {
+          value.forEach((item) => {
+            if (item !== undefined && item !== null && item !== '') {
+              searchParams.append(key, item);
+            }
+          });
+          return;
+        }
+        searchParams.append(key, value);
+      });
+      return searchParams.toString();
+    };
+
+    const response = await this.client.get(`/content/${pageId}/child/comment`, {
+      params,
+      paramsSerializer
+    });
+    const results = Array.isArray(response.data?.results)
+      ? response.data.results.map((item) => this.normalizeComment(item))
+      : [];
+
+    return {
+      results,
+      nextStart: this.parseNextStart(response.data?._links?.next)
+    };
+  }
+
+  /**
+   * Fetch all comments for a page, honoring an optional maxResults cap
+   */
+  async getAllComments(pageIdOrUrl, options = {}) {
+    const pageSize = this.parsePositiveInt(options.pageSize || options.limit, 25);
+    const maxResults = this.parsePositiveInt(options.maxResults, null);
+    let start = this.parsePositiveInt(options.start, 0);
+    const comments = [];
+
+    let hasNext = true;
+    while (hasNext) {
+      const page = await this.listComments(pageIdOrUrl, {
+        limit: pageSize,
+        start,
+        expand: options.expand,
+        location: options.location,
+        depth: options.depth,
+        parentVersion: options.parentVersion
+      });
+      comments.push(...page.results);
+
+      if (maxResults && comments.length >= maxResults) {
+        return comments.slice(0, maxResults);
+      }
+
+      hasNext = page.nextStart !== null && page.nextStart !== undefined;
+      if (hasNext) {
+        start = page.nextStart;
+      }
+    }
+
+    return comments;
+  }
+
+  normalizeComment(raw) {
+    const history = raw?.history || {};
+    const author = history.createdBy || {};
+    const extensions = raw?.extensions || {};
+    const ancestors = Array.isArray(raw?.ancestors)
+      ? raw.ancestors.map((ancestor) => {
+        const id = ancestor?.id ?? ancestor;
+        return {
+          id: id !== undefined && id !== null ? String(id) : null,
+          type: ancestor?.type || null,
+          title: ancestor?.title || null
+        };
+      }).filter((ancestor) => ancestor.id)
+      : [];
+
+    return {
+      id: raw?.id,
+      title: raw?.title,
+      status: raw?.status,
+      body: raw?.body?.storage?.value || '',
+      author: {
+        displayName: author.displayName || author.publicName || author.username || author.userKey || author.accountId || 'Unknown',
+        accountId: author.accountId,
+        userKey: author.userKey,
+        username: author.username,
+        email: author.email
+      },
+      createdAt: history.createdDate || null,
+      version: raw?.version?.number || null,
+      location: this.getCommentLocation(extensions),
+      inlineProperties: extensions.inlineProperties || null,
+      resolution: this.getCommentResolution(extensions),
+      parentId: this.getCommentParentId(ancestors),
+      ancestors,
+      extensions
+    };
+  }
+
+  getCommentParentId(ancestors = []) {
+    if (!Array.isArray(ancestors) || ancestors.length === 0) {
+      return null;
+    }
+    const commentAncestors = ancestors.filter((ancestor) => {
+      const type = ancestor?.type ? String(ancestor.type).toLowerCase() : '';
+      return type === 'comment';
+    });
+    if (commentAncestors.length === 0) {
+      return null;
+    }
+    return commentAncestors[commentAncestors.length - 1].id || null;
+  }
+
+  getCommentLocation(extensions = {}) {
+    const location = extensions.location;
+    if (!location) {
+      return null;
+    }
+    if (typeof location === 'string') {
+      return location;
+    }
+    if (typeof location.value === 'string') {
+      return location.value;
+    }
+    if (typeof location.name === 'string') {
+      return location.name;
+    }
+    return null;
+  }
+
+  getCommentResolution(extensions = {}) {
+    const resolution = extensions.resolution;
+    if (!resolution) {
+      return null;
+    }
+    if (typeof resolution === 'string') {
+      return resolution;
+    }
+    if (typeof resolution.status === 'string') {
+      return resolution.status;
+    }
+    if (typeof resolution.value === 'string') {
+      return resolution.value;
+    }
+    return null;
+  }
+
+  formatCommentBody(storageValue, format = 'text') {
+    const value = storageValue || '';
+    if (format === 'storage' || format === 'html') {
+      return value;
+    }
+    if (format === 'markdown') {
+      return this.storageToMarkdown(value);
+    }
+
+    return convert(value, {
+      wordwrap: 80,
+      selectors: [
+        { selector: 'h1', options: { uppercase: false } },
+        { selector: 'h2', options: { uppercase: false } },
+        { selector: 'h3', options: { uppercase: false } },
+        { selector: 'table', options: { uppercaseHeaderCells: false } }
+      ]
+    });
+  }
+
+  /**
+   * Create a comment on a page
+   */
+  async createComment(pageIdOrUrl, content, format = 'storage', options = {}) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    let storageContent = content;
+
+    if (format === 'markdown') {
+      storageContent = this.markdownToStorage(content);
+    } else if (format === 'html') {
+      storageContent = this.htmlToConfluenceStorage(content);
+    }
+
+    const commentData = {
+      type: 'comment',
+      container: {
+        id: pageId,
+        type: 'page'
+      },
+      body: {
+        storage: {
+          value: storageContent,
+          representation: 'storage'
+        }
+      }
+    };
+
+    if (options.parentId) {
+      commentData.ancestors = [{ id: options.parentId }];
+    }
+
+    const extensions = {};
+    const location = options.location || (options.inlineProperties ? 'inline' : null);
+    if (location) {
+      extensions.location = location;
+    }
+    if (options.inlineProperties) {
+      extensions.inlineProperties = options.inlineProperties;
+    }
+    if (Object.keys(extensions).length > 0) {
+      commentData.extensions = extensions;
+    }
+
+    const response = await this.client.post('/content', commentData);
+    return response.data;
+  }
+
+  /**
+   * Delete a comment by ID
+   */
+  async deleteComment(commentId) {
+    await this.client.delete(`/content/${commentId}`);
+    return { id: String(commentId) };
+  }
+
   /**
    * List attachments for a page with pagination support
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "A command-line interface for Atlassian Confluence with page creation and editing capabilities",
   "main": "index.js",
   "bin": {
@@ -34,7 +34,7 @@
   "devDependencies": {
     "@types/node": "^20.10.0",
     "axios-mock-adapter": "^2.1.0",
-    "eslint": "^8.55.0",
+    "eslint": "^9.39.2",
     "jest": "^29.7.0"
   },
   "overrides": {

package/tests/confluence-client.test.js

@@ -361,6 +361,80 @@ describe('ConfluenceClient', () => {
     });
   });
 
+  describe('comments', () => {
+    test('should list comments with location filter', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/child/comment').reply(config => {
+        expect(config.params.location).toBe('inline');
+        expect(config.params.expand).toContain('body.storage');
+        expect(config.params.expand).toContain('ancestors');
+        return [200, {
+          results: [
+            {
+              id: 'c1',
+              status: 'current',
+              body: { storage: { value: '<p>Hello</p>' } },
+              history: { createdBy: { displayName: 'Ada' }, createdDate: '2025-01-01' },
+              version: { number: 1 },
+              ancestors: [{ id: 'c0', type: 'comment' }],
+              extensions: {
+                location: 'inline',
+                inlineProperties: { selection: 'Hello', originalSelection: 'Hello' },
+                resolution: { status: 'open' }
+              }
+            }
+          ],
+          _links: { next: '/rest/api/content/123/child/comment?start=2' }
+        }];
+      });
+
+      const page = await client.listComments('123', { location: 'inline' });
+      expect(page.results).toHaveLength(1);
+      expect(page.results[0].location).toBe('inline');
+      expect(page.results[0].resolution).toBe('open');
+      expect(page.results[0].parentId).toBe('c0');
+      expect(page.nextStart).toBe(2);
+
+      mock.restore();
+    });
+
+    test('should create inline comment with inline properties', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onPost('/content').reply(config => {
+        const payload = JSON.parse(config.data);
+        expect(payload.type).toBe('comment');
+        expect(payload.container.id).toBe('123');
+        expect(payload.body.storage.value).toBe('<p>Hi</p>');
+        expect(payload.ancestors[0].id).toBe('c0');
+        expect(payload.extensions.location).toBe('inline');
+        expect(payload.extensions.inlineProperties.originalSelection).toBe('Hi');
+        expect(payload.extensions.inlineProperties.markerRef).toBe('comment-1');
+        return [200, { id: 'c1', type: 'comment' }];
+      });
+
+      await client.createComment('123', '<p>Hi</p>', 'storage', {
+        parentId: 'c0',
+        location: 'inline',
+        inlineProperties: {
+          selection: 'Hi',
+          originalSelection: 'Hi',
+          markerRef: 'comment-1'
+        }
+      });
+
+      mock.restore();
+    });
+
+    test('should delete a comment by ID', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onDelete('/content/456').reply(204);
+
+      await expect(client.deleteComment('456')).resolves.toEqual({ id: '456' });
+
+      mock.restore();
+    });
+  });
+
   describe('attachments', () => {
     test('should have required methods for attachment handling', () => {
       expect(typeof client.listAttachments).toBe('function');