confluence-cli 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.18.0](https://github.com/pchuri/confluence-cli/compare/v1.17.0...v1.18.0) (2026-02-15)
+
+
+### Features
+
+* add content property commands (list, get, set, delete) ([#38](https://github.com/pchuri/confluence-cli/issues/38)) ([506515d](https://github.com/pchuri/confluence-cli/commit/506515dd0c271e5385ede3a49225d4b4707f225d)), closes [#37](https://github.com/pchuri/confluence-cli/issues/37)
+
 # [1.17.0](https://github.com/pchuri/confluence-cli/compare/v1.16.0...v1.17.0) (2026-02-13)
 
 

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, download, upload, or delete page attachments
+- 🏷️ **Properties** - List, get, set, and delete content properties (key-value metadata)
 - 💬 **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
@@ -181,6 +182,27 @@ confluence attachment-delete 123456789 998877
 confluence attachment-delete 123456789 998877 --yes
 ```
 
+### Content Properties
+```bash
+# List all properties on a page
+confluence property-list 123456789
+
+# Get a specific property
+confluence property-get 123456789 my-key
+
+# Set a property (creates or updates with auto-versioning)
+confluence property-set 123456789 my-key --value '{"color":"#ff0000"}'
+
+# Set a property from a JSON file
+confluence property-set 123456789 my-key --file ./property.json
+
+# Delete a property
+confluence property-delete 123456789 my-key
+
+# Skip confirmation on delete
+confluence property-delete 123456789 my-key --yes
+```
+
 ### Comments
 ```bash
 # List all comments (footer + inline)
@@ -387,6 +409,10 @@ confluence stats
 | `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` |
+| `property-list <pageId_or_url>` | List all content properties for a page | `--format <text\|json>`, `--limit <number>`, `--start <number>`, `--all` |
+| `property-get <pageId_or_url> <key>` | Get a content property by key | `--format <text\|json>` |
+| `property-set <pageId_or_url> <key>` | Set a content property (create or update) | `--value <json>`, `--file <path>`, `--format <text\|json>` |
+| `property-delete <pageId_or_url> <key>` | Delete a content property by key | `--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 | |
 

package/bin/confluence.js

@@ -597,6 +597,212 @@ program
     }
   });
 
+// Property list command
+program
+  .command('property-list <pageId>')
+  .description('List all content properties for a page')
+  .option('-f, --format <format>', 'Output format (text, json)', 'text')
+  .option('-l, --limit <limit>', 'Maximum number of properties to fetch (default: 25)')
+  .option('--start <start>', 'Start index for results (default: 0)', '0')
+  .option('--all', 'Fetch all properties (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', 'json'].includes(format)) {
+        throw new Error('Format must be one of: text, 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.');
+      }
+
+      let properties = [];
+      let nextStart = null;
+
+      if (options.all) {
+        properties = await client.getAllProperties(pageId, {
+          maxResults: limit || null,
+          start
+        });
+      } else {
+        const response = await client.listProperties(pageId, {
+          limit: limit || undefined,
+          start
+        });
+        properties = response.results;
+        nextStart = response.nextStart;
+      }
+
+      if (format === 'json') {
+        const output = { properties };
+        if (!options.all) {
+          output.nextStart = nextStart;
+        }
+        console.log(JSON.stringify(output, null, 2));
+      } else if (properties.length === 0) {
+        console.log(chalk.yellow('No properties found.'));
+      } else {
+        properties.forEach((prop, i) => {
+          const preview = JSON.stringify(prop.value);
+          const truncated = preview.length > 80 ? preview.slice(0, 77) + '...' : preview;
+          console.log(`${chalk.blue(i + 1 + '.')} ${chalk.green(prop.key)} (v${prop.version.number}): ${truncated}`);
+        });
+
+        if (!options.all && nextStart !== null && nextStart !== undefined) {
+          console.log(chalk.gray(`Next start: ${nextStart}`));
+        }
+      }
+      analytics.track('property_list', true);
+    } catch (error) {
+      analytics.track('property_list', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Property get command
+program
+  .command('property-get <pageId> <key>')
+  .description('Get a content property by key')
+  .option('-f, --format <format>', 'Output format (text, json)', 'text')
+  .action(async (pageId, key, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+
+      const format = (options.format || 'text').toLowerCase();
+      if (!['text', 'json'].includes(format)) {
+        throw new Error('Format must be one of: text, json');
+      }
+
+      const property = await client.getProperty(pageId, key);
+
+      if (format === 'json') {
+        console.log(JSON.stringify(property, null, 2));
+      } else {
+        console.log(`${chalk.green('Key:')} ${property.key}`);
+        console.log(`${chalk.green('Version:')} ${property.version.number}`);
+        console.log(`${chalk.green('Value:')}`);
+        console.log(JSON.stringify(property.value, null, 2));
+      }
+      analytics.track('property_get', true);
+    } catch (error) {
+      analytics.track('property_get', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Property set command
+program
+  .command('property-set <pageId> <key>')
+  .description('Set a content property (create or update)')
+  .option('-v, --value <json>', 'Property value as JSON')
+  .option('--file <file>', 'Read property value from a JSON file')
+  .option('-f, --format <format>', 'Output format (text, json)', 'text')
+  .action(async (pageId, key, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+
+      if (!options.value && !options.file) {
+        throw new Error('Provide a value with --value or --file.');
+      }
+
+      let value;
+      if (options.file) {
+        const fs = require('fs');
+        const raw = fs.readFileSync(options.file, 'utf-8');
+        try {
+          value = JSON.parse(raw);
+        } catch {
+          throw new Error(`Invalid JSON in file ${options.file}`);
+        }
+      } else {
+        try {
+          value = JSON.parse(options.value);
+        } catch {
+          throw new Error('Invalid JSON in --value');
+        }
+      }
+
+      const format = (options.format || 'text').toLowerCase();
+      if (!['text', 'json'].includes(format)) {
+        throw new Error('Format must be one of: text, json');
+      }
+
+      const result = await client.setProperty(pageId, key, value);
+
+      if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(chalk.green('✅ Property set successfully!'));
+        console.log(`${chalk.green('Key:')} ${result.key}`);
+        console.log(`${chalk.green('Version:')} ${result.version.number}`);
+        console.log(`${chalk.green('Value:')}`);
+        console.log(JSON.stringify(result.value, null, 2));
+      }
+      analytics.track('property_set', true);
+    } catch (error) {
+      analytics.track('property_set', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Property delete command
+program
+  .command('property-delete <pageId> <key>')
+  .description('Delete a content property by key')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(async (pageId, key, 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 property "${key}" from page ${pageId}?`
+          }
+        ]);
+
+        if (!confirmed) {
+          console.log(chalk.yellow('Cancelled.'));
+          analytics.track('property_delete_cancel', true);
+          return;
+        }
+      }
+
+      const result = await client.deleteProperty(pageId, key);
+
+      console.log(chalk.green('✅ Property deleted successfully!'));
+      console.log(`${chalk.green('Key:')} ${chalk.blue(result.key)}`);
+      console.log(`${chalk.green('Page ID:')} ${chalk.blue(result.pageId)}`);
+      analytics.track('property_delete', true);
+    } catch (error) {
+      analytics.track('property_delete', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Comments command
 program
   .command('comments <pageId>')

package/lib/confluence-client.js

@@ -872,6 +872,97 @@ class ConfluenceClient {
     return { id: String(attachmentId), pageId: String(pageId) };
   }
 
+  /**
+   * List content properties for a page with pagination support
+   */
+  async listProperties(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 response = await this.client.get(`/content/${pageId}/property`, { params });
+    const results = Array.isArray(response.data.results) ? response.data.results : [];
+
+    return {
+      results,
+      nextStart: this.parseNextStart(response.data?._links?.next)
+    };
+  }
+
+  /**
+   * Fetch all content properties for a page, honoring an optional maxResults cap
+   */
+  async getAllProperties(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 properties = [];
+
+    let hasNext = true;
+    while (hasNext) {
+      const page = await this.listProperties(pageIdOrUrl, {
+        limit: pageSize,
+        start
+      });
+      properties.push(...page.results);
+
+      if (maxResults && properties.length >= maxResults) {
+        return properties.slice(0, maxResults);
+      }
+
+      hasNext = page.nextStart !== null && page.nextStart !== undefined;
+      if (hasNext) {
+        start = page.nextStart;
+      }
+    }
+
+    return properties;
+  }
+
+  /**
+   * Get a single content property by key
+   */
+  async getProperty(pageIdOrUrl, key) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    const response = await this.client.get(`/content/${pageId}/property/${encodeURIComponent(key)}`);
+    return response.data;
+  }
+
+  /**
+   * Set (create or update) a content property
+   */
+  async setProperty(pageIdOrUrl, key, value) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    const encodedKey = encodeURIComponent(key);
+
+    let version = 1;
+    try {
+      const existing = await this.client.get(`/content/${pageId}/property/${encodedKey}`);
+      version = existing.data.version.number + 1;
+    } catch (err) {
+      if (!err.response || err.response.status !== 404) {
+        throw err;
+      }
+    }
+
+    const response = await this.client.put(`/content/${pageId}/property/${encodedKey}`, {
+      key,
+      value,
+      version: { number: version }
+    });
+    return response.data;
+  }
+
+  /**
+   * Delete a content property by key
+   */
+  async deleteProperty(pageIdOrUrl, key) {
+    const pageId = await this.extractPageId(pageIdOrUrl);
+    await this.client.delete(`/content/${pageId}/property/${encodeURIComponent(key)}`);
+    return { pageId: String(pageId), key };
+  }
+
   /**
    * Convert markdown to Confluence storage format
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "1.17.0",
+  "version": "1.18.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

@@ -718,4 +718,224 @@ describe('ConfluenceClient', () => {
       mock.restore();
     });
   });
+
+  describe('content properties', () => {
+    test('should have required methods for property handling', () => {
+      expect(typeof client.listProperties).toBe('function');
+      expect(typeof client.getProperty).toBe('function');
+      expect(typeof client.setProperty).toBe('function');
+      expect(typeof client.deleteProperty).toBe('function');
+    });
+
+    test('listProperties should return results with pagination info', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property').reply(200, {
+        results: [
+          { key: 'color', value: { hex: '#ff0000' }, version: { number: 1 } },
+          { key: 'status', value: 'active', version: { number: 3 } }
+        ],
+        _links: { next: '/rest/api/content/123/property?start=2&limit=25' }
+      });
+
+      const response = await client.listProperties('123');
+      expect(response.results).toHaveLength(2);
+      expect(response.results[0].key).toBe('color');
+      expect(response.results[1].key).toBe('status');
+      expect(response.nextStart).toBe(2);
+
+      mock.restore();
+    });
+
+    test('listProperties should return empty results when no properties exist', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/456/property').reply(200, { results: [] });
+
+      const response = await client.listProperties('456');
+      expect(response.results).toEqual([]);
+      expect(response.nextStart).toBeNull();
+
+      mock.restore();
+    });
+
+    test('listProperties should resolve page URLs', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/789/property').reply(200, { results: [] });
+
+      const response = await client.listProperties('https://test.atlassian.net/wiki/viewpage.action?pageId=789');
+      expect(response.results).toEqual([]);
+
+      mock.restore();
+    });
+
+    test('listProperties should pass limit and start as query params', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property').reply((config) => {
+        expect(config.params.limit).toBe(5);
+        expect(config.params.start).toBe(10);
+        return [200, { results: [] }];
+      });
+
+      await client.listProperties('123', { limit: 5, start: 10 });
+
+      mock.restore();
+    });
+
+    test('getAllProperties should accumulate results across pages', async () => {
+      const mock = new MockAdapter(client.client);
+      let callCount = 0;
+      mock.onGet('/content/123/property').reply((config) => {
+        callCount++;
+        if (callCount === 1) {
+          expect(config.params.start).toBe(0);
+          return [200, {
+            results: [{ key: 'a', value: 1, version: { number: 1 } }],
+            _links: { next: '/rest/api/content/123/property?start=1&limit=1' }
+          }];
+        }
+        expect(config.params.start).toBe(1);
+        return [200, {
+          results: [{ key: 'b', value: 2, version: { number: 1 } }]
+        }];
+      });
+
+      const results = await client.getAllProperties('123', { pageSize: 1 });
+      expect(results).toHaveLength(2);
+      expect(results[0].key).toBe('a');
+      expect(results[1].key).toBe('b');
+
+      mock.restore();
+    });
+
+    test('getProperty should return property data', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/color').reply(200, {
+        key: 'color',
+        value: { hex: '#ff0000' },
+        version: { number: 2 }
+      });
+
+      const result = await client.getProperty('123', 'color');
+      expect(result.key).toBe('color');
+      expect(result.value.hex).toBe('#ff0000');
+
+      mock.restore();
+    });
+
+    test('getProperty should throw on 404', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/missing').reply(404, { message: 'Not found' });
+
+      await expect(client.getProperty('123', 'missing')).rejects.toThrow();
+
+      mock.restore();
+    });
+
+    test('setProperty should create new property with version 1', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/newkey').reply(404);
+      mock.onPut('/content/123/property/newkey').reply((config) => {
+        const body = JSON.parse(config.data);
+        expect(body.version.number).toBe(1);
+        expect(body.key).toBe('newkey');
+        return [200, body];
+      });
+
+      const result = await client.setProperty('123', 'newkey', { data: true });
+      expect(result.version.number).toBe(1);
+
+      mock.restore();
+    });
+
+    test('setProperty should auto-increment version for existing property', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/existing').reply(200, {
+        key: 'existing',
+        value: 'old',
+        version: { number: 5 }
+      });
+      mock.onPut('/content/123/property/existing').reply((config) => {
+        const body = JSON.parse(config.data);
+        expect(body.version.number).toBe(6);
+        return [200, body];
+      });
+
+      const result = await client.setProperty('123', 'existing', 'new');
+      expect(result.version.number).toBe(6);
+
+      mock.restore();
+    });
+
+    test('setProperty should propagate non-404 errors', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/broken').reply(500);
+
+      await expect(client.setProperty('123', 'broken', 'val')).rejects.toThrow();
+
+      mock.restore();
+    });
+
+    test('deleteProperty should call delete endpoint', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onDelete('/content/123/property/color').reply(204);
+
+      const result = await client.deleteProperty('123', 'color');
+      expect(result).toEqual({ pageId: '123', key: 'color' });
+
+      mock.restore();
+    });
+
+    test('getProperty should URL-encode keys with reserved characters', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/my%20prop%2Fkey').reply(200, {
+        key: 'my prop/key',
+        value: { ok: true },
+        version: { number: 1 }
+      });
+
+      const result = await client.getProperty('123', 'my prop/key');
+      expect(result.key).toBe('my prop/key');
+      expect(result.value.ok).toBe(true);
+
+      mock.restore();
+    });
+
+    test('setProperty should URL-encode keys with reserved characters', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/property/my%20prop%2Fkey').reply(404);
+      mock.onPut('/content/123/property/my%20prop%2Fkey').reply((config) => {
+        const body = JSON.parse(config.data);
+        expect(body.key).toBe('my prop/key');
+        expect(body.version.number).toBe(1);
+        return [200, body];
+      });
+
+      const result = await client.setProperty('123', 'my prop/key', { test: true });
+      expect(result.key).toBe('my prop/key');
+
+      mock.restore();
+    });
+
+    test('deleteProperty should URL-encode keys with reserved characters', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onDelete('/content/123/property/my%20prop%2Fkey').reply(204);
+
+      const result = await client.deleteProperty('123', 'my prop/key');
+      expect(result).toEqual({ pageId: '123', key: 'my prop/key' });
+
+      mock.restore();
+    });
+
+    test('deleteProperty should resolve page URLs', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onDelete('/content/789/property/status').reply(204);
+
+      const result = await client.deleteProperty(
+        'https://test.atlassian.net/wiki/viewpage.action?pageId=789',
+        'status'
+      );
+      expect(result).toEqual({ pageId: '789', key: 'status' });
+
+      mock.restore();
+    });
+  });
 });