confluence-cli 1.30.0 → 1.30.2

package/README.md

@@ -102,7 +102,7 @@ This creates `.claude/skills/confluence/SKILL.md` in your current directory. Cla
 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/username + token/password) 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), Bearer, or client-certificate (mTLS) authentication.
 
 ### Option 2: Non-interactive Setup (CLI Flags)
 
@@ -138,6 +138,17 @@ confluence --profile staging init \
   --token "your-personal-access-token"
 ```
 
+**mTLS profile** (self-hosted or reverse-proxied Confluence APIs):
+```bash
+confluence --profile corp init \
+  --domain "docs.example.com" \
+  --api-path "/confluence/rest/api" \
+  --auth-type "mtls" \
+  --tls-client-cert "~/.certs/client.pem" \
+  --tls-client-key "~/.certs/client.key" \
+  --tls-ca-cert "~/.certs/ca-chain.pem"
+```
+
 **Hybrid mode** (some fields provided, rest via prompts):
 ```bash
 # Domain and token provided, will prompt for auth method and email
@@ -150,9 +161,12 @@ 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` or `bearer`
+- `-a, --auth-type <type>` - Authentication type: `basic`, `bearer`, or `mtls`
 - `-e, --email <email>` - Email or username for basic authentication
 - `-t, --token <token>` - API token or password
+- `--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
 - `--read-only` - Enable read-only mode (blocks all write operations)
 
 ⚠️ **Security note:** While flags work, storing tokens in shell history is risky. Prefer environment variables (Option 3) for production environments.
@@ -169,6 +183,16 @@ export CONFLUENCE_AUTH_TYPE="basic"
 export CONFLUENCE_PROFILE="default"
 ```
 
+**mTLS environment variables**:
+```bash
+export CONFLUENCE_DOMAIN="docs.example.com"
+export CONFLUENCE_API_PATH="/confluence/rest/api"
+export CONFLUENCE_AUTH_TYPE="mtls"
+export CONFLUENCE_TLS_CLIENT_CERT="~/.certs/client.pem"
+export CONFLUENCE_TLS_CLIENT_KEY="~/.certs/client.key"
+export CONFLUENCE_TLS_CA_CERT="~/.certs/ca-chain.pem"  # optional
+```
+
 **Scoped API token** (recommended for agents):
 ```bash
 export CONFLUENCE_DOMAIN="api.atlassian.com"
@@ -178,7 +202,28 @@ export CONFLUENCE_EMAIL="user@example.com"
 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.
+`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
@@ -224,6 +269,8 @@ For **read-only** usage, select at minimum: `read:confluence-content.all`, `read
 
 **On-premise / Data Center:** Use your Confluence username and password for basic authentication.
 
+**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.
+
 ## 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,12 @@ 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 or bearer)')
+  .option('-a, --auth-type <type>', 'Authentication type (basic, bearer, or mtls)')
   .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
+  .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')
   .option('--read-only', 'Set profile to read-only mode (blocks write operations)')
   .action(async (options) => {
     const profile = getProfileName();
@@ -56,9 +71,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);
     }
   });
 
@@ -81,9 +94,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);
     }
   });
 
@@ -114,9 +125,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);
     }
   });
 
@@ -137,9 +146,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);
     }
   });
 
@@ -211,12 +218,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)) {
@@ -228,7 +238,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!'));
@@ -239,9 +249,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);
     }
   });
 
@@ -255,6 +263,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);
@@ -288,9 +299,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);
     }
   });
 
@@ -310,6 +319,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);
@@ -336,9 +349,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);
     }
   });
 
@@ -364,9 +375,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);
     }
   });
 
@@ -408,9 +417,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);
     }
   });
 
@@ -446,9 +453,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);
     }
   });
 
@@ -472,9 +477,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);
     }
   });
 
@@ -594,9 +597,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);
     }
   });
 
@@ -656,9 +657,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);
     }
   });
 
@@ -698,9 +697,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);
     }
   });
 
@@ -771,9 +768,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);
     }
   });
 
@@ -805,9 +800,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);
     }
   });
 
@@ -864,9 +857,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);
     }
   });
 
