confluence-cli 1.26.0 → 1.27.0

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

@@ -25,6 +25,18 @@ confluence --version   # verify install
 | `CONFLUENCE_AUTH_TYPE` | `basic` or `bearer` | `basic` |
 | `CONFLUENCE_EMAIL` | Email address (basic auth only) | `user@company.com` |
 | `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` |
+
+**Global `--profile` flag (use a named profile for any command):**
+
+```sh
+confluence --profile <name> <command>
+```
+
+Config resolution works in two stages:
+- **Direct env config:** If both `CONFLUENCE_DOMAIN` and `CONFLUENCE_API_TOKEN` are set, they are used directly and the config file / profiles are not consulted.
+- **Profile-based config:** Otherwise, a profile is selected in this order: `--profile` flag > `CONFLUENCE_PROFILE` env > `activeProfile` in config > `default`.
 
 **Non-interactive init (good for CI/CD scripts):**
 
@@ -52,6 +64,27 @@ export CONFLUENCE_EMAIL="user@company.com"
 export CONFLUENCE_API_TOKEN="your-scoped-token"
 ```
 
+**Read-only mode (recommended for AI agents):**
+
+Prevents all write operations (create, update, delete, move, etc.) at the profile level. Useful when giving an AI agent access to Confluence for reading only.
+
+```sh
+# Via profile flag
+confluence profile add agent --domain "company.atlassian.net" --token "xxx" --read-only
+
+# Via environment variable (overrides config file)
+export CONFLUENCE_READ_ONLY=true
+```
+
+When read-only mode is active, any write command exits with an error:
+```
+Error: This profile is in read-only mode. Write operations are not allowed.
+```
+
+`profile list` shows read-only profiles with a `[read-only]` badge.
+
+---
+
 ## Page ID Resolution
 
 Most commands accept `<pageId>` — a numeric ID or any of the supported URL formats below.
@@ -91,10 +124,14 @@ confluence read "https://company.atlassian.net/wiki/spaces/MYSPACE/pages/1234567
 Initialize configuration. Saves credentials to `~/.confluence-cli/config.json`.
 
 ```sh
-confluence init [--domain <domain>] [--api-path <path>] [--auth-type basic|bearer] [--email <email>] [--token <token>]
+confluence init [--domain <domain>] [--api-path <path>] [--auth-type basic|bearer] [--email <email>] [--token <token>] [--read-only]
 ```
 
-All flags are optional; omitting any flag triggers an interactive prompt for that field. Provide all flags to run fully non-interactive.
+All flags are optional; omitting any flag triggers an interactive prompt for that field. Provide all flags to run fully non-interactive. Use the global `--profile` flag to save to a named profile:
+
+```sh
+confluence --profile staging init --domain "staging.example.com" --auth-type bearer --token "your-token"
+```
 
 ---
 
@@ -520,6 +557,60 @@ confluence copy-tree 123456789 987654321 --exclude "Draft*,Archive*"
 
 ---
 
+### `profile list`
+
+List all configuration profiles with the active profile marked.
+
+```sh
+confluence profile list
+```
+
+---
+
+### `profile use <name>`
+
+Switch the active configuration profile.
+
+```sh
+confluence profile use <name>
+```
+
+```sh
+confluence profile use staging
+```
+
+---
+
+### `profile add <name>`
+
+Add a new configuration profile. Supports the same options as `init` (interactive, non-interactive, or hybrid).
+
+```sh
+confluence profile add <name> [--domain <domain>] [--api-path <path>] [--auth-type basic|bearer] [--email <email>] [--token <token>] [--protocol http|https] [--read-only]
+```
+
+Profile names may contain letters, numbers, hyphens, and underscores only.
+
+```sh
+confluence profile add staging --domain "staging.example.com" --auth-type bearer --token "xyz"
+```
+
+---
+
+### `profile remove <name>`
+
+Remove a configuration profile (prompts for confirmation). Cannot remove the only remaining profile.
+
+```sh
+confluence profile remove <name>
+```
+
+```sh
+confluence profile remove staging
+```
+
+---
+
 ### `stats`
 
 Show local usage statistics.
@@ -614,6 +705,8 @@ confluence search "release notes" --limit 20
 - **ANSI color codes**: stdout may contain ANSI escape sequences. Pipe through `| cat` or use `NO_COLOR=1` if your downstream tool doesn't handle them.
 - **Page ID vs URL**: when you have a Confluence URL, extract `?pageId=<number>` and pass the number. Do not pass pretty/display URLs — they are not supported.
 - **Cross-space moves**: `confluence move` only works within the same space. Moving across spaces is not supported.
+- **Multiple instances**: Use `--profile <name>` or `CONFLUENCE_PROFILE` env var to target different Confluence instances without reconfiguring.
+- **Read-only mode**: Set `CONFLUENCE_READ_ONLY=true` or use `--read-only` when creating profiles to prevent accidental writes. This is enforced at the CLI level — all write commands will be blocked.
 
 ## Error Patterns
 
@@ -624,3 +717,6 @@ confluence search "release notes" --limit 20
 | 400 on inline comment creation | Editor metadata required | Use `--location footer` or reply to existing inline comment with `--parent` |
 | `File not found: <path>` | `--file` path doesn't exist | Check the path before calling the command |
 | `At least one of --title, --file, or --content must be provided` | `update` called with no content options | Provide at least one of the required options |
+| `Profile "<name>" not found!` | Specified profile doesn't exist | Run `confluence profile list` to see available profiles |
+| `Cannot delete the only remaining profile.` | Tried to remove the last profile | Add another profile before removing |
+| `This profile is in read-only mode` | Write command used with a read-only profile | Use a writable profile or remove `readOnly` from config |

package/README.md

@@ -16,6 +16,8 @@ A powerful command-line interface for Atlassian Confluence that allows you to re
 - 💬 **Comments** - List, create, and delete page comments (footer or inline)
 - 📦 **Export** - Save a page and its attachments to a local folder
 - 🛠️ **Edit workflow** - Export page content for editing and re-import
+- 🔀 **Profiles** - Manage multiple Confluence instances with named configuration profiles
+- 🔒 **Read-only mode** - Profile-level write protection for safe AI agent usage
 - 🔧 **Easy setup** - Simple configuration with environment variables or interactive setup
 
 ## Installation
@@ -115,6 +117,15 @@ confluence init \
   --token "your-scoped-token"
 ```
 
