confluence-cli 1.18.0 → 1.20.0

package/.github/workflows/ci.yml

@@ -31,8 +31,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-    - name: Run npm audit
-      run: npm audit --audit-level moderate
+    - run: npm ci
+    - name: Run npm audit (production only)
+      run: npm audit --audit-level moderate --omit=dev
 
   publish:
     needs: [test, security]

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.20.0](https://github.com/pchuri/confluence-cli/compare/v1.19.0...v1.20.0) (2026-02-26)
+
+
+### Features
+
+* add JSON output format to attachments command ([#45](https://github.com/pchuri/confluence-cli/issues/45)) ([b512ffb](https://github.com/pchuri/confluence-cli/commit/b512ffbea6cd083879f5030c10db72cef32302c2)), closes [#44](https://github.com/pchuri/confluence-cli/issues/44)
+
+# [1.19.0](https://github.com/pchuri/confluence-cli/compare/v1.18.0...v1.19.0) (2026-02-20)
+
+
+### Features
+
+* add --cql flag to search command for raw CQL queries ([#40](https://github.com/pchuri/confluence-cli/issues/40)) ([311f5a9](https://github.com/pchuri/confluence-cli/commit/311f5a98bfd175c6b7902c55b4dd0687b2a0d8c0)), closes [#39](https://github.com/pchuri/confluence-cli/issues/39)
+
 # [1.18.0](https://github.com/pchuri/confluence-cli/compare/v1.17.0...v1.18.0) (2026-02-15)
 
 

package/README.md

@@ -68,7 +68,7 @@ npx confluence-cli
 confluence init
 ```
 
-The wizard helps you choose the right API endpoint and authentication method. It recommends `/wiki/rest/api` for Atlassian Cloud domains (e.g., `*.atlassian.net`) and `/rest/api` for self-hosted/Data Center instances, then prompts for Basic (email + token) or Bearer authentication.
+The wizard helps you choose the right API endpoint and authentication method. It recommends `/wiki/rest/api` for Atlassian Cloud domains (e.g., `*.atlassian.net`) and `/rest/api` for self-hosted/Data Center instances, then prompts for Basic (email/username + token/password) or Bearer authentication.
 
 ### Option 2: Non-interactive Setup (CLI Flags)
 
@@ -97,16 +97,16 @@ confluence init --email "user@example.com" --token "your-api-token"
 - `-d, --domain <domain>` - Confluence domain (e.g., `company.atlassian.net`)
 - `-p, --api-path <path>` - REST API path (e.g., `/wiki/rest/api`)
 - `-a, --auth-type <type>` - Authentication type: `basic` or `bearer`
-- `-e, --email <email>` - Email for basic authentication
-- `-t, --token <token>` - API token
+- `-e, --email <email>` - Email or username for basic authentication
+- `-t, --token <token>` - API token or password
 
 ⚠️ **Security note:** While flags work, storing tokens in shell history is risky. Prefer environment variables (Option 3) for production environments.
 
 ### Option 3: Environment Variables
 ```bash
 export CONFLUENCE_DOMAIN="your-domain.atlassian.net"
-export CONFLUENCE_API_TOKEN="your-api-token"
-export CONFLUENCE_EMAIL="your.email@example.com"  # required when using basic auth
+export CONFLUENCE_API_TOKEN="your-api-token"      # or password for on-premise (alias: CONFLUENCE_PASSWORD)
+export CONFLUENCE_EMAIL="your.email@example.com"  # required for basic auth (alias: CONFLUENCE_USERNAME for on-premise)
 export CONFLUENCE_API_PATH="/wiki/rest/api"         # Cloud default; use /rest/api for Server/DC
 # Optional: set to 'bearer' for self-hosted/Data Center instances
 export CONFLUENCE_AUTH_TYPE="basic"
@@ -116,11 +116,14 @@ export CONFLUENCE_AUTH_TYPE="basic"
 
 ### Getting Your API Token
 
+**Atlassian Cloud:**
 1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
 2. Click "Create API token"
 3. Give it a label (e.g., "confluence-cli")
 4. Copy the generated token
 
+**On-premise / Data Center:** Use your Confluence username and password for basic authentication.
+
 ## Usage
 
 ### Read a Page

package/bin/confluence.js

@@ -20,7 +20,7 @@ program
   .option('-d, --domain <domain>', 'Confluence domain')
   .option('-p, --api-path <path>', 'REST API path')
   .option('-a, --auth-type <type>', 'Authentication type (basic or bearer)')
-  .option('-e, --email <email>', 'Email for basic auth')
+  .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
   .action(async (options) => {
     await initConfig(options);
@@ -75,11 +75,12 @@ program
   .command('search <query>')
   .description('Search for Confluence pages')
   .option('-l, --limit <limit>', 'Limit number of results', '10')
+  .option('--cql', 'Pass query as raw CQL instead of text search')
   .action(async (query, options) => {
     const analytics = new Analytics();
     try {
       const client = new ConfluenceClient(getConfig());
-      const results = await client.search(query, parseInt(options.limit));
+      const results = await client.search(query, parseInt(options.limit), options.cql);
       
       if (results.length === 0) {
         console.log(chalk.yellow('No results found.'));
@@ -418,6 +419,7 @@ program
   .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)', '.')
+  .option('-f, --format <format>', 'Output format (text, json)', 'text')
   .action(async (pageId, options) => {
     const analytics = new Analytics();
     try {
@@ -430,22 +432,47 @@ program
         throw new Error('Limit must be a positive number.');
       }
 
+      const format = (options.format || 'text').toLowerCase();
+      if (!['text', 'json'].includes(format)) {
+        throw new Error('Format must be one of: text, json');
+      }
+
       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.'));
+        if (format === 'json') {
+          console.log(JSON.stringify({ attachmentCount: 0, attachments: [] }, null, 2));
+        } else {
+          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 (format === 'json' && !options.download) {
+        const output = {
+          attachmentCount: filtered.length,
+          attachments: filtered.map(att => ({
+            id: att.id,
+            title: att.title,
+            mediaType: att.mediaType || '',
+            fileSize: att.fileSize,
+            fileSizeFormatted: att.fileSize ? `${Math.max(1, Math.round(att.fileSize / 1024))} KB` : 'unknown size',
+            version: att.version,
+            downloadLink: att.downloadLink
+          }))
+        };
+        console.log(JSON.stringify(output, null, 2));
+      } else if (!options.download) {
+        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');
@@ -474,17 +501,28 @@ program
           writer.on('finish', resolve);
         });
 
-        let downloaded = 0;
+        const downloadResults = [];
         for (const attachment of filtered) {
           const targetPath = uniquePathFor(destDir, attachment.title);
-          // Pass the full attachment object so downloadAttachment can use downloadLink directly
           const dataStream = await client.downloadAttachment(pageId, attachment);
           await writeStream(dataStream, targetPath);
-          downloaded += 1;
-          console.log(`⬇️  ${chalk.green(attachment.title)} -> ${chalk.gray(targetPath)}`);
+          downloadResults.push({ title: attachment.title, id: attachment.id, savedTo: targetPath });
+          if (format !== 'json') {
+            console.log(`⬇️  ${chalk.green(attachment.title)} -> ${chalk.gray(targetPath)}`);
+          }
         }
 
-        console.log(chalk.green(`Downloaded ${downloaded} attachment${downloaded === 1 ? '' : 's'} to ${destDir}`));
+        if (format === 'json') {
+          const output = {
+            attachmentCount: filtered.length,
+            downloaded: downloadResults.length,
+            destination: destDir,
+            attachments: downloadResults
+          };
+          console.log(JSON.stringify(output, null, 2));
+        } else {
+          console.log(chalk.green(`Downloaded ${downloadResults.length} attachment${downloadResults.length === 1 ? '' : 's'} to ${destDir}`));
+        }
       }
 
       analytics.track('attachments', true);

package/lib/config.js

@@ -8,7 +8,7 @@ const CONFIG_DIR = path.join(os.homedir(), '.confluence-cli');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
 const AUTH_CHOICES = [
-  { name: 'Basic (email + API token)', value: 'basic' },
+  { name: 'Basic (credentials)', value: 'basic' },
   { name: 'Bearer token', value: 'bearer' }
 ];
 
@@ -91,7 +91,7 @@ const validateCliOptions = (options) => {
   // Check if basic auth is provided with email
   const normAuthType = options.authType ? normalizeAuthType(options.authType, Boolean(options.email)) : null;
   if (normAuthType === 'basic' && !options.email) {
-    errors.push('--email is required when using basic authentication');
+    errors.push('--email is required when using basic authentication (use your username for on-premise)');
   }
 
   return errors;
@@ -175,12 +175,12 @@ const promptForMissingValues = async (providedValues) => {
     questions.push({
       type: 'input',
       name: 'email',
-      message: 'Confluence email (used with API token):',
+      message: 'Email / username:',
       when: (responses) => {
         const authType = providedValues.authType || responses.authType;
         return authType === 'basic';
       },
-      validate: requiredInput('Email')
+      validate: requiredInput('Email / username')
     });
   }
 
@@ -189,8 +189,8 @@ const promptForMissingValues = async (providedValues) => {
     questions.push({
       type: 'password',
       name: 'token',
-      message: 'API Token:',
-      validate: requiredInput('API Token')
+      message: 'API token / password:',
+      validate: requiredInput('API token / password')
     });
   }
 
@@ -258,15 +258,15 @@ async function initConfig(cliOptions = {}) {
       {
         type: 'input',
         name: 'email',
-        message: 'Confluence email (used with API token):',
+        message: 'Email / username:',
         when: (responses) => responses.authType === 'basic',
-        validate: requiredInput('Email')
+        validate: requiredInput('Email / username')
       },
       {
         type: 'password',
         name: 'token',
-        message: 'API Token:',
-        validate: requiredInput('API Token')
+        message: 'API token / password:',
+        validate: requiredInput('API token / password')
       }
     ]);
 
@@ -351,8 +351,8 @@ async function initConfig(cliOptions = {}) {
 
 function getConfig() {
   const envDomain = process.env.CONFLUENCE_DOMAIN || process.env.CONFLUENCE_HOST;
-  const envToken = process.env.CONFLUENCE_API_TOKEN;
-  const envEmail = process.env.CONFLUENCE_EMAIL;
+  const envToken = process.env.CONFLUENCE_API_TOKEN || process.env.CONFLUENCE_PASSWORD;
+  const envEmail = process.env.CONFLUENCE_EMAIL || process.env.CONFLUENCE_USERNAME;
   const envAuthType = process.env.CONFLUENCE_AUTH_TYPE;
   const envApiPath = process.env.CONFLUENCE_API_PATH;
 
@@ -368,8 +368,8 @@ function getConfig() {
     }
 
     if (authType === 'basic' && !envEmail) {
-      console.error(chalk.red('❌ Basic authentication requires CONFLUENCE_EMAIL.'));
-      console.log(chalk.yellow('Set CONFLUENCE_EMAIL or switch to bearer auth by setting CONFLUENCE_AUTH_TYPE=bearer.'));
+      console.error(chalk.red('❌ Basic authentication requires CONFLUENCE_EMAIL or CONFLUENCE_USERNAME.'));
+      console.log(chalk.yellow('Set CONFLUENCE_EMAIL (or CONFLUENCE_USERNAME for on-premise) or switch to bearer auth by setting CONFLUENCE_AUTH_TYPE=bearer.'));
       process.exit(1);
     }
 
@@ -385,7 +385,7 @@ function getConfig() {
   if (!fs.existsSync(CONFIG_FILE)) {
     console.error(chalk.red('❌ No configuration found!'));
     console.log(chalk.yellow('Please run "confluence init" to set up your configuration.'));
-    console.log(chalk.gray('Or set environment variables: CONFLUENCE_DOMAIN, CONFLUENCE_API_TOKEN, CONFLUENCE_EMAIL, and optionally CONFLUENCE_API_PATH.'));
+    console.log(chalk.gray('Or set environment variables: CONFLUENCE_DOMAIN, CONFLUENCE_API_TOKEN (or CONFLUENCE_PASSWORD), CONFLUENCE_EMAIL (or CONFLUENCE_USERNAME), and optionally CONFLUENCE_API_PATH.'));
     process.exit(1);
   }
 
@@ -404,8 +404,8 @@ function getConfig() {
     }
 
     if (authType === 'basic' && !trimmedEmail) {
-      console.error(chalk.red('❌ Basic authentication requires an email address.'));
-      console.log(chalk.yellow('Please rerun "confluence init" to add your Confluence email.'));
+      console.error(chalk.red('❌ Basic authentication requires an email address or username.'));
+      console.log(chalk.yellow('Please rerun "confluence init" to add your Confluence email or username.'));
       process.exit(1);
     }
 

package/lib/confluence-client.js

@@ -42,7 +42,7 @@ class ConfluenceClient {
 
   buildBasicAuthHeader() {
     if (!this.email) {
-      throw new Error('Basic authentication requires an email address.');
+      throw new Error('Basic authentication requires an email address or username.');
     }
 
     const encodedCredentials = Buffer.from(`${this.email}:${this.token}`).toString('base64');
@@ -221,10 +221,11 @@ class ConfluenceClient {
   /**
    * Search for pages
    */
-  async search(query, limit = 10) {
+  async search(query, limit = 10, rawCql = false) {
+    const cql = rawCql ? query : `text ~ "${String(query).replace(/"/g, '\\"')}"`;
     const response = await this.client.get('/search', {
       params: {
-        cql: `text ~ "${query}"`,
+        cql,
         limit: limit
       }
     });

package/package.json

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

package/tests/config.test.js

@@ -0,0 +1,79 @@
+const { getConfig } = require('../lib/config');
+
+// Save and restore all relevant env vars around each test
+const ENV_KEYS = [
+  'CONFLUENCE_DOMAIN', 'CONFLUENCE_HOST',
+  'CONFLUENCE_API_TOKEN', 'CONFLUENCE_PASSWORD',
+  'CONFLUENCE_EMAIL', 'CONFLUENCE_USERNAME',
+  'CONFLUENCE_AUTH_TYPE', 'CONFLUENCE_API_PATH'
+];
+
+describe('getConfig env var aliases', () => {
+  const saved = {};
+
+  beforeEach(() => {
+    for (const key of ENV_KEYS) {
+      saved[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const key of ENV_KEYS) {
+      if (saved[key] !== undefined) {
+        process.env[key] = saved[key];
+      } else {
+        delete process.env[key];
+      }
+    }
+  });
+
+  test('CONFLUENCE_USERNAME is used when CONFLUENCE_EMAIL is not set', () => {
+    process.env.CONFLUENCE_DOMAIN = 'on-prem.example.com';
+    process.env.CONFLUENCE_PASSWORD = 'secret';
+    process.env.CONFLUENCE_USERNAME = 'admin';
+    process.env.CONFLUENCE_AUTH_TYPE = 'basic';
+
+    const config = getConfig();
+    expect(config.email).toBe('admin');
+    expect(config.token).toBe('secret');
+  });
+
+  test('CONFLUENCE_EMAIL takes priority over CONFLUENCE_USERNAME', () => {
+    process.env.CONFLUENCE_DOMAIN = 'cloud.atlassian.net';
+    process.env.CONFLUENCE_API_TOKEN = 'api-token';
+    process.env.CONFLUENCE_EMAIL = 'user@example.com';
+    process.env.CONFLUENCE_USERNAME = 'admin';
+    process.env.CONFLUENCE_AUTH_TYPE = 'basic';
+
+    const config = getConfig();
+    expect(config.email).toBe('user@example.com');
+  });
+
+  test('CONFLUENCE_PASSWORD is used when CONFLUENCE_API_TOKEN is not set', () => {
+    process.env.CONFLUENCE_DOMAIN = 'on-prem.example.com';
+    process.env.CONFLUENCE_PASSWORD = 'my-password';
+    process.env.CONFLUENCE_USERNAME = 'admin';
+    process.env.CONFLUENCE_AUTH_TYPE = 'basic';
+
+    const config = getConfig();
+    expect(config.token).toBe('my-password');
+  });
+
+  test('CONFLUENCE_API_TOKEN takes priority over CONFLUENCE_PASSWORD', () => {
+    process.env.CONFLUENCE_DOMAIN = 'cloud.atlassian.net';
+    process.env.CONFLUENCE_API_TOKEN = 'api-token';
+    process.env.CONFLUENCE_PASSWORD = 'password';
+
+    const config = getConfig();
+    expect(config.token).toBe('api-token');
+  });
+
+  test('CONFLUENCE_HOST alias still works for domain', () => {
+    process.env.CONFLUENCE_HOST = 'host.example.com';
+    process.env.CONFLUENCE_API_TOKEN = 'token';
+
+    const config = getConfig();
+    expect(config.domain).toBe('host.example.com');
+  });
+});

package/tests/confluence-client.test.js

@@ -97,7 +97,7 @@ describe('ConfluenceClient', () => {
         domain: 'test.atlassian.net',
         token: 'missing-email',
         authType: 'basic'
-      })).toThrow('Basic authentication requires an email address.');
+      })).toThrow('Basic authentication requires an email address or username.');
     });
   });
 
@@ -303,6 +303,68 @@ describe('ConfluenceClient', () => {
     });
   });
 
+  describe('search', () => {
+    test('should wrap query in text search by default', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/search').reply((config) => {
+        expect(config.params.cql).toBe('text ~ "architecture decisions"');
+        expect(config.params.limit).toBe(10);
+        return [200, { results: [] }];
+      });
+
+      const results = await client.search('architecture decisions');
+      expect(results).toEqual([]);
+
+      mock.restore();
+    });
+
+    test('should pass raw CQL when rawCql is true', async () => {
+      const mock = new MockAdapter(client.client);
+      const rawQuery = 'contributor = currentUser() order by lastmodified desc';
+      mock.onGet('/search').reply((config) => {
+        expect(config.params.cql).toBe(rawQuery);
+        return [200, {
+          results: [{
+            content: { id: '123', title: 'Test Page', type: 'page' },
+            excerpt: 'test excerpt'
+          }]
+        }];
+      });
+
+      const results = await client.search(rawQuery, 10, true);
+      expect(results).toHaveLength(1);
+      expect(results[0].id).toBe('123');
+      expect(results[0].title).toBe('Test Page');
+
+      mock.restore();
+    });
+
+    test('should escape double quotes in text search query', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/search').reply((config) => {
+        expect(config.params.cql).toBe('text ~ "test \\"quoted\\" term"');
+        return [200, { results: [] }];
+      });
+
+      const results = await client.search('test "quoted" term');
+      expect(results).toEqual([]);
+
+      mock.restore();
+    });
+
+    test('should respect limit parameter', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/search').reply((config) => {
+        expect(config.params.limit).toBe(5);
+        return [200, { results: [] }];
+      });
+
+      await client.search('test', 5);
+
+      mock.restore();
+    });
+  });
+
   describe('page creation and updates', () => {
     test('should have required methods for page management', () => {
       expect(typeof client.createPage).toBe('function');
@@ -709,6 +771,66 @@ describe('ConfluenceClient', () => {
       }
     });
 
+    test('normalizeAttachment should return all fields needed for JSON output', () => {
+      const raw = {
+        id: '101',
+        title: 'diagram.png',
+        metadata: { mediaType: 'image/png' },
+        extensions: { fileSize: 204800 },
+        version: { number: 3 },
+        _links: { download: '/download/attachments/123/diagram.png' }
+      };
+      const result = client.normalizeAttachment(raw);
+      expect(result).toEqual({
+        id: '101',
+        title: 'diagram.png',
+        mediaType: 'image/png',
+        fileSize: 204800,
+        version: 3,
+        downloadLink: expect.stringContaining('/download/attachments/123/diagram.png')
+      });
+    });
+
+    test('normalizeAttachment should handle missing metadata gracefully', () => {
+      const raw = {
+        id: '102',
+        title: 'readme.txt',
+        version: { number: 1 },
+        _links: {}
+      };
+      const result = client.normalizeAttachment(raw);
+      expect(result.mediaType).toBe('');
+      expect(result.fileSize).toBe(0);
+      expect(result.version).toBe(1);
+      expect(result.downloadLink).toBeNull();
+    });
+
+    test('getAllAttachments should return normalized attachment objects', async () => {
+      const mock = new MockAdapter(client.client);
+      mock.onGet('/content/123/child/attachment').reply(200, {
+        results: [{
+          id: '201',
+          title: 'report.pdf',
+          metadata: { mediaType: 'application/pdf' },
+          extensions: { fileSize: 512000 },
+          version: { number: 2 },
+          _links: { download: '/download/attachments/123/report.pdf' }
+        }],
+        _links: {}
+      });
+
+      const attachments = await client.getAllAttachments('123');
+      expect(attachments).toHaveLength(1);
+      expect(attachments[0]).toHaveProperty('id', '201');
+      expect(attachments[0]).toHaveProperty('title', 'report.pdf');
+      expect(attachments[0]).toHaveProperty('mediaType', 'application/pdf');
+      expect(attachments[0]).toHaveProperty('fileSize', 512000);
+      expect(attachments[0]).toHaveProperty('version', 2);
+      expect(attachments[0]).toHaveProperty('downloadLink');
+
+      mock.restore();
+    });
+
     test('deleteAttachment should call delete endpoint', async () => {
       const mock = new MockAdapter(client.client);
       mock.onDelete('/content/123/child/attachment/999').reply(204);