confluence-cli 1.23.0 → 1.24.0

package/.claude/skills/confluence/SKILL.md

@@ -39,8 +39,19 @@ 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 (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)
 
+**Scoped API token for agents (recommended):**
+
+```sh
+export CONFLUENCE_DOMAIN="api.atlassian.com"
+export CONFLUENCE_API_PATH="/ex/confluence/<your-cloud-id>/wiki/rest/api"
+export CONFLUENCE_AUTH_TYPE="basic"
+export CONFLUENCE_EMAIL="user@company.com"
+export CONFLUENCE_API_TOKEN="your-scoped-token"
+```
+
 ## Page ID Resolution
 
 Most commands accept `<pageId>` — a numeric ID or any of the supported URL formats below.

package/README.md

@@ -104,6 +104,17 @@ confluence init \
   --token "your-api-token"
 ```
 
+**Scoped API token** (recommended for agents — least privilege):
+```bash
+# Replace <your-cloud-id> with your actual Cloud ID
+confluence init \
+  --domain "api.atlassian.com" \
+  --api-path "/ex/confluence/<your-cloud-id>/wiki/rest/api" \
+  --auth-type "basic" \
+  --email "user@example.com" \
+  --token "your-scoped-token"
+```
+
 **Hybrid mode** (some fields provided, rest via prompts):
 ```bash
 # Domain and token provided, will prompt for auth method and email
@@ -132,6 +143,15 @@ export CONFLUENCE_API_PATH="/wiki/rest/api"         # Cloud default; use /rest/a
 export CONFLUENCE_AUTH_TYPE="basic"
 ```
 
+**Scoped API token** (recommended for agents):
+```bash
+export CONFLUENCE_DOMAIN="api.atlassian.com"
+export CONFLUENCE_API_PATH="/ex/confluence/<your-cloud-id>/wiki/rest/api"
+export CONFLUENCE_AUTH_TYPE="basic"
+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.
 
 ### Getting Your API Token
@@ -142,6 +162,17 @@ export CONFLUENCE_AUTH_TYPE="basic"
 3. Give it a label (e.g., "confluence-cli")
 4. Copy the generated token
 
+**Atlassian Cloud — Scoped API Token** (recommended for agents and automation):
+
+Scoped tokens restrict access to specific Atlassian products and permissions, following the principle of least privilege. They use a different API gateway (`api.atlassian.com`) instead of your site domain.
+
+1. Create a scoped token in your [Atlassian Admin settings](https://admin.atlassian.com)
+2. Find your Cloud ID by visiting `https://<your-site>.atlassian.net/_edge/tenant_info`
+3. Configure with:
+   - **Domain:** `api.atlassian.com`
+   - **API path:** `/ex/confluence/<your-cloud-id>/wiki/rest/api`
+   - **Auth type:** `basic` (email + scoped token)
+
 **On-premise / Data Center:** Use your Confluence username and password for basic authentication.
 
 ## Usage

package/bin/confluence.js

@@ -8,6 +8,11 @@ const { getConfig, initConfig } = require('../lib/config');
 const Analytics = require('../lib/analytics');
 const pkg = require('../package.json');
 
+function buildPageUrl(config, path) {
+  const protocol = config.protocol || 'https';
+  return `${protocol}://${config.domain}${path}`;
+}
+
 program
   .name('confluence')
   .description('CLI tool for Atlassian Confluence')
@@ -18,6 +23,7 @@ program
   .command('init')
   .description('Initialize Confluence CLI configuration')
   .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('-e, --email <email>', 'Email or username for basic auth')
@@ -217,7 +223,7 @@ program
       console.log(`Title: ${chalk.blue(result.title)}`);
       console.log(`ID: ${chalk.blue(result.id)}`);
       console.log(`Space: ${chalk.blue(result.space.name)} (${result.space.key})`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
+      console.log(`URL: ${chalk.gray(`${buildPageUrl(config, `/wiki${result._links.webui}`)}`)}`);
       
       analytics.track('create', true);
     } catch (error) {
@@ -265,7 +271,7 @@ program
       console.log(`ID: ${chalk.blue(result.id)}`);
       console.log(`Parent: ${chalk.blue(parentInfo.title)} (${parentId})`);
       console.log(`Space: ${chalk.blue(result.space.name)} (${result.space.key})`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
+      console.log(`URL: ${chalk.gray(`${buildPageUrl(config, `/wiki${result._links.webui}`)}`)}`);
       
       analytics.track('create_child', true);
     } catch (error) {
@@ -312,7 +318,7 @@ program
       console.log(`Title: ${chalk.blue(result.title)}`);
       console.log(`ID: ${chalk.blue(result.id)}`);
       console.log(`Version: ${chalk.blue(result.version.number)}`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
+      console.log(`URL: ${chalk.gray(`${buildPageUrl(config, `/wiki${result._links.webui}`)}`)}`);
       
       analytics.track('update', true);
     } catch (error) {
@@ -339,7 +345,7 @@ program
       console.log(`ID: ${chalk.blue(result.id)}`);
       console.log(`New Parent: ${chalk.blue(newParentId)}`);
       console.log(`Version: ${chalk.blue(result.version.number)}`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result._links.webui}`)}`);
+      console.log(`URL: ${chalk.gray(`${buildPageUrl(config, `/wiki${result._links.webui}`)}`)}`);
 
       analytics.track('move', true);
     } catch (error) {
@@ -445,7 +451,7 @@ program
       console.log(`Title: ${chalk.green(pageInfo.title)}`);
       console.log(`ID: ${chalk.green(pageInfo.id)}`);
       console.log(`Space: ${chalk.green(pageInfo.space.name)} (${pageInfo.space.key})`);
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${pageInfo.url}`)}`);
+      console.log(`URL: ${chalk.gray(`${buildPageUrl(config, `/wiki${pageInfo.url}`)}`)}`);
       
       analytics.track('find', true);
     } catch (error) {
@@ -1467,7 +1473,7 @@ program
           console.log(` - ...and ${result.failures.length - 10} more`);
         }
       }