+**Named profile** (save to a specific profile):
+```bash
+confluence --profile staging init \
+  --domain "staging.example.com" \
+  --api-path "/rest/api" \
+  --auth-type "bearer" \
+  --token "your-personal-access-token"
+```
+
 **Hybrid mode** (some fields provided, rest via prompts):
 ```bash
 # Domain and token provided, will prompt for auth method and email
@@ -130,6 +141,7 @@ confluence init --email "user@example.com" --token "your-api-token"
 - `-a, --auth-type <type>` - Authentication type: `basic` or `bearer`
 - `-e, --email <email>` - Email or username for basic authentication
 - `-t, --token <token>` - API token or password
+- `--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.
 
@@ -141,6 +153,8 @@ export CONFLUENCE_EMAIL="your.email@example.com"  # required for basic auth (ali
 export CONFLUENCE_API_PATH="/wiki/rest/api"         # Cloud default; use /rest/api for Server/DC
 # Optional: set to 'bearer' for self-hosted/Data Center instances
 export CONFLUENCE_AUTH_TYPE="basic"
+# Optional: select a named profile (overridden by --profile flag)
+export CONFLUENCE_PROFILE="default"
 ```
 
 **Scoped API token** (recommended for agents):
@@ -154,6 +168,12 @@ 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.
 
+**Read-only mode** (recommended for AI agents):
+```bash
+export CONFLUENCE_READ_ONLY=true
+```
+When set, all write operations (`create`, `update`, `delete`, etc.) are blocked at the CLI level. The environment variable overrides the profile's `readOnly` setting.
+
 ### Getting Your API Token
 
 **Atlassian Cloud:**
@@ -434,6 +454,52 @@ vim ./page-to-edit.xml
 confluence update 123456789 --file ./page-to-edit.xml --format storage
 ```
 
