confluence-cli 1.30.1 → 1.31.0

package/README.md

@@ -149,6 +149,21 @@ confluence --profile corp init \
   --tls-ca-cert "~/.certs/ca-chain.pem"
 ```
 
+**Cookie authentication profile** (Enterprise SSO):
+```bash
+confluence --profile sso init \
+  --domain "confluence.company.com" \
+  --api-path "/rest/api" \
+  --auth-type "cookie" \
+  --cookie "JSESSIONID=abc123xyz..."
+
+# Multiple cookies are also supported:
+confluence --profile sso init \
+  --domain "confluence.company.com" \
+  --auth-type "cookie" \
+  --cookie "JSESSIONID=abc123; XSRF-TOKEN=xyz789"
+```
+
 **Hybrid mode** (some fields provided, rest via prompts):
 ```bash
 # Domain and token provided, will prompt for auth method and email
@@ -161,9 +176,10 @@ confluence init --email "user@example.com" --token "your-api-token"
 **Available flags:**
 - `-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`, `bearer`, or `mtls`
+- `-a, --auth-type <type>` - Authentication type: `basic`, `bearer`, `mtls`, or `cookie`
 - `-e, --email <email>` - Email or username for basic authentication
 - `-t, --token <token>` - API token or password
+- `-c, --cookie <cookie>` - Cookie for Enterprise SSO authentication (e.g., `"JSESSIONID=..."`)
 - `--tls-client-cert <path>` - Client certificate for mTLS authentication
 - `--tls-client-key <path>` - Client private key for mTLS authentication
 - `--tls-ca-cert <path>` - Optional CA certificate chain for mTLS authentication
@@ -193,6 +209,14 @@ export CONFLUENCE_TLS_CLIENT_KEY="~/.certs/client.key"
 export CONFLUENCE_TLS_CA_CERT="~/.certs/ca-chain.pem"  # optional
 ```
 
+**Cookie environment variables** (Enterprise SSO):
+```bash
+export CONFLUENCE_DOMAIN="confluence.company.com"
+export CONFLUENCE_API_PATH="/rest/api"
+export CONFLUENCE_AUTH_TYPE="cookie"
+export CONFLUENCE_COOKIE="JSESSIONID=abc123xyz..."
+```
+
 **Scoped API token** (recommended for agents):
 ```bash
 export CONFLUENCE_DOMAIN="api.atlassian.com"
@@ -204,6 +228,27 @@ export CONFLUENCE_API_TOKEN="your-scoped-token"
 
 `CONFLUENCE_API_PATH` defaults to `/wiki/rest/api` for Atlassian Cloud domains and `/rest/api` otherwise. Override it when your site lives under a custom reverse proxy or on-premises path. `CONFLUENCE_AUTH_TYPE` defaults to `basic` when an email is present and falls back to `bearer` otherwise. For `mtls`, set `CONFLUENCE_TLS_CLIENT_CERT` and `CONFLUENCE_TLS_CLIENT_KEY`; `CONFLUENCE_TLS_CA_CERT` is optional.
 
+**Custom domains on Confluence Cloud:**
+
+If your Confluence Cloud instance uses a custom domain (e.g., `wiki.example.org` instead of `*.atlassian.net`), the CLI may misidentify it as a Server/Data Center instance and produce broken link formats. Set `CONFLUENCE_FORCE_CLOUD=true` to override the automatic detection:
+
+```bash
+export CONFLUENCE_FORCE_CLOUD=true
+```
+
+Or add `"forceCloud": true` to your profile in `~/.confluence-cli/config.json`:
+
+```json
+{
+  "profiles": {
+    "default": {
+      "domain": "wiki.example.org",
+      "forceCloud": true
+    }
+  }
+}
+```
+
 **Read-only mode** (recommended for AI agents):
 ```bash
 export CONFLUENCE_READ_ONLY=true
@@ -250,6 +295,8 @@ For **read-only** usage, select at minimum: `read:confluence-content.all`, `read
 
 **mTLS-protected Confluence APIs:** Some self-hosted or reverse-proxied deployments authenticate at the TLS layer with a client certificate instead of sending an application-level token. In these environments, configure `authType=mtls` and provide certificate paths via CLI flags or environment variables. No `Authorization` header will be sent in mTLS mode.
 
+**Enterprise SSO with Cookie Authentication:** For Confluence instances behind Enterprise SSO (SAML, OAuth, Okta, etc.) where API tokens or Basic/Bearer auth are not available, you can authenticate using session cookies. After logging in through your browser, extract the session cookie (typically `JSESSIONID` or similar) from your browser's dev tools and configure it via the `--cookie` flag or `CONFLUENCE_COOKIE` environment variable. The cookie is sent in the `Cookie` header instead of an `Authorization` header. Note that session cookies typically expire, so you'll need to refresh them periodically. For security, prefer `CONFLUENCE_COOKIE` env var or interactive prompt over `--cookie` flag since command-line arguments may be visible in shell history and process listings.
+
 ## Usage
 
 ### Read a Page