@@ -906,9 +897,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);
     }
   });
 
@@ -1057,9 +1046,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);
     }
   });
 
@@ -1222,9 +1209,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);
     }
   });
 
@@ -1329,9 +1314,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);
     }
   });
 
@@ -1717,9 +1700,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);
     }
   });
 
@@ -1816,9 +1797,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);
     }
   });
 
@@ -1917,9 +1896,12 @@ 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 or bearer)')
+  .option('-a, --auth-type <type>', 'Authentication type (basic, bearer, or mtls)')
   .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
+  .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')
   .option('--read-only', 'Set profile to read-only mode (blocks write operations)')
   .action(async (name, options) => {
     if (!isValidProfileName(name)) {
@@ -2033,9 +2015,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);
     }
   });
 
@@ -2050,6 +2030,8 @@ module.exports = {
     exportRecursive,
     sanitizeTitle,
     assertWritable,
+    assertNonEmpty,
+    handleCommandError,
   },
 };
 

package/lib/config.js

@@ -10,7 +10,8 @@ const DEFAULT_PROFILE = 'default';
 
 const AUTH_CHOICES = [
   { name: 'Basic (credentials)', value: 'basic' },
-  { name: 'Bearer token', value: 'bearer' }
+  { name: 'Bearer token', value: 'bearer' },
+  { name: 'Client certificate (mTLS)', value: 'mtls' }
 ];
 
 const isValidProfileName = (name) => /^[a-zA-Z0-9_-]+$/.test(name);