-      console.log(`URL: ${chalk.gray(`https://${config.domain}/wiki${result.rootPage._links.webui}`)}`);
+      console.log(`URL: ${chalk.gray(`${buildPageUrl(config, `/wiki${result.rootPage._links.webui}`)}`)}`);
       if (options.failOnError && result.failures?.length) {
         analytics.track('copy_tree', false);
         console.error(chalk.red('Completed with failures and --fail-on-error is set.'));
@@ -1529,7 +1535,7 @@ program
             type: page.type,
             status: page.status,
             spaceKey: page.space?.key,
-            url: `https://${config.domain}/wiki/spaces/${page.space?.key}/pages/${page.id}`,
+            url: `${buildPageUrl(config, `/wiki/spaces/${page.space?.key}/pages/${page.id}`)}`,
             parentId: page.parentId || resolvedPageId
           }))
         };
@@ -1558,7 +1564,7 @@ program
           }
           
           if (options.showUrl) {
-            const url = `https://${config.domain}/wiki/spaces/${page.space?.key}/pages/${page.id}`;
+            const url = `${buildPageUrl(config, `/wiki/spaces/${page.space?.key}/pages/${page.id}`)}`;
             output += `\n   ${chalk.gray(url)}`;
           }
           
@@ -1623,7 +1629,7 @@ function printTree(nodes, config, options, depth = 1) {
     }
     
     if (options.showUrl) {
-      const url = `https://${config.domain}/wiki/spaces/${node.space?.key}/pages/${node.id}`;
+      const url = `${buildPageUrl(config, `/wiki/spaces/${node.space?.key}/pages/${node.id}`)}`;
       output += `\n${indent}${isLast ? '    ' : '│   '}${chalk.gray(url)}`;
     }
     

package/lib/config.js

@@ -19,6 +19,19 @@ const requiredInput = (label) => (input) => {
   return true;
 };
 