+### Profile Management
+```bash
+# List all profiles and see which is active
+confluence profile list
+
+# Switch the active profile
+confluence profile use staging
+
+# Add a new profile interactively
+confluence profile add staging
+
+# Add a new profile non-interactively
+confluence profile add staging --domain "staging.example.com" --auth-type bearer --token "xyz"
+
+# Add a read-only profile (blocks all write operations)
+confluence profile add agent --domain "company.atlassian.net" --auth-type basic --email "bot@example.com" --token "xyz" --read-only
+
+# Remove a profile
+confluence profile remove staging
+
+# Use a specific profile for a single command
+confluence --profile staging spaces
+```
+
+### Read-Only Mode
+
+Read-only mode blocks all write operations at the CLI level, making it safe to hand the tool to AI agents (Claude Code, Copilot, etc.) without risking accidental edits.
+
+**Enable via profile:**
+```bash
+# During init
+confluence init --read-only
+
+# When adding a profile
+confluence profile add agent --domain "company.atlassian.net" --token "xyz" --read-only
+```
+
+**Enable via environment variable:**
+```bash
+export CONFLUENCE_READ_ONLY=true   # overrides profile setting
+```
+
+When read-only mode is active, any write command (`create`, `create-child`, `update`, `delete`, `move`, `edit`, `comment`, `attachment-upload`, `attachment-delete`, `property-set`, `property-delete`, `comment-delete`, `copy-tree`) exits with code 1 and prints an error message.
+
+`confluence profile list` shows a `[read-only]` badge next to protected profiles.
+
 ### View Usage Statistics
 ```bash
 confluence stats
@@ -443,7 +509,7 @@ confluence stats
 
 | Command | Description | Options |
 |---|---|---|
-| `init` | Initialize CLI configuration | |
+| `init` | Initialize CLI configuration | `--read-only` |
 | `read <pageId_or_url>` | Read page content | `--format <html\|text\|markdown>` |
 | `info <pageId_or_url>` | Get page information | |
 | `search <query>` | Search for pages | `--limit <number>` |
@@ -468,8 +534,14 @@ confluence stats
 | `property-set <pageId_or_url> <key>` | Set a content property (create or update) | `--value <json>`, `--file <path>`, `--format <text\|json>` |
 | `property-delete <pageId_or_url> <key>` | Delete a content property by key | `--yes` |
 | `export <pageId_or_url>` | Export a page to a directory with its attachments | `--format <html\|text\|markdown>`, `--dest <directory>`, `--file <filename>`, `--attachments-dir <name>`, `--pattern <glob>`, `--referenced-only`, `--skip-attachments` |
+| `profile list` | List all configuration profiles | |
+| `profile use <name>` | Set the active configuration profile | |
+| `profile add <name>` | Add a new configuration profile | `-d, --domain`, `-p, --api-path`, `-a, --auth-type`, `-e, --email`, `-t, --token`, `--protocol`, `--read-only` |
+| `profile remove <name>` | Remove a configuration profile | |
 | `stats` | View your usage statistics | |
 
+**Global option:** `--profile <name>` — Use a specific profile for any command (overrides `CONFLUENCE_PROFILE` env var and active profile).
+
 ## Examples
 
 ```bash
@@ -503,6 +575,11 @@ confluence attachment-delete 123456789 998877 --yes
 
 # View usage statistics
 confluence stats
+
+# Profile management
+confluence profile list
+confluence profile use staging
+confluence --profile staging spaces
 ```
 
 ## Development

package/bin/confluence.js

@@ -13,6 +13,14 @@ function buildPageUrl(config, path) {
   return `${protocol}://${config.domain}${path}`;
 }
 
+function assertWritable(config) {
+  if (config.readOnly) {
+    console.error(chalk.red('Error: This profile is in read-only mode. Write operations are not allowed.'));
+    console.error(chalk.yellow('Tip: Use "confluence profile add <name>" without --read-only, or set readOnly to false in config.'));
+    process.exit(1);
+  }
+}
+
 program
   .name('confluence')
   .description('CLI tool for Atlassian Confluence')
@@ -34,6 +42,7 @@ program
   .option('-a, --auth-type <type>', 'Authentication type (basic or bearer)')
   .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