@@ -37,12 +38,116 @@ const normalizeProtocol = (rawValue) => {
 
 const normalizeAuthType = (rawValue, hasEmail) => {
   const normalized = (rawValue || '').trim().toLowerCase();
-  if (normalized === 'basic' || normalized === 'bearer') {
+  if (normalized === 'basic' || normalized === 'bearer' || normalized === 'mtls') {
     return normalized;
   }
   return hasEmail ? 'basic' : 'bearer';
 };
 
+const trimOptional = (value) => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+};
+
+const normalizeMtlsConfig = (mtls) => {
+  if (!mtls) {
+    return undefined;
+  }
+
+  const normalized = {
+    caCert: trimOptional(mtls.caCert),
+    clientCert: trimOptional(mtls.clientCert),
+    clientKey: trimOptional(mtls.clientKey),
+  };
+
+  if (!normalized.caCert && !normalized.clientCert && !normalized.clientKey) {
+    return undefined;
+  }
+
+  return normalized;
+};
+
+const validateMtlsConfig = (mtls, labelPrefix = 'mTLS') => {
+  const normalized = normalizeMtlsConfig(mtls);
+  if (!normalized) {
+    return [`${labelPrefix} requires a client certificate and client key.`];
+  }
+
+  const errors = [];
+  if (!normalized.clientCert) {
+    errors.push(`${labelPrefix} requires a client certificate.`);
+  } else if (!fs.existsSync(normalized.clientCert)) {
+    errors.push(`${labelPrefix} client certificate file not found: ${normalized.clientCert}`);
+  }
+  if (!normalized.clientKey) {
+    errors.push(`${labelPrefix} requires a client key.`);
+  } else if (!fs.existsSync(normalized.clientKey)) {
+    errors.push(`${labelPrefix} client key file not found: ${normalized.clientKey}`);
+  }
+  if (normalized.caCert && !fs.existsSync(normalized.caCert)) {
+    errors.push(`${labelPrefix} CA certificate file not found: ${normalized.caCert}`);
+  }
+  return errors;
+};
+
+const validateMtlsProtocol = (protocol) => {
+  if (normalizeProtocol(protocol) === 'http') {
+    return 'mTLS authentication requires HTTPS and is not compatible with HTTP.';
+  }
+  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 !== 'mtls' && !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')
+ * @param {string} message    - prompt text
+ * @param {boolean} required  - whether the field is mandatory
+ * @param {Function} [whenFn] - optional custom `when` predicate; defaults to authType === 'mtls'
+ */
+const mtlsCertQuestion = (name, message, required, whenFn) => ({
+  type: 'input',
+  name,
+  message,
+  when: whenFn || ((responses) => responses.authType === 'mtls'),
+  validate: (input) => {
+    const value = (input || '').trim();
+    if (!value) {
+      return required ? `${message.replace(/:$/, '')} is required for mTLS.` : true;
+    }
+    if (!fs.existsSync(value)) {
+      return `File not found: ${value}`;
+    }
+    return true;
+  }
+});
+
 const inferApiPath = (domain) => {
   if (!domain) {
     return '/rest/api';
@@ -89,6 +194,10 @@ function readConfigFile() {
         token: raw.token,
         authType: raw.authType
       };
+      const mtls = normalizeMtlsConfig(raw.mtls);
+      if (mtls) {
+        profile.mtls = mtls;
+      }
       if (raw.email) {
         profile.email = raw.email;
       }
@@ -123,7 +232,7 @@ const validateCliOptions = (options) => {
     errors.push('--domain cannot be empty');
   }
 
-  if (options.token && !options.token.trim()) {
+  if (options.token !== undefined && !options.token.trim()) {
     errors.push('--token cannot be empty');
   }
 
@@ -148,8 +257,8 @@ const validateCliOptions = (options) => {
     errors.push('--protocol must be "http" or "https"');
   }
 
-  if (options.authType && !['basic', 'bearer'].includes(options.authType.toLowerCase())) {
-    errors.push('--auth-type must be "basic" or "bearer"');
+  if (options.authType && !['basic', 'bearer', 'mtls'].includes(options.authType.toLowerCase())) {
+    errors.push('--auth-type must be "basic", "bearer", or "mtls"');
   }
 
   // Check if basic auth is provided with email
@@ -158,6 +267,16 @@ const validateCliOptions = (options) => {
     errors.push('--email is required when using basic authentication (use your username for on-premise)');
   }
 
+  if (normAuthType === 'mtls') {
+    validateMtlsConfig(options.mtls, '--auth-type mtls').forEach((error) => {
+      errors.push(error);
+    });
+    const protocolError = validateMtlsProtocol(options.protocol);
+    if (protocolError) {
+      errors.push(protocolError);
+    }
+  }
+
   return errors;
 };
 
@@ -167,14 +286,22 @@ const saveConfig = (configData, profileName) => {
     domain: configData.domain.trim(),
     protocol: normalizeProtocol(configData.protocol),
     apiPath: normalizeApiPath(configData.apiPath, configData.domain),
-    token: configData.token.trim(),
     authType: configData.authType
   };
 
+  if (configData.token) {
+    config.token = configData.token.trim();
+  }
+
   if (configData.authType === 'basic' && configData.email) {
     config.email = configData.email.trim();
   }
 
+  const mtls = normalizeMtlsConfig(configData.mtls);
+  if (mtls) {
+    config.mtls = mtls;
+  }
+
   if (configData.readOnly) {
     config.readOnly = true;
   }
@@ -283,10 +410,30 @@ const promptForMissingValues = async (providedValues) => {
       type: 'password',
       name: 'token',
       message: 'API token / password:',
+      when: (responses) => {
+        const authType = providedValues.authType || responses.authType;
+        return authType !== 'mtls';
+      },
       validate: requiredInput('API token / password')
     });
   }
 
+  // mTLS certificate path questions
+  const mtls = normalizeMtlsConfig(providedValues.mtls);
+  const mtlsWhen = (responses) => {
+    const authType = providedValues.authType || responses.authType;
+    return authType === 'mtls';
+  };
+  if (!mtls || !mtls.clientCert) {
+    questions.push(mtlsCertQuestion('tlsClientCert', 'Path to client certificate file (PEM):', true, mtlsWhen));
+  }
+  if (!mtls || !mtls.clientKey) {
+    questions.push(mtlsCertQuestion('tlsClientKey', 'Path to client key file (PEM):', true, mtlsWhen));
+  }
+  if (!mtls || !mtls.caCert) {
+    questions.push(mtlsCertQuestion('tlsCaCert', 'Path to CA certificate file (PEM, optional):', false, mtlsWhen));
+  }
+
   if (questions.length === 0) {
     return providedValues;
   }
@@ -313,7 +460,12 @@ async function initConfig(cliOptions = {}) {
     apiPath: cliOptions.apiPath,
     authType: cliOptions.authType,
     email: cliOptions.email,
-    token: cliOptions.token
+    token: cliOptions.token,
+    mtls: cliOptions.mtls || {
+      caCert: cliOptions.tlsCaCert,
+      clientCert: cliOptions.tlsClientCert,
+      clientKey: cliOptions.tlsClientKey,
+    }
   };
 
   // Check if any CLI options were provided
@@ -380,11 +532,24 @@ async function initConfig(cliOptions = {}) {
         type: 'password',
         name: 'token',
         message: 'API token / password:',
+        when: (responses) => responses.authType !== 'mtls',
         validate: requiredInput('API token / password')
-      }
+      },
+      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)
     ]);
 