package/bin/confluence.js

@@ -16,6 +16,18 @@ function assertWritable(config) {
   }
 }
 
+function assertNonEmpty(value, label) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${label} is required and cannot be empty.`);
+  }
+}
+
+function handleCommandError(analytics, commandName, error) {
+  analytics.track(commandName, false);
+  console.error(chalk.red('Error:'), error.message);
+  process.exit(1);
+}
+
 program
   .name('confluence')
   .description('CLI tool for Atlassian Confluence')
@@ -34,9 +46,10 @@ program
   .option('-d, --domain <domain>', 'Confluence domain')
   .option('--protocol <protocol>', 'Protocol (http or https)')
   .option('-p, --api-path <path>', 'REST API path')
-  .option('-a, --auth-type <type>', 'Authentication type (basic, bearer, or mtls)')
+  .option('-a, --auth-type <type>', 'Authentication type (basic, bearer, mtls, or cookie)')
   .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
+  .option('-c, --cookie <cookie>', 'Cookie for Enterprise SSO authentication (e.g., "JSESSIONID=...")')
   .option('--tls-ca-cert <path>', 'CA certificate for mTLS connections')
   .option('--tls-client-cert <path>', 'Client certificate for mTLS connections')
   .option('--tls-client-key <path>', 'Client private key for mTLS connections')
@@ -59,9 +72,7 @@ program
       console.log(content);
       analytics.track('read', true);
     } catch (error) {
-      analytics.track('read', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'read', error);
     }
   });
 
@@ -84,9 +95,7 @@ program
       }
       analytics.track('info', true);
     } catch (error) {
-      analytics.track('info', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'info', error);
     }
   });
 
@@ -117,9 +126,7 @@ program
       });
       analytics.track('search', true);
     } catch (error) {
-      analytics.track('search', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'search', error);
     }
   });
 
@@ -140,9 +147,7 @@ program
       });
       analytics.track('spaces', true);
     } catch (error) {
-      analytics.track('spaces', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'spaces', error);
     }
   });
 
@@ -214,12 +219,15 @@ program
   .action(async (title, spaceKey, options) => {
     const analytics = new Analytics();
     try {
+      assertNonEmpty(title, 'title');
+      assertNonEmpty(spaceKey, 'spaceKey');
+
       const config = getConfig(getProfileName());
       assertWritable(config);
       const client = new ConfluenceClient(config);
 
       let content = '';
-      
+
       if (options.file) {
         const fs = require('fs');
         if (!fs.existsSync(options.file)) {
@@ -231,7 +239,7 @@ program
       } else {
         throw new Error('Either --file or --content option is required');
       }
-      
+
       const result = await client.createPage(title, spaceKey, content, options.format);
       
       console.log(chalk.green('✅ Page created successfully!'));
@@ -242,9 +250,7 @@ program
 
       analytics.track('create', true);
     } catch (error) {
-      analytics.track('create', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'create', error);
     }
   });
 
@@ -258,6 +264,9 @@ program
   .action(async (title, parentId, options) => {
     const analytics = new Analytics();
     try {
+      assertNonEmpty(title, 'title');
+      assertNonEmpty(parentId, 'parentId');
+
       const config = getConfig(getProfileName());
       assertWritable(config);
       const client = new ConfluenceClient(config);
@@ -291,9 +300,7 @@ program
 
       analytics.track('create_child', true);
     } catch (error) {
-      analytics.track('create_child', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'create_child', error);
     }
   });
 
@@ -313,6 +320,10 @@ program
         throw new Error('At least one of --title, --file, or --content must be provided.');
       }
 
+      if (options.title !== undefined) {
+        assertNonEmpty(options.title, '--title');
+      }
+
       const config = getConfig(getProfileName());
       assertWritable(config);
       const client = new ConfluenceClient(config);
@@ -339,9 +350,7 @@ program
 
       analytics.track('update', true);
     } catch (error) {
-      analytics.track('update', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'update', error);
     }
   });
 
@@ -367,9 +376,7 @@ program
 
       analytics.track('move', true);
     } catch (error) {
-      analytics.track('move', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'move', error);
     }
   });
 
@@ -411,9 +418,7 @@ program
       console.log(`ID: ${chalk.blue(result.id)}`);
       analytics.track('delete', true);
     } catch (error) {
-      analytics.track('delete', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'delete', error);
     }
   });
 
@@ -449,9 +454,7 @@ program
       
       analytics.track('edit', true);
     } catch (error) {
-      analytics.track('edit', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'edit', error);
     }
   });
 
@@ -475,9 +478,7 @@ program
 
       analytics.track('find', true);
     } catch (error) {
-      analytics.track('find', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'find', error);
     }
   });
 
@@ -551,8 +552,9 @@ program
         fs.mkdirSync(destDir, { recursive: true });
 
         const uniquePathFor = (dir, filename) => {
-          const parsed = path.parse(filename);
-          let attempt = path.join(dir, filename);
+          const safeFilename = sanitizeFilename(filename);
+          const parsed = path.parse(safeFilename);
+          let attempt = path.join(dir, safeFilename);
           let counter = 1;
           while (fs.existsSync(attempt)) {
             const suffix = ` (${counter})`;
@@ -597,9 +599,7 @@ program
 
       analytics.track('attachments', true);
     } catch (error) {
-      analytics.track('attachments', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'attachments', error);
     }
   });
 
@@ -659,9 +659,7 @@ program
       console.log(chalk.green(`Uploaded ${uploaded} attachment${uploaded === 1 ? '' : 's'} to page ${pageId}`));
       analytics.track('attachment_upload', true);
     } catch (error) {
-      analytics.track('attachment_upload', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'attachment_upload', error);
     }
   });
 
@@ -701,9 +699,7 @@ program
       console.log(`Page ID: ${chalk.blue(result.pageId)}`);
       analytics.track('attachment_delete', true);
     } catch (error) {
-      analytics.track('attachment_delete', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'attachment_delete', error);
     }
   });
 
@@ -774,9 +770,7 @@ program
       }
       analytics.track('property_list', true);
     } catch (error) {
-      analytics.track('property_list', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'property_list', error);
     }
   });
 
@@ -808,9 +802,7 @@ program
       }
       analytics.track('property_get', true);
     } catch (error) {
-      analytics.track('property_get', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'property_get', error);
     }
   });
 
@@ -867,9 +859,7 @@ program
       }
       analytics.track('property_set', true);
     } catch (error) {
-      analytics.track('property_set', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'property_set', error);
     }
   });
 
@@ -909,9 +899,7 @@ program
       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);
+      handleCommandError(analytics, 'property_delete', error);
     }
   });
 
@@ -1060,9 +1048,7 @@ program
 
       analytics.track('comments', true);
     } catch (error) {
-      analytics.track('comments', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'comments', error);
     }
   });
 
@@ -1225,9 +1211,7 @@ program
       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);
+      handleCommandError(analytics, 'comment_delete', error);
     }
   });
 
@@ -1332,9 +1316,7 @@ program
 
       analytics.track('export', true);
     } catch (error) {
-      analytics.track('export', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'export', error);
     }
   });
 
@@ -1354,9 +1336,24 @@ function isExportDirectory(fs, path, dir) {
   return fs.existsSync(path.join(dir, EXPORT_MARKER));
 }
 
+function sanitizeFilename(filename) {
+  if (!filename || typeof filename !== 'string') {
+    return 'unnamed';
+  }
+  const path = require('path');
+  const stripped = path.basename(filename.replace(/\\/g, '/'));
+  const cleaned = stripped
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\\/:*?"<>|\x00-\x1f]/g, '_')
+    .replace(/^\.+/, '')
+    .trim();
+  return cleaned || 'unnamed';
+}
+
 function uniquePathFor(fs, path, dir, filename) {
-  const parsed = path.parse(filename);
-  let attempt = path.join(dir, filename);
+  const safeFilename = sanitizeFilename(filename);
+  const parsed = path.parse(safeFilename);
+  let attempt = path.join(dir, safeFilename);
   let counter = 1;
   while (fs.existsSync(attempt)) {
     const suffix = ` (${counter})`;
@@ -1556,7 +1553,11 @@ function sanitizeTitle(value) {
   if (!value || typeof value !== 'string') {
     return fallback;
   }
-  const cleaned = value.replace(/[\\/:*?"<>|]/g, ' ').trim();
+  const cleaned = value
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\\/:*?"<>|\x00-\x1f]/g, ' ')
+    .replace(/^\.+/, '')
+    .trim();
   return cleaned || fallback;
 }
 
@@ -1720,9 +1721,7 @@ program
       
       analytics.track('copy_tree', true);
     } catch (error) {
-      analytics.track('copy_tree', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'copy_tree', error);
     }
   });
 
@@ -1819,9 +1818,7 @@ program
       
       analytics.track('children', true);
     } catch (error) {
-      analytics.track('children', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'children', error);
     }
   });
 
@@ -1920,9 +1917,10 @@ profileCmd
   .option('-d, --domain <domain>', 'Confluence domain')
   .option('--protocol <protocol>', 'Protocol (http or https)')
   .option('-p, --api-path <path>', 'REST API path')
-  .option('-a, --auth-type <type>', 'Authentication type (basic, bearer, or mtls)')
+  .option('-a, --auth-type <type>', 'Authentication type (basic, bearer, mtls, or cookie)')
   .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
+  .option('-c, --cookie <cookie>', 'Cookie for Enterprise SSO authentication (e.g., "JSESSIONID=...")')
   .option('--tls-ca-cert <path>', 'CA certificate for mTLS connections')
   .option('--tls-client-cert <path>', 'Client certificate for mTLS connections')
   .option('--tls-client-key <path>', 'Client private key for mTLS connections')
@@ -2039,9 +2037,7 @@ program
       }
       analytics.track('convert', true);
     } catch (error) {
-      analytics.track('convert', false);
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
+      handleCommandError(analytics, 'convert', error);
     }
   });
 
@@ -2055,7 +2051,10 @@ module.exports = {
     uniquePathFor,
     exportRecursive,
     sanitizeTitle,
+    sanitizeFilename,
     assertWritable,
+    assertNonEmpty,
+    handleCommandError,
   },
 };
 

package/lib/config.js

@@ -11,9 +11,12 @@ const DEFAULT_PROFILE = 'default';
 const AUTH_CHOICES = [
   { name: 'Basic (credentials)', value: 'basic' },
   { name: 'Bearer token', value: 'bearer' },
-  { name: 'Client certificate (mTLS)', value: 'mtls' }
+  { name: 'Client certificate (mTLS)', value: 'mtls' },
+  { name: 'Cookie (Enterprise SSO)', value: 'cookie' }
 ];
 
+const AUTH_TYPES = ['basic', 'bearer', 'mtls', 'cookie'];
+
 const isValidProfileName = (name) => /^[a-zA-Z0-9_-]+$/.test(name);
 
 const requiredInput = (label) => (input) => {
@@ -38,7 +41,7 @@ const normalizeProtocol = (rawValue) => {
 
 const normalizeAuthType = (rawValue, hasEmail) => {
   const normalized = (rawValue || '').trim().toLowerCase();
-  if (normalized === 'basic' || normalized === 'bearer' || normalized === 'mtls') {
+  if (AUTH_TYPES.includes(normalized)) {
     return normalized;
   }
   return hasEmail ? 'basic' : 'bearer';
@@ -100,6 +103,34 @@ const validateMtlsProtocol = (protocol) => {
   return null;
 };
 
+// Validate a resolved auth configuration (post-normalization).
+// Returns error messages only; callers format source-specific hints.
+const validateAuthConfig = (auth, mtlsSourceLabel) => {
+  const errors = [];
+
+  if (auth.authType === 'basic' && !auth.email) {
+    errors.push('Basic authentication requires an email address or username.');
+  }
+
+  if (auth.authType === 'cookie' && !auth.cookie) {
+    errors.push('Cookie authentication requires a cookie value.');
+  }
+
+  if (auth.authType !== 'mtls' && auth.authType !== 'cookie' && !auth.token) {
+    errors.push('Bearer or basic authentication requires a token.');
+  }
+
+  if (auth.authType === 'mtls') {
+    errors.push(...validateMtlsConfig(auth.mtls, mtlsSourceLabel));
+    const protocolError = validateMtlsProtocol(auth.protocol);
+    if (protocolError) {
+      errors.push(protocolError);
+    }
+  }
+
+  return errors;
+};
+
 /**
  * Build an inquirer question for an mTLS file path prompt.
  * @param {string} name       - answer key (e.g. 'tlsClientCert')
@@ -177,6 +208,9 @@ function readConfigFile() {
       if (raw.email) {
         profile.email = raw.email;
       }
+      if (raw.cookie) {
+        profile.cookie = raw.cookie;
+      }
       return {
         activeProfile: DEFAULT_PROFILE,
         profiles: { [DEFAULT_PROFILE]: profile }
@@ -233,8 +267,8 @@ const validateCliOptions = (options) => {
     errors.push('--protocol must be "http" or "https"');
   }
 
-  if (options.authType && !['basic', 'bearer', 'mtls'].includes(options.authType.toLowerCase())) {
-    errors.push('--auth-type must be "basic", "bearer", or "mtls"');
+  if (options.authType && !AUTH_TYPES.includes(options.authType.toLowerCase())) {
+    errors.push('--auth-type must be "basic", "bearer", "mtls", or "cookie"');
   }
 
   // Check if basic auth is provided with email
@@ -253,6 +287,10 @@ const validateCliOptions = (options) => {
     }
   }
 
+  if (normAuthType === 'cookie' && options.cookie !== undefined && !options.cookie.trim()) {
+    errors.push('--cookie cannot be empty when using cookie authentication');
+  }
+
   return errors;
 };
 
@@ -273,6 +311,10 @@ const saveConfig = (configData, profileName) => {
     config.email = configData.email.trim();
   }
 
+  if (configData.authType === 'cookie' && configData.cookie) {
+    config.cookie = configData.cookie.trim();
+  }
+
   const mtls = normalizeMtlsConfig(configData.mtls);
   if (mtls) {
     config.mtls = mtls;
@@ -388,12 +430,26 @@ const promptForMissingValues = async (providedValues) => {
       message: 'API token / password:',
       when: (responses) => {
         const authType = providedValues.authType || responses.authType;
-        return authType !== 'mtls';
+        return authType !== 'mtls' && authType !== 'cookie';
       },
       validate: requiredInput('API token / password')
     });
   }
 
+  // Cookie question (Enterprise SSO)
+  if (!providedValues.cookie) {
+    questions.push({
+      type: 'password',
+      name: 'cookie',
+      message: 'Cookie (format: "name=value" or "name=value; name2=value2"):',
+      when: (responses) => {
+        const authType = providedValues.authType || responses.authType;
+        return authType === 'cookie';
+      },
+      validate: requiredInput('Cookie')
+    });
+  }
+
   // mTLS certificate path questions
   const mtls = normalizeMtlsConfig(providedValues.mtls);
   const mtlsWhen = (responses) => {
@@ -429,14 +485,18 @@ async function initConfig(cliOptions = {}) {
 
   const readOnly = cliOptions.readOnly || false;
 
-  // Extract provided values from CLI options
+  // Extract provided values from CLI options.
+  // Normalize authType up front so downstream case-insensitive checks
+  // (hasRequiredValues, prompt `when` predicates) work for values like
+  // `--auth-type COOKIE` or `--auth-type MTLS`.
   const providedValues = {
     protocol: cliOptions.protocol,
     domain: cliOptions.domain,
     apiPath: cliOptions.apiPath,
-    authType: cliOptions.authType,
+    authType: cliOptions.authType ? cliOptions.authType.trim().toLowerCase() : undefined,
     email: cliOptions.email,
     token: cliOptions.token,
+    cookie: cliOptions.cookie,
     mtls: cliOptions.mtls || {
       caCert: cliOptions.tlsCaCert,
       clientCert: cliOptions.tlsClientCert,
@@ -508,9 +568,16 @@ async function initConfig(cliOptions = {}) {
         type: 'password',
         name: 'token',
         message: 'API token / password:',
-        when: (responses) => responses.authType !== 'mtls',
+        when: (responses) => responses.authType !== 'mtls' && responses.authType !== 'cookie',
         validate: requiredInput('API token / password')
       },
+      {
+        type: 'password',
+        name: 'cookie',
+        message: 'Cookie (format: "name=value" or "name=value; name2=value2"):',
+        when: (responses) => responses.authType === 'cookie',
+        validate: requiredInput('Cookie')
+      },
       mtlsCertQuestion('tlsClientCert', 'Path to client certificate file (PEM):', true),
       mtlsCertQuestion('tlsClientKey', 'Path to client key file (PEM):', true),
       mtlsCertQuestion('tlsCaCert', 'Path to CA certificate file (PEM, optional):', false)
@@ -541,11 +608,15 @@ async function initConfig(cliOptions = {}) {
   }
 
   // Check if all required values are provided for non-interactive mode
-  // Non-interactive requires: domain, token, and either authType or email (for inference)
+  // Non-interactive requires: domain, and one of:
+  //   - authType === 'mtls' (certs via flags/env)
+  //   - authType === 'cookie' + cookie
+  //   - token + (authType or email) for basic/bearer
   const hasRequiredValues = Boolean(
     providedValues.domain &&
     (
       providedValues.authType === 'mtls'
+      || (providedValues.authType === 'cookie' && providedValues.cookie)
       || (
         providedValues.token &&
         (providedValues.authType || providedValues.email)
@@ -571,11 +642,16 @@ async function initConfig(cliOptions = {}) {
         process.exit(1);
       }
 
-      if (normalizedAuthType !== 'mtls' && !providedValues.token) {
+      if (normalizedAuthType !== 'mtls' && normalizedAuthType !== 'cookie' && !providedValues.token) {
         console.error(chalk.red('❌ Token is required for basic or bearer authentication'));
         process.exit(1);
       }
 
+      if (normalizedAuthType === 'cookie' && !providedValues.cookie) {
+        console.error(chalk.red('❌ Cookie is required for cookie authentication'));
+        process.exit(1);
+      }
+
       // Verify API path format if provided
       if (providedValues.apiPath) {
         normalizeApiPath(providedValues.apiPath, normalizedDomain);
@@ -588,6 +664,7 @@ async function initConfig(cliOptions = {}) {
         token: providedValues.token,
         authType: normalizedAuthType,
         email: providedValues.email,
+        cookie: providedValues.cookie,
         mtls: providedValues.mtls,
         readOnly
       };
@@ -633,18 +710,30 @@ function getConfig(profileName) {
   const envDomain = process.env.CONFLUENCE_DOMAIN || process.env.CONFLUENCE_HOST;
   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;
+  // Normalize up front so env gating and inferredAuthType are case-insensitive
+  // for values like CONFLUENCE_AUTH_TYPE=COOKIE / MTLS.
+  const envAuthType = process.env.CONFLUENCE_AUTH_TYPE
+    ? process.env.CONFLUENCE_AUTH_TYPE.trim().toLowerCase()
+    : undefined;
   const envApiPath = process.env.CONFLUENCE_API_PATH;
   const envProtocol = process.env.CONFLUENCE_PROTOCOL;
   const envReadOnly = process.env.CONFLUENCE_READ_ONLY;
+  const envForceCloud = process.env.CONFLUENCE_FORCE_CLOUD;
+  const envCookie = process.env.CONFLUENCE_COOKIE;
   const envMtls = normalizeMtlsConfig({
     caCert: process.env.CONFLUENCE_TLS_CA_CERT,
     clientCert: process.env.CONFLUENCE_TLS_CLIENT_CERT,
     clientKey: process.env.CONFLUENCE_TLS_CLIENT_KEY,
   });
 
-  if (envDomain && (envToken || envAuthType === 'mtls' || envMtls)) {
-    const inferredAuthType = envAuthType || (envMtls && !envToken ? 'mtls' : undefined);
+  const hasEnvAuth = envToken
+    || envAuthType === 'mtls' || envMtls
+    || envAuthType === 'cookie' || envCookie;
+
+  if (envDomain && hasEnvAuth) {
+    const inferredAuthType = envAuthType
+      || (envMtls && !envToken ? 'mtls' : undefined)
+      || (envCookie && !envToken ? 'cookie' : undefined);
     const authType = normalizeAuthType(inferredAuthType, Boolean(envEmail));
     let apiPath;
 
@@ -655,29 +744,22 @@ function getConfig(profileName) {
       process.exit(1);
     }
 
-    if (authType === 'basic' && !envEmail) {
-      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);
-    }
-
-    if (authType !== 'mtls' && !envToken) {
-      console.error(chalk.red('❌ Bearer/basic authentication requires CONFLUENCE_API_TOKEN or CONFLUENCE_PASSWORD.'));
-      process.exit(1);
-    }
-
-    if (authType === 'mtls') {
-      const mtlsErrors = validateMtlsConfig(envMtls, 'CONFLUENCE_AUTH_TYPE=mtls');
-      if (mtlsErrors.length > 0) {
-        console.error(chalk.red(`❌ ${mtlsErrors.join(' ')}`));
+    const authErrors = validateAuthConfig(
+      { authType, token: envToken, email: envEmail, cookie: envCookie, mtls: envMtls, protocol: envProtocol },
+      'CONFLUENCE_AUTH_TYPE=mtls'
+    );
+    if (authErrors.length > 0) {
+      console.error(chalk.red(`❌ ${authErrors.join(' ')}`));
+      if (authType === 'basic' && !envEmail) {
+        console.log(chalk.yellow('Set CONFLUENCE_EMAIL (or CONFLUENCE_USERNAME for on-premise) or switch to bearer auth by setting CONFLUENCE_AUTH_TYPE=bearer.'));
+      }
+      if (authType === 'mtls' && !envMtls) {
         console.log(chalk.yellow('Set CONFLUENCE_TLS_CLIENT_CERT and CONFLUENCE_TLS_CLIENT_KEY. Optionally set CONFLUENCE_TLS_CA_CERT.'));
-        process.exit(1);
       }
-      if (normalizeProtocol(envProtocol) === 'http') {
-        const protocolError = validateMtlsProtocol(envProtocol);
-        console.error(chalk.red(`❌ ${protocolError}`));
-        process.exit(1);
+      if (authType === 'cookie' && !envCookie) {
+        console.log(chalk.yellow('Set CONFLUENCE_COOKIE with your session cookie (e.g., "JSESSIONID=...").'));
       }
+      process.exit(1);
     }
 
     return {
@@ -686,9 +768,11 @@ function getConfig(profileName) {
       apiPath,
       token: envToken ? envToken.trim() : undefined,
       email: envEmail ? envEmail.trim() : undefined,
+      cookie: envCookie ? envCookie.trim() : undefined,
       authType,
       mtls: envMtls,
-      readOnly: envReadOnly === 'true'
+      readOnly: envReadOnly === 'true',
+      forceCloud: envForceCloud === 'true'
     };
   }
 
@@ -723,37 +807,27 @@ function getConfig(profileName) {
     const trimmedDomain = (storedConfig.domain || '').trim();
     const trimmedToken = trimOptional(storedConfig.token);
     const trimmedEmail = storedConfig.email ? storedConfig.email.trim() : undefined;
+    const trimmedCookie = trimOptional(storedConfig.cookie);
     const authType = normalizeAuthType(storedConfig.authType, Boolean(trimmedEmail));
     const mtls = normalizeMtlsConfig(storedConfig.mtls);
     let apiPath;
 
-    if (!trimmedDomain || (authType !== 'mtls' && !trimmedToken)) {
+    if (!trimmedDomain) {
       console.error(chalk.red('❌ Configuration file is missing required values.'));
       console.log(chalk.yellow('Run "confluence init" to refresh your settings.'));
       process.exit(1);
     }
 
-    if (authType === 'basic' && !trimmedEmail) {
-      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.'));
+    const authErrors = validateAuthConfig(
+      { authType, token: trimmedToken, email: trimmedEmail, cookie: trimmedCookie, mtls, protocol: storedConfig.protocol },
+      'mTLS authentication'
+    );
+    if (authErrors.length > 0) {
+      console.error(chalk.red(`❌ ${authErrors.join(' ')}`));
+      console.log(chalk.yellow('Please rerun "confluence init" to refresh your settings.'));
       process.exit(1);
     }
 
-    if (authType === 'mtls') {
-      const mtlsErrors = validateMtlsConfig(mtls, 'mTLS authentication');
-      if (mtlsErrors.length > 0) {
-        console.error(chalk.red(`❌ ${mtlsErrors.join(' ')}`));
-        console.log(chalk.yellow('Please rerun "confluence init" to add your mTLS certificate paths.'));
-        process.exit(1);
-      }
-      if (normalizeProtocol(storedConfig.protocol) === 'http') {
-        const protocolError = validateMtlsProtocol(storedConfig.protocol);
-        console.error(chalk.red(`❌ ${protocolError}`));
-        console.log(chalk.yellow('Please rerun "confluence init" to update your protocol to HTTPS.'));
-        process.exit(1);
-      }
-    }
-
     try {
       apiPath = normalizeApiPath(storedConfig.apiPath, trimmedDomain);
     } catch (error) {
@@ -766,15 +840,21 @@ function getConfig(profileName) {
       ? envReadOnly === 'true'
       : Boolean(storedConfig.readOnly);
 
+    const forceCloud = envForceCloud !== undefined
+      ? envForceCloud === 'true'
+      : Boolean(storedConfig.forceCloud);
+
     return {
       domain: trimmedDomain,
       protocol: normalizeProtocol(storedConfig.protocol),
       apiPath,
       token: trimmedToken,
       email: trimmedEmail,
+      cookie: trimmedCookie,
       authType,
       mtls,
-      readOnly
+      readOnly,
+      forceCloud
     };
   } catch (error) {
     console.error(chalk.red('❌ Error reading configuration file:'), error.message);

package/lib/confluence-client.js

@@ -34,7 +34,9 @@ class ConfluenceClient {
     this.protocol = (rawProtocol === 'http' || rawProtocol === 'https') ? rawProtocol : 'https';
     this.token = config.token;
     this.email = config.email;
+    this.cookie = config.cookie;
     this.authType = (config.authType || (this.email ? 'basic' : 'bearer')).toLowerCase();
+    this.forceCloud = !!config.forceCloud;
     this.mtls = config.mtls;
     this.apiPath = this.sanitizeApiPath(config.apiPath);
     this.webUrlPrefix = this.apiPath.startsWith('/wiki/') ? '/wiki' : '';
@@ -43,12 +45,9 @@ class ConfluenceClient {
     this.setupConfluenceMarkdownExtensions();
 
     const headers = {
-      'Content-Type': 'application/json'
+      'Content-Type': 'application/json',
+      ...this.buildAuthHeaders()
     };
-    const authHeader = this.buildAuthHeader();
-    if (authHeader) {
-      headers.Authorization = authHeader;
-    }
 
     const clientOptions = {
       baseURL: this.baseURL,
@@ -87,6 +86,11 @@ class ConfluenceClient {
             hints.push(
               'Please verify your client certificate, client key, and CA certificate are correct and trusted by the server.'
             );
+          } else if (this.authType === 'cookie') {
+            hints.push(
+              'Please verify your cookie is valid and not expired.',
+              'You may need to re-authenticate through your Enterprise SSO to get a fresh cookie.'
+            );
           } else {
             hints.push(
               'Please verify your personal access token is valid and not expired.'
@@ -100,7 +104,7 @@ class ConfluenceClient {
   }
 
   isCloud() {
-    return this.isScopedToken() || (this.domain && this.domain.trim().toLowerCase().endsWith('.atlassian.net'));
+    return this.isScopedToken() || (this.domain && this.domain.trim().toLowerCase().endsWith('.atlassian.net')) || this.forceCloud;
   }
 
   isScopedToken() {
@@ -131,7 +135,7 @@ class ConfluenceClient {
   }
 
   buildAuthHeader() {
-    if (this.authType === 'mtls') {
+    if (this.authType === 'mtls' || this.authType === 'cookie') {
       return null;
     }
 
@@ -142,6 +146,18 @@ class ConfluenceClient {
     return this.authType === 'basic' ? this.buildBasicAuthHeader() : `Bearer ${this.token}`;
   }
 
+  buildAuthHeaders() {
+    const headers = {};
+    const authHeader = this.buildAuthHeader();
+    if (authHeader) {
+      headers.Authorization = authHeader;
+    }
+    if (this.authType === 'cookie' && this.cookie) {
+      headers.Cookie = this.cookie;
+    }
+    return headers;
+  }
+
   buildHttpsAgent() {
     if (this.protocol !== 'https' || !this.mtls) {
       return null;
@@ -380,11 +396,26 @@ class ConfluenceClient {
     };
   }
 
+  /**
+   * Escape a string for safe use inside a CQL double-quoted literal.
+   * Only escapes characters that can break out of the literal: backslash and
+   * double quote. Wildcards (*, ?) and fuzzy (~) are left as-is so existing
+   * search semantics are preserved.
+   */
+  escapeCql(str) {
+    if (typeof str !== 'string') {
+      return '';
+    }
+    return str
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"');
+  }
+
   /**
    * Search for pages
    */
   async search(query, limit = 10, rawCql = false) {
-    const cql = rawCql ? query : `text ~ "${String(query).replace(/"/g, '\\"')}"`;
+    const cql = rawCql ? query : `text ~ "${this.escapeCql(query)}"`;
     const response = await this.client.get('/search', {
       params: {
         cql,
@@ -477,12 +508,12 @@ class ConfluenceClient {
     // Replace userkey references with display names in HTML
     let resolvedHtml = html;
     userMap.forEach((displayName, userKey) => {
-      // Replace <ac:link><ri:user ri:userkey="xxx" /></ac:link> with @displayName
+      const escapedKey = userKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
       const userLinkRegex = new RegExp(
-        `<ac:link>\\s*<ri:user\\s+ri:userkey="${userKey}"\\s*/>\\s*</ac:link>`,
+        `<ac:link>\\s*<ri:user\\s+ri:userkey="${escapedKey}"\\s*/>\\s*</ac:link>`,
         'g'
       );
-      resolvedHtml = resolvedHtml.replace(userLinkRegex, `@${displayName}`);
+      resolvedHtml = resolvedHtml.replace(userLinkRegex, () => `@${displayName}`);
     });
 
     return { html: resolvedHtml, userMap };
@@ -965,12 +996,15 @@ class ConfluenceClient {
     }
 
     // Download directly using axios with the same auth headers
-    const downloadResponse = await axios.get(downloadUrl, {
+    const downloadRequestConfig = {
       responseType: options.responseType || 'stream',
-      headers: {
-        'Authorization': this.authType === 'basic' ? this.buildBasicAuthHeader() : `Bearer ${this.token}`
-      }
-    });
+      headers: this.buildAuthHeaders()
+    };
+    const httpsAgent = this.buildHttpsAgent();
+    if (httpsAgent) {
+      downloadRequestConfig.httpsAgent = httpsAgent;
+    }
+    const downloadResponse = await axios.get(downloadUrl, downloadRequestConfig);
     return downloadResponse.data;
   }
 
@@ -1871,9 +1905,9 @@ class ConfluenceClient {
    * Search for a page by title and space
    */
   async findPageByTitle(title, spaceKey = null) {
-    let cql = `title = "${title}"`;
+    let cql = `title = "${this.escapeCql(title)}"`;
     if (spaceKey) {
-      cql += ` AND space = "${spaceKey}"`;
+      cql += ` AND space = "${this.escapeCql(spaceKey)}"`;
     }
 
     const response = await this.client.get('/search', {
@@ -2177,7 +2211,10 @@ class ConfluenceClient {
       return pathOrUrl;
     }
 
-    return this.buildUrl(pathOrUrl);
+    const pathWithPrefix = this.webUrlPrefix && !pathOrUrl.startsWith(this.webUrlPrefix)
+      ? `${this.webUrlPrefix}${pathOrUrl}`
+      : pathOrUrl;
+    return this.buildUrl(pathWithPrefix);
   }
 
   parseNextStart(nextLink) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "confluence-cli",
-  "version": "1.30.1",
+  "version": "1.31.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "confluence-cli",
-      "version": "1.30.1",
+      "version": "1.31.0",
       "license": "MIT",
       "dependencies": {
         "axios": "^1.15.0",

package/package.json

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

package/plugins/confluence/skills/confluence/SKILL.md

@@ -29,6 +29,7 @@ confluence --version   # verify install
 | `CONFLUENCE_API_TOKEN` | API token or personal access token | `ATATT3x...` |
 | `CONFLUENCE_PROFILE` | Named profile to use (optional) | `staging` |
 | `CONFLUENCE_READ_ONLY` | Block all write operations when `true` | `true` |
+| `CONFLUENCE_FORCE_CLOUD` | Force Cloud link format for custom domains | `true` |
 
 **Global `--profile` flag (use a named profile for any command):**
 
@@ -53,6 +54,7 @@ confluence init \
 
 **Cloud vs Server/DC:**
 - Atlassian Cloud (`*.atlassian.net`): use `--api-path "/wiki/rest/api"`, auth type `basic` with email + API token
+- Atlassian Cloud (custom domain): if your Cloud instance uses a custom domain (e.g., `wiki.example.org`), set `CONFLUENCE_FORCE_CLOUD=true` or add `"forceCloud": true` to your profile in `~/.confluence-cli/config.json`. Without this, links will render incorrectly.
 - Atlassian Cloud (scoped token): use `--domain "api.atlassian.com"`, `--api-path "/ex/confluence/<your-cloud-id>/wiki/rest/api"`, auth type `basic` with email + scoped token. Get your Cloud ID from `https://<your-site>.atlassian.net/_edge/tenant_info`. Recommended for agents (least privilege).
 - Self-hosted / Data Center: use `--api-path "/rest/api"`, auth type `bearer` with a personal access token (no email needed)