+  .option('--read-only', 'Set profile to read-only mode (blocks write operations)')
   .action(async (options) => {
     const profile = getProfileName();
     await initConfig({ ...options, profile });
@@ -208,8 +217,9 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
-      
+
       let content = '';
       
       if (options.file) {
@@ -251,8 +261,9 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
-      
+
       // Get parent page info to get space key
       const parentInfo = await client.getPageInfo(parentId);
       const spaceKey = parentInfo.space.key;
@@ -305,8 +316,9 @@ program
       }
 
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
-      
+
       let content = null; // Use null to indicate no content change
       
       if (options.file) {
@@ -344,6 +356,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
       const result = await client.movePage(pageId, newParentId, options.title);
 
@@ -371,6 +384,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
       const pageInfo = await client.getPageInfo(pageIdOrUrl);
 
@@ -414,6 +428,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
       const pageData = await client.getPageForEdit(pageId);
       
@@ -613,6 +628,7 @@ program
       const fs = require('fs');
       const path = require('path');
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
 
       const resolvedFiles = files.map((filePath) => ({
@@ -660,6 +676,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
 
       if (!options.yes) {
@@ -810,6 +827,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
 
       if (!options.value && !options.file) {
@@ -866,6 +884,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
 
       if (!options.yes) {
@@ -1067,6 +1086,7 @@ program
     let location = null;
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
 
       let content = '';
@@ -1181,6 +1201,7 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
 
       if (!options.yes) {
@@ -1599,8 +1620,9 @@ program
     const analytics = new Analytics();
     try {
       const config = getConfig(getProfileName());
+      assertWritable(config);
       const client = new ConfluenceClient(config);
-      
+
       // Parse numeric flags with safe fallbacks
       const parsedDepth = parseInt(options.maxDepth, 10);
       const maxDepth = Number.isNaN(parsedDepth) ? 10 : parsedDepth;
@@ -1876,7 +1898,8 @@ profileCmd
     console.log(chalk.blue('Configuration profiles:\n'));
     profiles.forEach(p => {
       const marker = p.active ? chalk.green(' (active)') : '';
-      console.log(`  ${p.active ? chalk.green('*') : ' '} ${chalk.cyan(p.name)}${marker} - ${chalk.gray(p.domain)}`);
+      const readOnlyBadge = p.readOnly ? chalk.red(' [read-only]') : '';
+      console.log(`  ${p.active ? chalk.green('*') : ' '} ${chalk.cyan(p.name)}${marker}${readOnlyBadge} - ${chalk.gray(p.domain)}`);
     });
   });
 
@@ -1902,6 +1925,7 @@ profileCmd
   .option('-a, --auth-type <type>', 'Authentication type (basic or bearer)')
   .option('-e, --email <email>', 'Email or username for basic auth')
   .option('-t, --token <token>', 'API token')
+  .option('--read-only', 'Set profile to read-only mode (blocks write operations)')
   .action(async (name, options) => {
     if (!isValidProfileName(name)) {
       console.error(chalk.red('Invalid profile name. Use only letters, numbers, hyphens, and underscores.'));
@@ -1943,6 +1967,7 @@ module.exports = {
     uniquePathFor,
     exportRecursive,
     sanitizeTitle,
+    assertWritable,
   },
 };
 

package/lib/config.js

@@ -172,6 +172,10 @@ const saveConfig = (configData, profileName) => {
     config.email = configData.email.trim();
   }
 
+  if (configData.readOnly) {
+    config.readOnly = true;
+  }
+
   // Read existing config file (or create new structure)
   const fileData = readConfigFile() || { activeProfile: DEFAULT_PROFILE, profiles: {} };
 
@@ -297,6 +301,8 @@ async function initConfig(cliOptions = {}) {
     process.exit(1);
   }
 
+  const readOnly = cliOptions.readOnly || false;
+
   // Extract provided values from CLI options
   const providedValues = {
     protocol: cliOptions.protocol,
@@ -375,7 +381,7 @@ async function initConfig(cliOptions = {}) {
       }
     ]);
 
-    saveConfig(answers, profileName);
+    saveConfig({ ...answers, readOnly }, profileName);
     return;
   }
 
@@ -427,7 +433,8 @@ async function initConfig(cliOptions = {}) {
         apiPath: providedValues.apiPath || inferApiPath(normalizedDomain),
         token: providedValues.token,
         authType: normalizedAuthType,
-        email: providedValues.email
+        email: providedValues.email,
+        readOnly
       };
 
       saveConfig(configData, profileName);
@@ -451,7 +458,7 @@ async function initConfig(cliOptions = {}) {
     // Normalize auth type
     mergedValues.authType = normalizeAuthType(mergedValues.authType, Boolean(mergedValues.email));
 
-    saveConfig(mergedValues, profileName);
+    saveConfig({ ...mergedValues, readOnly }, profileName);
   } catch (error) {
     console.error(chalk.red(`❌ ${error.message}`));
     process.exit(1);
@@ -465,6 +472,7 @@ function getConfig(profileName) {
   const envAuthType = process.env.CONFLUENCE_AUTH_TYPE;
   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));
@@ -489,7 +497,8 @@ function getConfig(profileName) {
       apiPath,
       token: envToken.trim(),
       email: envEmail ? envEmail.trim() : undefined,
-      authType
+      authType,
+      readOnly: envReadOnly === 'true'
     };
   }
 
@@ -547,13 +556,18 @@ function getConfig(profileName) {
       process.exit(1);
     }
 
+    const readOnly = envReadOnly !== undefined
+      ? envReadOnly === 'true'
+      : Boolean(storedConfig.readOnly);
+
     return {
       domain: trimmedDomain,
       protocol: normalizeProtocol(storedConfig.protocol),
       apiPath,
       token: trimmedToken,
       email: trimmedEmail,
-      authType
+      authType,
+      readOnly
     };
   } catch (error) {
     console.error(chalk.red('❌ Error reading configuration file:'), error.message);
@@ -572,7 +586,8 @@ function listProfiles() {
     profiles: Object.keys(fileData.profiles).map(name => ({
       name,
       active: name === fileData.activeProfile,
-      domain: fileData.profiles[name].domain
+      domain: fileData.profiles[name].domain,
+      readOnly: Boolean(fileData.profiles[name].readOnly)
     }))
   };
 }

package/package.json

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