-    saveConfig({ ...answers, readOnly }, profileName);
+    const configData = { ...answers, readOnly };
+    if (answers.authType === 'mtls') {
+      configData.mtls = {
+        clientCert: answers.tlsClientCert,
+        clientKey: answers.tlsClientKey,
+        caCert: answers.tlsCaCert || undefined,
+      };
+    }
+
+    saveConfig(configData, profileName);
     return;
   }
 
@@ -403,8 +568,13 @@ async function initConfig(cliOptions = {}) {
   // Non-interactive requires: domain, token, and either authType or email (for inference)
   const hasRequiredValues = Boolean(
     providedValues.domain &&
-    providedValues.token &&
-    (providedValues.authType || providedValues.email)
+    (
+      providedValues.authType === 'mtls'
+      || (
+        providedValues.token &&
+        (providedValues.authType || providedValues.email)
+      )
+    )
   );
 
   if (hasRequiredValues) {
@@ -425,6 +595,11 @@ async function initConfig(cliOptions = {}) {
         process.exit(1);
       }
 
+      if (normalizedAuthType !== 'mtls' && !providedValues.token) {
+        console.error(chalk.red('❌ Token is required for basic or bearer authentication'));
+        process.exit(1);
+      }
+
       // Verify API path format if provided
       if (providedValues.apiPath) {
         normalizeApiPath(providedValues.apiPath, normalizedDomain);
@@ -437,6 +612,7 @@ async function initConfig(cliOptions = {}) {
         token: providedValues.token,
         authType: normalizedAuthType,
         email: providedValues.email,
+        mtls: providedValues.mtls,
         readOnly
       };
 
@@ -461,6 +637,15 @@ async function initConfig(cliOptions = {}) {
     // Normalize auth type
     mergedValues.authType = normalizeAuthType(mergedValues.authType, Boolean(mergedValues.email));
 
+    // Build mTLS config from prompted values if needed
+    if (mergedValues.authType === 'mtls') {
+      mergedValues.mtls = normalizeMtlsConfig({
+        clientCert: mergedValues.tlsClientCert || (mergedValues.mtls && mergedValues.mtls.clientCert),
+        clientKey: mergedValues.tlsClientKey || (mergedValues.mtls && mergedValues.mtls.clientKey),
+        caCert: mergedValues.tlsCaCert || (mergedValues.mtls && mergedValues.mtls.caCert),
+      });
+    }
+
     saveConfig({ ...mergedValues, readOnly }, profileName);
   } catch (error) {
     console.error(chalk.red(`❌ ${error.message}`));
@@ -476,9 +661,16 @@ function getConfig(profileName) {
   const envApiPath = process.env.CONFLUENCE_API_PATH;
   const envProtocol = process.env.CONFLUENCE_PROTOCOL;
   const envReadOnly = process.env.CONFLUENCE_READ_ONLY;
-
-  if (envDomain && envToken) {
-    const authType = normalizeAuthType(envAuthType, Boolean(envEmail));
+  const envForceCloud = process.env.CONFLUENCE_FORCE_CLOUD;
+  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 authType = normalizeAuthType(inferredAuthType, Boolean(envEmail));
     let apiPath;
 
     try {
@@ -488,9 +680,18 @@ 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.'));
+    const authErrors = validateAuthConfig(
+      { authType, token: envToken, email: envEmail, 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);
     }
 
@@ -498,10 +699,12 @@ function getConfig(profileName) {
       domain: envDomain.trim(),
       protocol: normalizeProtocol(envProtocol),
       apiPath,
-      token: envToken.trim(),
+      token: envToken ? envToken.trim() : undefined,
       email: envEmail ? envEmail.trim() : undefined,
       authType,
-      readOnly: envReadOnly === 'true'
+      mtls: envMtls,
+      readOnly: envReadOnly === 'true',
+      forceCloud: envForceCloud === 'true'
     };
   }
 
@@ -534,20 +737,25 @@ function getConfig(profileName) {
 
   try {
     const trimmedDomain = (storedConfig.domain || '').trim();
-    const trimmedToken = (storedConfig.token || '').trim();
+    const trimmedToken = trimOptional(storedConfig.token);
     const trimmedEmail = storedConfig.email ? storedConfig.email.trim() : undefined;
     const authType = normalizeAuthType(storedConfig.authType, Boolean(trimmedEmail));
+    const mtls = normalizeMtlsConfig(storedConfig.mtls);
     let apiPath;
 
-    if (!trimmedDomain || !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, 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);
     }
 
@@ -563,6 +771,10 @@ function getConfig(profileName) {
       ? envReadOnly === 'true'
       : Boolean(storedConfig.readOnly);
 
+    const forceCloud = envForceCloud !== undefined
+      ? envForceCloud === 'true'
+      : Boolean(storedConfig.forceCloud);
+
     return {
       domain: trimmedDomain,
       protocol: normalizeProtocol(storedConfig.protocol),
@@ -570,7 +782,9 @@ function getConfig(profileName) {
       token: trimmedToken,
       email: trimmedEmail,
       authType,
-      readOnly
+      mtls,
+      readOnly,
+      forceCloud
     };
   } catch (error) {
     console.error(chalk.red('❌ Error reading configuration file:'), error.message);

package/lib/confluence-client.js

@@ -1,5 +1,6 @@
 const axios = require('axios');
 const fs = require('fs');
+const https = require('https');
 const path = require('path');
 const FormData = require('form-data');
 const { convert } = require('html-to-text');
@@ -34,6 +35,8 @@ class ConfluenceClient {
     this.token = config.token;
     this.email = config.email;
     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' : '';
     this.baseURL = `${this.protocol}://${this.domain}${this.apiPath}`;
@@ -41,14 +44,23 @@ class ConfluenceClient {
     this.setupConfluenceMarkdownExtensions();
 
     const headers = {
-      'Content-Type': 'application/json',
-      'Authorization': this.authType === 'basic' ? this.buildBasicAuthHeader() : `Bearer ${this.token}`
+      'Content-Type': 'application/json'
     };
+    const authHeader = this.buildAuthHeader();
+    if (authHeader) {
+      headers.Authorization = authHeader;
+    }
 
-    this.client = axios.create({
+    const clientOptions = {
       baseURL: this.baseURL,
       headers
-    });
+    };
+    const httpsAgent = this.buildHttpsAgent();
+    if (httpsAgent) {
+      clientOptions.httpsAgent = httpsAgent;
+    }
+
+    this.client = axios.create(clientOptions);
 
     this.client.interceptors.response.use(
       response => response,
@@ -72,6 +84,10 @@ class ConfluenceClient {
             hints.push(
               'Please verify your username and password are correct.'
             );
+          } else if (this.authType === 'mtls') {
+            hints.push(
+              'Please verify your client certificate, client key, and CA certificate are correct and trusted by the server.'
+            );
           } else {
             hints.push(
               'Please verify your personal access token is valid and not expired.'
@@ -85,7 +101,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() {
@@ -115,6 +131,67 @@ class ConfluenceClient {
     return `Basic ${encodedCredentials}`;
   }
 
+  buildAuthHeader() {
+    if (this.authType === 'mtls') {
+      return null;
+    }
+
+    if (!this.token) {
+      throw new Error(`Authentication type "${this.authType}" requires a token or password.`);
+    }
+
+    return this.authType === 'basic' ? this.buildBasicAuthHeader() : `Bearer ${this.token}`;
+  }
+
+  buildHttpsAgent() {
+    if (this.protocol !== 'https' || !this.mtls) {
+      return null;
+    }
+
+    const options = {};
+
+    if (this.mtls.caCert) {
+      if (!fs.existsSync(this.mtls.caCert)) {
+        throw new Error(`CA certificate file not found: ${this.mtls.caCert}`);
+      }
+      options.ca = fs.readFileSync(this.mtls.caCert);
+    }
+    if (this.mtls.clientCert) {
+      if (!fs.existsSync(this.mtls.clientCert)) {
+        throw new Error(`Client certificate file not found: ${this.mtls.clientCert}`);
+      }
+      options.cert = fs.readFileSync(this.mtls.clientCert);
+    }
+    if (this.mtls.clientKey) {
+      if (!fs.existsSync(this.mtls.clientKey)) {
+        throw new Error(`Client key file not found: ${this.mtls.clientKey}`);
+      }
+      // Warn if private key file is readable by others (Unix only)
+      if (process.platform !== 'win32') {
+        try {
+          const keyStats = fs.statSync(this.mtls.clientKey);
+          const keyMode = keyStats.mode & 0o777;
+          if (keyMode & 0o077) {
+            console.error(
+              `Warning: Client key file "${this.mtls.clientKey}" has mode ${keyMode.toString(8)}. ` +
+              'Private keys should not be readable by other users (recommended: 0600). ' +
+              `Fix with: chmod 600 "${this.mtls.clientKey}"`
+            );
+          }
+        } catch {
+          // Ignore stat errors — the read below will surface them
+        }
+      }
+      options.key = fs.readFileSync(this.mtls.clientKey);
+    }
+
+    if (Object.keys(options).length === 0) {
+      return null;
+    }
+
+    return new https.Agent(options);
+  }
+
   /**
    * Extract page ID from URL or return the ID if it's already a number
    */
@@ -401,12 +478,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 };
@@ -1423,9 +1500,12 @@ class ConfluenceClient {
     // Format: <ac:link><ri:page ri:space-key="xxx" ri:content-title="Page Title" /></ac:link>
     markdown = markdown.replace(/<ac:link>\s*<ri:page[^>]*ri:content-title="([^"]*)"[^>]*\/>\s*<\/ac:link>/g, '[$1]');
     markdown = markdown.replace(/<ac:link>\s*<ri:page[^>]*ri:content-title="([^"]*)"[^>]*>\s*<\/ri:page>\s*<\/ac:link>/g, '[$1]');
-    
-    // Remove any remaining ac:link tags that weren't matched
-    markdown = markdown.replace(/<ac:link>[\s\S]*?<\/ac:link>/g, '');
+
+    // Convert internal page links with custom display text (ac:link-body)
+    markdown = markdown.replace(/<ac:link[^>]*>[\s\S]*?<ac:link-body>([\s\S]*?)<\/ac:link-body>[\s\S]*?<\/ac:link>/g, '$1');
+
+    // Remove any remaining ac:link tags that weren't matched (including those with attributes)
+    markdown = markdown.replace(/<ac:link[^>]*>[\s\S]*?<\/ac:link>/g, '');
     
     // Convert remaining HTML to markdown
     markdown = this.htmlToMarkdown(markdown);
@@ -2132,4 +2212,4 @@ ConfluenceClient.createLocalConverter = function () {
 };
 
 module.exports = ConfluenceClient;
-module.exports.NAMED_ENTITIES = NAMED_ENTITIES;
+module.exports.NAMED_ENTITIES = NAMED_ENTITIES;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "confluence-cli",
-  "version": "1.30.0",
+  "version": "1.30.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "confluence-cli",
-      "version": "1.30.0",
+      "version": "1.30.2",
       "license": "MIT",
       "dependencies": {
         "axios": "^1.15.0",
@@ -2684,9 +2684,9 @@
       "license": "ISC"
     },
     "node_modules/follow-redirects": {
-      "version": "1.15.11",
-      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
-      "integrity": "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==",
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
+      "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
       "funding": [
         {
           "type": "individual",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "1.30.0",
+  "version": "1.30.2",
   "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)