+const PROTOCOL_CHOICES = [
+  { name: 'HTTPS (recommended)', value: 'https' },
+  { name: 'HTTP', value: 'http' }
+];
+
+const normalizeProtocol = (rawValue) => {
+  const normalized = (rawValue || '').trim().toLowerCase();
+  if (normalized === 'http' || normalized === 'https') {
+    return normalized;
+  }
+  return 'https';
+};
+
 const normalizeAuthType = (rawValue, hasEmail) => {
   const normalized = (rawValue || '').trim().toLowerCase();
   if (normalized === 'basic' || normalized === 'bearer') {
@@ -84,6 +97,10 @@ const validateCliOptions = (options) => {
     }
   }
 
+  if (options.protocol && !['http', 'https'].includes(options.protocol.toLowerCase())) {
+    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"');
   }
@@ -105,6 +122,7 @@ const saveConfig = (configData) => {
 
   const config = {
     domain: configData.domain.trim(),
+    protocol: normalizeProtocol(configData.protocol),
     apiPath: normalizeApiPath(configData.apiPath, configData.domain),
     token: configData.token.trim(),
     authType: configData.authType,
@@ -122,6 +140,17 @@ const saveConfig = (configData) => {
 const promptForMissingValues = async (providedValues) => {
   const questions = [];
 
+  // Protocol question
+  if (!providedValues.protocol) {
+    questions.push({
+      type: 'list',
+      name: 'protocol',
+      message: 'Protocol:',
+      choices: PROTOCOL_CHOICES,
+      default: 'https'
+    });
+  }
+
   // Domain question
   if (!providedValues.domain) {
     questions.push({
@@ -205,6 +234,7 @@ const promptForMissingValues = async (providedValues) => {
 async function initConfig(cliOptions = {}) {
   // Extract provided values from CLI options
   const providedValues = {
+    protocol: cliOptions.protocol,
     domain: cliOptions.domain,
     apiPath: cliOptions.apiPath,
     authType: cliOptions.authType,
@@ -221,6 +251,13 @@ async function initConfig(cliOptions = {}) {
     console.log('Please provide your Confluence connection details:\n');
 
     const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'protocol',
+        message: 'Protocol:',
+        choices: PROTOCOL_CHOICES,
+        default: 'https'
+      },
       {
         type: 'input',
         name: 'domain',
@@ -318,6 +355,7 @@ async function initConfig(cliOptions = {}) {
 
       const configData = {
         domain: normalizedDomain,
+        protocol: normalizeProtocol(providedValues.protocol),
         apiPath: providedValues.apiPath || inferApiPath(normalizedDomain),
         token: providedValues.token,
         authType: normalizedAuthType,
@@ -355,6 +393,7 @@ function getConfig() {
   const envEmail = process.env.CONFLUENCE_EMAIL || process.env.CONFLUENCE_USERNAME;
   const envAuthType = process.env.CONFLUENCE_AUTH_TYPE;
   const envApiPath = process.env.CONFLUENCE_API_PATH;
+  const envProtocol = process.env.CONFLUENCE_PROTOCOL;
 
   if (envDomain && envToken) {
     const authType = normalizeAuthType(envAuthType, Boolean(envEmail));
@@ -375,6 +414,7 @@ function getConfig() {
 
     return {
       domain: envDomain.trim(),
+      protocol: normalizeProtocol(envProtocol),
       apiPath,
       token: envToken.trim(),
       email: envEmail ? envEmail.trim() : undefined,
@@ -385,7 +425,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 (or CONFLUENCE_PASSWORD), CONFLUENCE_EMAIL (or CONFLUENCE_USERNAME), 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, CONFLUENCE_PROTOCOL.'));
     process.exit(1);
   }
 
@@ -419,6 +459,7 @@ function getConfig() {
 
     return {
       domain: trimmedDomain,
+      protocol: normalizeProtocol(storedConfig.protocol),
       apiPath,
       token: trimmedToken,
       email: trimmedEmail,

package/lib/confluence-client.js

@@ -29,11 +29,13 @@ const NAMED_ENTITIES = {
 class ConfluenceClient {
   constructor(config) {
     this.domain = config.domain;
+    const rawProtocol = (config.protocol || 'https').trim().toLowerCase();
+    this.protocol = (rawProtocol === 'http' || rawProtocol === 'https') ? rawProtocol : 'https';
     this.token = config.token;
     this.email = config.email;
     this.authType = (config.authType || (this.email ? 'basic' : 'bearer')).toLowerCase();
     this.apiPath = this.sanitizeApiPath(config.apiPath);
-    this.baseURL = `https://${this.domain}${this.apiPath}`;
+    this.baseURL = `${this.protocol}://${this.domain}${this.apiPath}`;
     this.markdown = new MarkdownIt();
     this.setupConfluenceMarkdownExtensions();
 
@@ -368,7 +370,7 @@ class ConfluenceClient {
         const webui = page._links?.webui || '';
         return {
           title: page.title,
-          url: webui ? `https://${this.domain}/wiki${webui}` : ''
+          url: webui ? this.buildUrl(`/wiki${webui}`) : ''
         };
       }
       return null;
@@ -462,7 +464,7 @@ class ConfluenceClient {
       // Format: - [Page Title](URL)
       const childPagesList = childPages.map(page => {
         const webui = page._links?.webui || '';
-        const url = webui ? `https://${this.domain}/wiki${webui}` : '';
+        const url = webui ? this.buildUrl(`/wiki${webui}`) : '';
         if (url) {
           return `- [${page.title}](${url})`;
         } else {
@@ -1294,11 +1296,11 @@ class ConfluenceClient {
       // Try to build a proper URL - if spaceKey starts with ~, it's a user space
       if (spaceKey.startsWith('~')) {
         const spacePath = `display/${spaceKey}/${encodeURIComponent(title)}`;
-        return `\n> 📄 **${labels.includePage}**: [${title}](https://${this.domain}/wiki/${spacePath})\n`;
+        return `\n> 📄 **${labels.includePage}**: [${title}](${this.buildUrl(`/wiki/${spacePath}`)})\n`;
       } else {
         // For non-user spaces, we cannot construct a valid link without the page ID.
         // Document that manual correction is required.
-        return `\n> 📄 **${labels.includePage}**: [${title}](https://${this.domain}/wiki/spaces/${spaceKey}/pages/[PAGE_ID_HERE]) _(manual link correction required)_\n`;
+        return `\n> 📄 **${labels.includePage}**: [${title}](${this.buildUrl(`/wiki/spaces/${spaceKey}/pages/[PAGE_ID_HERE]`)}) _(manual link correction required)_\n`;
       }
     });
     
@@ -2005,6 +2007,11 @@ class ConfluenceClient {
     };
   }
 
+  buildUrl(path) {
+    const normalized = path && !path.startsWith('/') ? `/${path}` : (path || '');
+    return `${this.protocol}://${this.domain}${normalized}`;
+  }
+
   toAbsoluteUrl(pathOrUrl) {
     if (!pathOrUrl) {
       return null;
@@ -2014,8 +2021,7 @@ class ConfluenceClient {
       return pathOrUrl;
     }
 
-    const normalized = pathOrUrl.startsWith('/') ? pathOrUrl : `/${pathOrUrl}`;
-    return `https://${this.domain}${normalized}`;
+    return this.buildUrl(pathOrUrl);
   }
 
   parseNextStart(nextLink) {

package/package.json

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