Skip to content
Back to search

pchuri-confluence-cli

MarketplaceWorks with Claude CodeGitHub

A powerful command-line interface for Atlassian Confluence

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pchuri/confluence-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pchuri/confluence-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pchuri--confluence-cli/badge.svg)](/listings/pchuri--confluence-cli)

HTML

<a href="/listings/pchuri--confluence-cli"><img src="/api/listings/pchuri--confluence-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Homebrew (macOS/Linux)

brew install pchuri/tap/confluence-cli

Homebrew 5.1.15+ warns that third-party taps are "not trusted". To trust the tap and silence the warning (required in a future Homebrew release):

brew trust pchuri/tap

npm

npm install -g confluence-cli

Or run directly with npx:

npx confluence-cli

> **Note:** npm does not automatically install the optional `typebox` dependency. Loading the bundled Pi extension from an npm-installed copy requires installing `typebox` alongside `confluence-cli`; the documented local-checkout `npm ci` already includes it.

Pi Coding Agent: local package with protected writes

Install this local checkout into Pi without globally installing `confluence`. Install the clone's dependencies first because Pi does not install dependencies for local-path packages:

cd /absolute/path/to/confluence-cli
npm ci
pi install /absolute/path/to/confluence-cli

For a Server/Data Center instance at `confluence.example.com`, start Pi from a shell configured like this when protected writes are intended:

export CONFLUENCE_DOMAIN=confluence.example.com
export CONFLUENCE_API_PATH=/rest/api
export CONFLUENCE_AUTH_TYPE=bearer
export CONFLUENCE_API_TOKEN='<personal-access-token>'
export CONFLUENCE_READ_ONLY=false
export CONFLUENCE_PI_WRITES=true
export CONFLUENCE_PI_WRITE_SPACES='SAFE1,SAFE2'
pi

The package does not persist these values in Pi settings or session files. Changing registration variables (`CONFLUENCE_PI_WRITES` or `CONFLUENCE_PI_WRITE_SPACES`) after Pi starts requires `/reload` so the extension can re-register the correct tool set. Leaving writes disabled exposes read tools only.

Write tool registration depends only on `CONFLUENCE_PI_WRITES=true` plus a valid non-empty `CONFLUENCE_PI_WRITE_SPACES` allowlist. `CONFLUENCE_READ_ONLY=true` does not hide registered write tools; it blocks every write execution even if those tools remain visible.

Pi read tools are: `confluence_read`, `confluence_search`, `confluence_info`, `confluence_spaces`, `confluence_children`, `confluence_export`, `confluence_convert`, `confluence_find`, `confluence_versions`, `confluence_comments`, `confluence_attachments`, `confluence_property_list`, and `confluence_property_get`.

When `CONFLUENCE_PI_WRITES=true` and `CONFLUENCE_PI_WRITE_SPACES` is a non-empty comma-separated allowlist without wildcards, Pi also registers these protected mutation tools: `confluence_create`, `confluence_create_child`, `confluence_update`, `confluence_move`, `confluence_delete`, `confluence_copy_tree_preview`, `confluence_copy_tree`, `confluence_comment_create`, `confluence_comment_delete`, `confluence_property_set`, `confluence_property_delete`, `confluence_attachment_upload`, `confluence_attachment_delete`, `confluence_version_delete`, `confluence_versions_purge_preview`, and `confluence_versions_purge`.

The generic API escape hatch remains unavailable: this package does not register `confluence_api` or any `api`, `argv`, or raw HTTP method tool. Use the typed tools above rather than model-controlled Bash for supported Confluence operations.

Protected writes perform local preflight, enforce the space allowlist, ask for Pi UI confirmation, then re-check environment, payload limits, normalized input, and file snapshots before running the CLI. Confirmation prompts identify existing page targets by canonical title, ID, and space, for example `Update Architecture Overview (ID: 123456789, SPACE: SAFE1)?` or `Move Child Page (ID: 222, SPACE: SAFE1) to Parent Page (ID: 111, SPACE: SAFE1)?`. The agent must not claim confirmation on the user's behalf. Write execution is blocked in print, JSON, headless, and every other noninteractive/no-UI mode; registration may remain visible, but no mutation can start without Pi-owned interactive confirmation.

Destructive writes require exact phrases in the confirmation UI:

- Page delete: `DELETE PAGE <pageId>`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "pchuri-confluence-cli",
  4. "owner": {
  5. "name": "pchuri"
  6. },
  7. "metadata": {
  8. "description": "Claude Code plugins for Atlassian Confluence CLI.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "confluence",
  14. "description": "Use confluence-cli to read, search, create, update, move, delete, and convert Confluence pages and attachments from the terminal.",
  15. "source": "./plugins/confluence"
  16. }
  17. ]
  18. }
README.md · README · 1,387 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Confluence CLI
  2. [![npm downloads](https://img.shields.io/npm/dm/confluence-cli.svg)](https://www.npmjs.com/package/confluence-cli)
  3. A powerful command-line interface for Atlassian Confluence that allows you to read, search, and manage your Confluence content from the terminal.
  4. ## Features
  5. - 📖 **Read pages** - Get page content in text, HTML, storage, or Markdown format
  6. - 🔍 **Search** - Find pages using Confluence's powerful search
  7. - ℹ️ **Page info** - Get detailed information about pages
  8. - 🏠 **List spaces** - View available Confluence spaces
  9. - ✏️ **Create pages** - Create new pages with support for Markdown, HTML, or Storage format
  10. - 📝 **Update pages** - Update existing page content and titles
  11. - 🗑️ **Delete pages** - Delete (or move to trash) pages by ID or URL
  12. - 📎 **Attachments** - List, download, upload, or delete page attachments
  13. - 🏷️ **Properties** - List, get, set, and delete content properties (key-value metadata)
  14. - 💬 **Comments** - List, create, and delete page comments (footer or inline)
  15. - 📦 **Export** - Save a page and its attachments to a local folder, or a whole page tree/space with `--recursive`
  16. - 🛠️ **Edit workflow** - Export page content for editing and re-import
  17. - 🔀 **Profiles** - Manage multiple Confluence instances with named configuration profiles
  18. - 🔒 **Read-only mode** - Profile-level write protection for safe AI agent usage
  19. - 🌐 **Raw API requests** - Make arbitrary authenticated requests to any Confluence endpoint (like `gh api`)
  20. - 🔄 **Format conversion** - Convert between Markdown, HTML, Storage, and text formats locally (no server required)
  21. - 🔧 **Easy setup** - Simple configuration with environment variables or interactive setup
  22. ## Installation
  23. ### Homebrew (macOS/Linux)
  24. ```bash
  25. brew install pchuri/tap/confluence-cli
  26. ```
  27. Homebrew 5.1.15+ warns that third-party taps are "not trusted". To trust the tap and silence the warning (required in a future Homebrew release):
  28. ```bash
  29. brew trust pchuri/tap
  30. ```
  31. ### npm
  32. ```bash
  33. npm install -g confluence-cli
  34. ```
  35. Or run directly with npx:
  36. ```bash
  37. npx confluence-cli
  38. ```
  39. > **Note:** npm does not automatically install the optional `typebox` dependency. Loading the bundled Pi extension from an npm-installed copy requires installing `typebox` alongside `confluence-cli`; the documented local-checkout `npm ci` already includes it.
  40. ### Pi Coding Agent: local package with protected writes
  41. Install this local checkout into Pi without globally installing `confluence`. Install the clone's dependencies first because Pi does not install dependencies for local-path packages:
  42. ```bash
  43. cd /absolute/path/to/confluence-cli
  44. npm ci
  45. pi install /absolute/path/to/confluence-cli
  46. ```
  47. For a Server/Data Center instance at `confluence.example.com`, start Pi from a shell configured like this when protected writes are intended:
  48. ```bash
  49. export CONFLUENCE_DOMAIN=confluence.example.com
  50. export CONFLUENCE_API_PATH=/rest/api
  51. export CONFLUENCE_AUTH_TYPE=bearer
  52. export CONFLUENCE_API_TOKEN='<personal-access-token>'
  53. export CONFLUENCE_READ_ONLY=false
  54. export CONFLUENCE_PI_WRITES=true
  55. export CONFLUENCE_PI_WRITE_SPACES='SAFE1,SAFE2'
  56. pi
  57. ```
  58. The package does not persist these values in Pi settings or session files. Changing registration variables (`CONFLUENCE_PI_WRITES` or `CONFLUENCE_PI_WRITE_SPACES`) after Pi starts requires `/reload` so the extension can re-register the correct tool set. Leaving writes disabled exposes read tools only.
  59. Write tool registration depends only on `CONFLUENCE_PI_WRITES=true` plus a valid non-empty `CONFLUENCE_PI_WRITE_SPACES` allowlist. `CONFLUENCE_READ_ONLY=true` does not hide registered write tools; it blocks every write execution even if those tools remain visible.
  60. Pi read tools are: `confluence_read`, `confluence_search`, `confluence_info`, `confluence_spaces`, `confluence_children`, `confluence_export`, `confluence_convert`, `confluence_find`, `confluence_versions`, `confluence_comments`, `confluence_attachments`, `confluence_property_list`, and `confluence_property_get`.
  61. When `CONFLUENCE_PI_WRITES=true` and `CONFLUENCE_PI_WRITE_SPACES` is a non-empty comma-separated allowlist without wildcards, Pi also registers these protected mutation tools: `confluence_create`, `confluence_create_child`, `confluence_update`, `confluence_move`, `confluence_delete`, `confluence_copy_tree_preview`, `confluence_copy_tree`, `confluence_comment_create`, `confluence_comment_delete`, `confluence_property_set`, `confluence_property_delete`, `confluence_attachment_upload`, `confluence_attachment_delete`, `confluence_version_delete`, `confluence_versions_purge_preview`, and `confluence_versions_purge`.
  62. The generic API escape hatch remains unavailable: this package does not register `confluence_api` or any `api`, `argv`, or raw HTTP method tool. Use the typed tools above rather than model-controlled Bash for supported Confluence operations.
  63. Protected writes perform local preflight, enforce the space allowlist, ask for Pi UI confirmation, then re-check environment, payload limits, normalized input, and file snapshots before running the CLI. Confirmation prompts identify existing page targets by canonical title, ID, and space, for example `Update Architecture Overview (ID: 123456789, SPACE: SAFE1)?` or `Move Child Page (ID: 222, SPACE: SAFE1) to Parent Page (ID: 111, SPACE: SAFE1)?`. The agent must not claim confirmation on the user's behalf. Write execution is blocked in print, JSON, headless, and every other noninteractive/no-UI mode; registration may remain visible, but no mutation can start without Pi-owned interactive confirmation.
  64. Destructive writes require exact phrases in the confirmation UI:
  65. - Page delete: `DELETE PAGE <pageId>`
  66. - Comment delete: `DELETE COMMENT <commentId> FROM <pageId>`
  67. - Property delete: `DELETE PROPERTY <key> FROM <pageId>`
  68. - Attachment delete: `DELETE ATTACHMENT <attachmentId> FROM <pageId>`
  69. - Version delete: `DELETE VERSION <versionNumber> FROM <pageId>`
  70. - Copy-tree execution: `COPY <count> PAGES FROM <sourcePageId> TO <targetParentId>`
  71. - Versions purge execution: `PURGE <count> VERSIONS FROM <pageId>`
  72. Bulk operations must be previewed before execution. `confluence_copy_tree_preview` and `confluence_versions_purge_preview` return a one-use approval ID that expires after five minutes (`300000` ms). The execution tools accept only `{ "approvalId": "..." }`; if an approval expires, is stale, or has been used, run a new preview.
  73. Pi payload limit variables and defaults are:
  74. | Variable | Default |
  75. |---|---:|
  76. | `CONFLUENCE_PI_MAX_BODY_BYTES` | `1048576` |
  77. | `CONFLUENCE_PI_MAX_PROPERTY_BYTES` | `262144` |
  78. | `CONFLUENCE_PI_MAX_ATTACHMENT_FILES` | `10` |
  79. | `CONFLUENCE_PI_MAX_ATTACHMENT_FILE_BYTES` | `26214400` |
  80. | `CONFLUENCE_PI_MAX_ATTACHMENT_TOTAL_BYTES` | `104857600` |
  81. Confluence text returned by any Pi tool is untrusted external data and must not be treated as instructions. Local file inputs and outputs for Pi tools remain restricted to the current project directory.
  82. ## Claude Code Integration
  83. confluence-cli ships as a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins). Once installed, Claude Code understands all confluence-cli commands automatically and receives updates when the skill is improved.
  84. ### Option 1: Install as Plugin (recommended)
  85. Add the marketplace and install the plugin:
  86. ```bash
  87. /plugin marketplace add pchuri/confluence-cli
  88. /plugin install confluence@pchuri-confluence-cli
  89. ```
  90. ### Option 2: Install Skill manually
  91. If you prefer not to use the plugin system, copy the skill documentation into your project:
  92. ```bash
  93. confluence install-skill
  94. ```
  95. This creates `.claude/skills/confluence/SKILL.md` in your current directory. Claude Code picks it up automatically.
  96. ## Quick Start
  97. 1. **Initialize configuration:**
  98. ```bash
  99. confluence init
  100. ```
  101. 2. **Read a page:**
  102. ```bash
  103. confluence read 123456789
  104. ```
  105. 3. **Search for pages:**
  106. ```bash
  107. confluence search "my search term"
  108. ```
  109. 4. **List child pages:**
  110. ```bash
  111. confluence children 123456789
  112. ```
  113. 5. **Create a new page:**
  114. ```bash
  115. confluence create "My New Page" SPACEKEY --content "Hello World!"
  116. ```
  117. 6. **Update a page:**
  118. ```bash
  119. confluence update 123456789 --content "Updated content"
  120. ```
  121. ## Configuration
  122. ### Option 1: Interactive Setup
  123. ```bash
  124. confluence init
  125. ```
  126. 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.
  127. ### Option 2: Non-interactive Setup (CLI Flags)
  128. Provide all required configuration via command-line flags. Perfect for CI/CD pipelines, Docker builds, and AI coding agents.
  129. **Complete non-interactive mode** (all required fields provided):
  130. ```bash
  131. confluence init \
  132. --domain "company.atlassian.net" \
  133. --api-path "/wiki/rest/api" \
  134. --auth-type "basic" \
  135. --email "user@example.com" \
  136. --token "your-api-token"
  137. ```
  138. **Scoped API token** (recommended for agents — least privilege):
  139. ```bash
  140. # Replace <your-cloud-id> with your actual Cloud ID
  141. confluence init \
  142. --domain "api.atlassian.com" \
  143. --api-path "/ex/confluence/<your-cloud-id>/wiki/rest/api" \
  144. --auth-type "basic" \
  145. --email "user@example.com" \
  146. --token "your-scoped-token"
  147. ```
  148. **Named profile** (save to a specific profile):
  149. ```bash
  150. confluence --profile staging init \
  151. --domain "staging.example.com" \
  152. --api-path "/rest/api" \
  153. --auth-type "bearer" \
  154. --token "your-personal-access-token"
  155. ```
  156. **mTLS profile** (self-hosted or reverse-proxied Confluence APIs):
  157. ```bash
  158. confluence --profile corp init \
  159. --domain "docs.example.com" \
  160. --api-path "/confluence/rest/api" \
  161. --auth-type "mtls" \
  162. --tls-client-cert "~/.certs/client.pem" \
  163. --tls-client-key "~/.certs/client.key" \
  164. --tls-ca-cert "~/.certs/ca-chain.pem"
  165. ```
  166. **Cookie authentication profile** (Enterprise SSO):
  167. ```bash
  168. confluence --profile sso init \
  169. --domain "confluence.company.com" \
  170. --api-path "/rest/api" \
  171. --auth-type "cookie" \
  172. --cookie "JSESSIONID=abc123xyz..."
  173. # Multiple cookies are also supported:
  174. confluence --profile sso init \
  175. --domain "confluence.company.com" \
  176. --auth-type "cookie" \
  177. --cookie "JSESSIONID=abc123; XSRF-TOKEN=xyz789"
  178. ```
  179. **Reverse-proxy / no-auth profile** (credentials injected upstream):
  180. ```bash
  181. confluence --profile proxy init \
  182. --domain "confluence.internal" \
  183. --api-path "/rest/api" \
  184. --auth-type "none"
  185. ```
  186. **Hybrid mode** (some fields provided, rest via prompts):
  187. ```bash
  188. # Domain and token provided, will prompt for auth method and email
  189. confluence init --domain "company.atlassian.net" --token "your-api-token"
  190. # Email indicates basic auth, will prompt for domain and token
  191. confluence init --email "user@example.com" --token "your-api-token"
  192. ```
  193. **Available flags:**
  194. - `-d, --domain <domain>` - Confluence domain (e.g., `company.atlassian.net`)
  195. - `-p, --api-path <path>` - REST API path (e.g., `/wiki/rest/api`)
  196. - `-a, --auth-type <type>` - Authentication type: `basic`, `bearer`, `mtls`, `cookie`, or `none`
  197. - `-e, --email <email>` - Email or username for basic authentication
  198. - `-t, --token <token>` - API token or password
  199. - `-c, --cookie <cookie>` - Cookie for Enterprise SSO authentication (e.g., `"JSESSIONID=..."`). Can also be combined with `--auth-type basic`/`bearer` for gateways that require both a session cookie and an application-level credential (see below).
  200. - `--tls-client-cert <path>` - Client certificate for mTLS authentication
  201. - `--tls-client-key <path>` - Client private key for mTLS authentication
  202. - `--tls-ca-cert <path>` - Optional CA certificate chain for mTLS authentication
  203. - `--read-only` - Enable read-only mode (blocks all write operations)
  204. - `--keychain` - Store the token in the macOS Keychain instead of `config.json` (macOS only, see Option 5)
  205. - `--allow-insecure-http` - Allow `--protocol http` to actually use HTTP for this profile (see [HTTP transport](#http-transport-allowinsecurehttp) below). Without it, `http` silently falls back to HTTPS.
  206. ⚠️ **Security note:** While flags work, storing tokens in shell history is risky. Prefer environment variables (Option 3) for production environments, or the macOS Keychain (Option 5) for a workstation.
  207. ### Option 3: Environment Variables
  208. ```bash
  209. export CONFLUENCE_DOMAIN="your-domain.atlassian.net"
  210. export CONFLUENCE_API_TOKEN="your-api-token" # or password for on-premise (alias: CONFLUENCE_PASSWORD)
  211. export CONFLUENCE_EMAIL="your.email@example.com" # required for basic auth (alias: CONFLUENCE_USERNAME for on-premise)
  212. export CONFLUENCE_API_PATH="/wiki/rest/api" # Cloud default; use /rest/api for Server/DC
  213. # Optional: set to 'bearer' for self-hosted/Data Center instances
  214. export CONFLUENCE_AUTH_TYPE="basic"
  215. # Optional: select a named profile (overridden by --profile flag)
  216. export CONFLUENCE_PROFILE="default"
  217. ```
  218. **mTLS environment variables**:
  219. ```bash
  220. export CONFLUENCE_DOMAIN="docs.example.com"
  221. export CONFLUENCE_API_PATH="/confluence/rest/api"
  222. export CONFLUENCE_AUTH_TYPE="mtls"
  223. export CONFLUENCE_TLS_CLIENT_CERT="~/.certs/client.pem"
  224. export CONFLUENCE_TLS_CLIENT_KEY="~/.certs/client.key"
  225. export CONFLUENCE_TLS_CA_CERT="~/.certs/ca-chain.pem" # optional
  226. ```
  227. **Cookie environment variables** (Enterprise SSO):
  228. ```bash
  229. export CONFLUENCE_DOMAIN="confluence.company.com"
  230. export CONFLUENCE_API_PATH="/rest/api"
  231. export CONFLUENCE_AUTH_TYPE="cookie"
  232. export CONFLUENCE_COOKIE="JSESSIONID=abc123xyz..."
  233. ```
  234. **Reverse-proxy / no-auth environment variables**:
  235. ```bash
  236. export CONFLUENCE_DOMAIN="confluence.internal"
  237. export CONFLUENCE_API_PATH="/rest/api"
  238. export CONFLUENCE_AUTH_TYPE="none"
  239. ```
  240. **Scoped API token** (recommended for agents):
  241. ```bash
  242. export CONFLUENCE_DOMAIN="api.atlassian.com"
  243. export CONFLUENCE_API_PATH="/ex/confluence/<your-cloud-id>/wiki/rest/api"
  244. export CONFLUENCE_AUTH_TYPE="basic"
  245. export CONFLUENCE_EMAIL="user@example.com"
  246. export CONFLUENCE_API_TOKEN="your-scoped-token"
  247. ```
  248. `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.
  249. ### Option 4: `.netrc` file
  250. To keep your API token out of `config.json` on any platform, store it in a standard [`.netrc`](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html) file (the same mechanism used by `curl` and Git). Configure a profile as usual but omit the token, then add an entry to your `~/.netrc`:
  251. ```
  252. machine your-domain.atlassian.net
  253. login your.email@example.com
  254. password your-api-token
  255. ```
  256. - The `machine` must match the profile's domain, and `login` must match the profile's email (basic auth). For bearer auth (no email), only the `machine` is matched.
  257. - The token is resolved with this precedence: environment variable / `--token` → profile `token` in `config.json` → macOS Keychain → `.netrc`. A token from a higher-priority source wins.
  258. - `.netrc` supplies the token for `basic` and `bearer` auth only (not `mtls`, `cookie`, or `none`).
  259. - The file location is `~/.netrc` (`~/_netrc` on Windows), or the path in the `NETRC` environment variable if set.
  260. - Note that `.netrc` is still plaintext on disk. On macOS, prefer the Keychain (Option 5).
  261. ### Option 5: macOS Keychain
  262. On macOS you can keep the API token in the login Keychain instead of `config.json`. Pass `--keychain` to `confluence init` (or answer **yes** to the Keychain prompt in interactive mode):
  263. ```bash
  264. confluence init \
  265. --domain "your-domain.atlassian.net" \
  266. --auth-type basic \
  267. --email "your.email@example.com" \
  268. --token "your-api-token" \
  269. --keychain
  270. ```
  271. The profile is written without a `token` field, and every command reads the token from the Keychain instead.
  272. - Items are generic passwords named `confluence-cli:<host>`; the account is your email for `basic` auth or the literal `bearer` for `bearer` auth. You can inspect them in Keychain Access.app or with `security find-generic-password -s confluence-cli:<host> -a <account>`.
  273. - The CLI talks to the Keychain through the built-in `/usr/bin/security` tool (the same approach as `jira-cli`), so there is no native dependency. The token is passed to `security -i` on stdin, never on the command line.
  274. - Values are stored as `b64:` + base64 so that non-ASCII tokens round-trip. Entries added by hand with a plain value are read as-is and must be printable ASCII (otherwise `security` prints them as hex). Profiles on the same host with the same auth type share one item.
  275. - Re-running `confluence init --keychain` replaces both the profile and the Keychain item. Changing the host or email creates a new item and leaves the old one in place; remove items with `security delete-generic-password -s confluence-cli:<host> -a <account>`.
  276. - Set `CONFLUENCE_KEYCHAIN=off` to skip Keychain lookups (for example on a headless Mac where the login Keychain is locked and an access prompt would block). Lookups time out after 30 seconds and fall back to `.netrc`.
  277. - Not available on Linux or Windows; `--keychain` is rejected there and lookups are skipped.
  278. **Config file location:**
  279. confluence-cli supports the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/). The config directory is resolved in this order:
  280. 1. `CONFLUENCE_CONFIG_DIR` env var — explicit override (e.g., `/custom/path`)
  281. 2. Legacy `~/.confluence-cli/` — if it already exists (backwards compatibility)
  282. 3. `$XDG_CONFIG_HOME/confluence-cli/` — defaults to `~/.config/confluence-cli/`
  283. New installations go to `~/.config/confluence-cli/` by default. Existing users at `~/.confluence-cli/` are unaffected — the CLI continues to use the legacy location until you move it. To migrate, simply move the directory:
  284. ```bash
  285. mkdir -p ~/.config/confluence-cli
  286. mv ~/.confluence-cli/* ~/.config/confluence-cli/
  287. rmdir ~/.confluence-cli
  288. ```
  289. The stats file (`stats.json`) follows the same resolution and lives alongside `config.json` in the same directory.
  290. **Custom domains on Confluence Cloud:**
  291. If your Confluence Cloud instance uses a custom domain (e.g., `wiki.example.org` instead of `*.atlassian.net`), the CLI may identify it as a Server/Data Center instance and use standard links instead of Cloud smart links, and it will not switch to the v2 page API when the v1 endpoints answer `410 Gone`. Set `CONFLUENCE_FORCE_CLOUD=true` to override the automatic detection:
  292. ```bash
  293. export CONFLUENCE_FORCE_CLOUD=true
  294. ```
  295. Or add `"forceCloud": true` to your profile in the config file (see [Config file location](#config-file-location)):
  296. ```json
  297. {
  298. "profiles": {
  299. "default": {
  300. "domain": "wiki.example.org",
  301. "forceCloud": true
  302. }
  303. }
  304. }
  305. ```
  306. **HTTP transport (`allowInsecureHttp`):**
  307. HTTPS is used by default even if a profile or `CONFLUENCE_PROTOCOL` requests `http` — connecting over plain HTTP sends your credentials (basic auth header, bearer token, cookie) in plaintext, including through transparent corporate proxies. Setting `protocol: "http"` without an explicit opt-in prints a warning and silently falls back to HTTPS.
  308. If you genuinely need HTTP — for example a local reverse-authentication proxy on `127.0.0.1` or an internal network you trust — opt in explicitly via any of:
  309. ```bash
  310. # 1. CLI flag on init / profile add
  311. confluence init --domain "127.0.0.1:8080" --protocol http --allow-insecure-http ...
  312. # 2. Environment variable (overrides the profile's allowInsecureHttp setting)
  313. export CONFLUENCE_ALLOW_INSECURE_HTTP=true
  314. ```
  315. Or set `"allowInsecureHttp": true` directly in the profile:
  316. ```json
  317. {
  318. "profiles": {
  319. "local-proxy": {
  320. "domain": "127.0.0.1:8080",
  321. "protocol": "http",
  322. "allowInsecureHttp": true
  323. }
  324. }
  325. }
  326. ```
  327. **Link rendering (`linkStyle`):**
  328. External links use Cloud smart links (`<a data-card-appearance="inline">`) on Cloud and standard `<a href>` tags on Server/Data Center and local conversions. Some Cloud instances — particularly custom-domain Cloud setups — fail to render smart links and show "Cannot handle: DefaultLink" errors instead. If you hit this, set `linkStyle` to `plain`:
  329. ```bash
  330. export CONFLUENCE_LINK_STYLE=plain
  331. ```
  332. Or per-profile:
  333. ```json
  334. {
  335. "profiles": {
  336. "default": {
  337. "domain": "wiki.example.org",
  338. "forceCloud": true,
  339. "linkStyle": "plain"
  340. }
  341. }
  342. }
  343. ```
  344. Valid values: `smart` (Cloud smart links), `plain` (standard `<a href>`), `auto` (smart links for links into your own Confluence site, plain links for everything else), and `wiki` (legacy `ac:link` + `ri:url` output for explicit backward compatibility). When unset, the CLI picks `smart` for Cloud and `plain` for Server/Data Center and local conversions. New configurations should not use `wiki` for external links.
  345. A Cloud smart link is rendered from the target page's own title and discards the link text you wrote, which suits links to other Confluence pages but not links to external sites. `auto` gives each link the right treatment:
  346. ```markdown
  347. See [ACME](https://example.atlassian.net/wiki/spaces/DEVOPS/pages/1346144034/acme)
  348. and [Let's Encrypt FAQ](https://letsencrypt.org/docs/faq/).
  349. ```
  350. becomes a smart link for `ACME` and a plain `<a href>` that keeps the text `Let's Encrypt FAQ`. A link counts as internal when its parsed origin matches `siteUrl` (or the configured domain when unset) and its path is inside the site's context path (`/wiki` on Cloud), so look-alike hosts such as `example.atlassian.net.evil.test` stay plain. Relative links are rendered plain, and so is every link when no site is configured (for example in library use of the converter without `buildUrl`). Only the written storage differs: `read --format markdown` returns the same `[text](href)` under every style.
  351. Smart links are a Cloud feature, so on Server/Data Center `auto` would emit smart-link markup for internal links that those sites do not render; keep `plain` there. With a scoped API token the CLI talks to the `api.atlassian.com` gateway. Set your actual Confluence site URL separately to enable internal link detection:
  352. ```bash
  353. export CONFLUENCE_SITE_URL=https://example.atlassian.net
  354. export CONFLUENCE_LINK_STYLE=auto
  355. ```
  356. Alternatively, save `"siteUrl": "https://example.atlassian.net"` in the profile, or pass `--site-url https://example.atlassian.net` to `confluence init` or `confluence profile add <name>`. Use an absolute HTTP(S) URL without credentials, query, or fragment; a `/wiki` context path and trailing slash are supported. When loading a profile, a nonempty `CONFLUENCE_SITE_URL` overrides its `siteUrl`; an empty value uses the saved setting. This setting only supplies the web URL for conversion and internal link detection; API requests and authentication still use `domain` and `apiPath`. When unset, detection uses the API domain as before, so scoped gateway profiles render site links plain under `auto`.
  357. **PlantUML macro format (`plantumlFormat`):**
  358. ````` ```plantuml ````` fences become the plain `plantuml` macro by default. Sites running the PlantUML Diagrams for Confluence app need the `plantumlcloud` macro (URI-encoded, deflated and base64-encoded `data` parameter) — select it with `CONFLUENCE_PLANTUML_FORMAT=plantumlcloud`, the profile field `"plantumlFormat": "plantumlcloud"`, or `--plantuml-format plantumlcloud` on `convert`, `create`, `create-child` and `update`:
  359. ```bash
  360. export CONFLUENCE_PLANTUML_FORMAT=plantumlcloud
  361. confluence convert --input-format markdown --output-format storage --plantuml-format plantumlcloud -i page.md
  362. ```
  363. Valid values: `plantuml` (default — `<ac:plain-text-body>` CDATA) and `plantumlcloud` (compressed `data` parameter). Flag > environment variable > profile; `convert` runs locally without loading a profile, so the profile field only applies to `create`, `create-child` and `update`. Values are case-insensitive. See [Programmatically adding PlantUML diagrams](https://stratus-addons.atlassian.net/wiki/spaces/PDFC/pages/1839333377/Programmatically+adding+PlantUML+diagrams).
  364. > **Note:** `plantumlcloud` renders from `<filename>.svg` / `.png` attachments (`plantuml-diagram-1.svg`, … in document order) produced by a PlantUML server you operate. This CLI emits the macro only; upload those attachments separately. Both formats read back as the same ` ```plantuml ` fence.
  365. **Read-only mode** (recommended for AI agents):
  366. ```bash
  367. export CONFLUENCE_READ_ONLY=true
  368. ```
  369. When set, all write operations (`create`, `update`, `delete`, etc.) are blocked at the CLI level. The environment variable overrides the profile's `readOnly` setting.
  370. ### Getting Your API Token
  371. **Atlassian Cloud:**
  372. 1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
  373. 2. Click "Create API token"
  374. 3. Give it a label (e.g., "confluence-cli")
  375. 4. Copy the generated token
  376. **Atlassian Cloud — Scoped API Token** (recommended for agents and automation):
  377. 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.
  378. 1. Create a scoped token in your [Atlassian Admin settings](https://admin.atlassian.com)
  379. 2. Find your Cloud ID by visiting `https://<your-site>.atlassian.net/_edge/tenant_info`
  380. 3. Configure with:
  381. - **Domain:** `api.atlassian.com`
  382. - **API path:** `/ex/confluence/<your-cloud-id>/wiki/rest/api`
  383. - **Auth type:** `basic` (email + scoped token)
  384. **Required scopes for scoped API tokens:**
  385. When creating a scoped token, select the following [classic scopes](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/) based on your needs:
  386. | Scope | Required for |
  387. |-------|-------------|
  388. | `read:confluence-content.all` | Reading pages and blog posts (`read`, `info`) |
  389. | `read:confluence-content.summary` | Reading content summaries and metadata (`read`, `info`) |
  390. | `read:confluence-space.summary` | Listing spaces (`spaces`) |
  391. | `search:confluence` | Searching content (`search`) |
  392. | `readonly:content.attachment:confluence` | Downloading attachments (`attachments --download`) |
  393. | `write:confluence-content` | Creating and updating pages (`create`, `update`) |
  394. | `write:confluence-file` | Uploading attachments (`attachments --upload`) |
  395. | `write:confluence-space` | Managing spaces |
  396. For **read-only** usage, select at minimum the classic scopes `read:confluence-content.all`, `read:confluence-content.summary`, `read:confluence-space.summary`, and `search:confluence`. Listing folders with `children --type folders`/`all` additionally requires the granular scope `read:hierarchical-content:confluence`.
  397. **Confluence Cloud sites where the v1 page API is gone.** Atlassian is removing the v1 `/content` and `/space` endpoints on Cloud; a removed endpoint answers `410 Gone`. The CLI keeps using v1 until one answers 410 and then switches to `/wiki/api/v2` (pages, blog posts, folders, spaces) for the rest of the command, so a site that still serves v1 sees no change. On v2, `read`, `info`, `create`, `create-child`, `update`, `edit`, `move`, `delete`, `children`, `copy-tree`, `export`, `spaces`, `space-lookup` and display-URL lookups use v2. Search stays on v1 and keeps the classic scopes above. Attachments, comments, content properties and versions are not ported yet and still call v1, so they fail where Atlassian has removed those endpoints too; there, run `export` with `--skip-attachments`. Server/Data Center never switches. Set `CONFLUENCE_PAGE_API=v1` or `v2` (or the `pageApi` client option) to skip the detection, for example to use v2 from the first request. Differences on v2: `info` reports authors as account IDs and ancestors without titles, child listings carry no version (`children --json` reports `version: null`) and their URLs are built from the space key and page id, and `update`/`move` work on pages only.
  398. The v2 endpoints do not accept the classic content scopes; they need **granular** scopes. Granular scopes per command on the v2 API (a missing scope can surface as 401 or 403; unscoped API tokens are not subject to scopes). `S` = `read:space:confluence`, `M` = `read:content.metadata:confluence` (ancestors), `H` = `read:hierarchical-content:confluence` (needed only for direct-children listings of folders):
  399. | Command | Granular scopes |
  400. |---------|-----------------|
  401. | `read` (storage/html/text) | `read:page:confluence` (blog post: `read:blogpost:confluence`; folders have no body and always report "no readable body") |
  402. | `read --format markdown` | as above, plus `S` (page links); a page using the children macro also needs the child listing scopes (`read:page:confluence` + `S`) |
  403. | `info` | `read:page:confluence` + `S` + `M` (blog post: `read:blogpost:confluence` + `S`; folder: `read:folder:confluence` + `S` + `M`) |
  404. | `spaces`, `space-lookup` | `S` |
  405. | `create` | `S`, `write:page:confluence` (folder: `write:folder:confluence`) |
  406. | `create-child` | `create` scopes, plus the `info` scopes of the parent's type (`read:page:confluence` + `S` + `M` for a page parent, `read:folder:confluence` + `S` + `M` for a folder) |
  407. | `update`, `edit`, `move` | `read:page:confluence` + `S` + `write:page:confluence` |
  408. | `delete` | `info` scopes, plus `delete:page:confluence` (`delete:blogpost:confluence` / `delete:folder:confluence` for those types) |
  409. | `children` (pages) | `read:page:confluence` + `S`; `--recursive --json` adds `M`; `--format tree` adds the `info` scopes |
  410. | `children --type folders` / `all` | `H` (folders are listed through direct-children); `all` also needs the pages scopes |
  411. | `copy-tree` | `info` scopes for source and target, `S`, `write:page:confluence` (child listing needs only `read:page:confluence` + `S`) |
  412. | `export` | `info` scopes, child listing scopes (`read:page:confluence` + `S`), plus the classic attachment scope when downloading attachments |
  413. **On-premise / Data Center:** Use your Confluence username and password for basic authentication.
  414. **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.
  415. **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.
  416. **Reverse-proxy injected authentication:** For deployments where a local reverse proxy injects credentials on the wire (e.g. SPNEGO/Kerberos, mTLS terminated at the proxy edge, or header injection), set `authType=none`. In this mode the CLI sends no `Authorization` or `Cookie` header — authentication is entirely the proxy's responsibility. Point `CONFLUENCE_DOMAIN` at the proxy and ensure no credentials are configured on the CLI side.
  417. **Combining a gateway cookie with Bearer/Basic auth:** Some corporate reverse-proxy/SSO gateways (e.g. F5 BIG-IP APM) terminate the connection with their own access-policy session cookie *and* still forward the request to Confluence, which then requires its own application-level credential (a Personal Access Token or Basic auth) on top. Neither `authType=cookie` (sends only `Cookie`) nor a plain `authType=bearer`/`basic` (sends only `Authorization`) covers this by itself. Set `--cookie` (or `CONFLUENCE_COOKIE`) *alongside* `--auth-type bearer` (or `basic`) and both headers are sent together:
  418. ```bash
  419. confluence --profile gateway init \
  420. --domain "confluence.company.com" \
  421. --api-path "/rest/api" \
  422. --auth-type "bearer" \
  423. --token "your-personal-access-token" \
  424. --cookie "MRHSession=abc123..."
  425. ```
  426. The gateway's session cookie is typically short-lived and will need refreshing periodically (re-extract it from your browser's dev tools and update the profile), independently of the token/password, which does not expire the same way.
  427. ## Usage
  428. ### JSON output (for scripting / jq)
  429. Pass the global `--json` flag to make a command emit raw JSON to stdout, so you can pipe it to tools like `jq`:
  430. ```bash
  431. confluence search "release notes" --json | jq '.results[].title'
  432. confluence spaces --json | jq -r '.spaces[].key'
  433. confluence info 123456789 --json | jq '.version'
  434. confluence create "Notes" ENG --content "hi" --json | jq -r '.id' # capture the new page id
  435. ```
  436. `--json` works on read commands (`info`, `search`, `spaces`, `find`, `children`, `versions`, `comments`, `attachments`, `property-list`/`-get`/`-set`) and write commands (`create`, `create-child`, `update`, `move`, `delete`, `copy-tree`, `comment`, `comment-resolve`, `comment-delete`, `property-delete`, `attachment-upload`/`-delete`, `version-delete`, `versions-purge`). For destructive commands, `--json` requires `--yes` — it will not prompt interactively. Passing `--json` to a command that doesn't support it (e.g. `init`, `convert`, `export`, `edit`) is rejected with an error rather than silently ignored. Human-readable messages and warnings go to stderr, so stdout stays valid JSON.
  437. > **Deprecation:** the per-command `--format json` form is deprecated in favor of the global `--json` flag. It still works but prints a warning to stderr and will be removed in a future major version.
  438. #### Structured errors
  439. When `--json` is active, command failures are machine-parseable: the command prints exactly one JSON object to **stderr** (stdout stays empty) and, except as noted below, exits with status `1`. This lets scripts and agents branch on failures without scraping prose. The shape is:
  440. ```json
  441. {
  442. "error": "Authentication failed (401 Unauthorized).",
  443. "code": "AUTH_FAILED",
  444. "status": 401,
  445. "details": { "message": "...", "status-code": 401 }
  446. }
  447. ```
  448. - `error` — the human-readable message.
  449. - `code` — a stable machine code, one of `AUTH_FAILED`, `NOT_FOUND`, `VALIDATION`, `API_ERROR`, `NETWORK`, `UNKNOWN`.
  450. - `status` — the HTTP status when the failure came from the server, otherwise `null`.
  451. - `details` — the raw API response body when present, otherwise `null`.
  452. ```bash
  453. # Read errors from stderr and inspect the code
  454. confluence info 123 --json 2> >(jq -r '.code') 1>/dev/null
  455. ```
  456. Without `--json`, error output is unchanged (human-readable prose on stderr).
  457. Exceptions: `api` failures caused by missing `jq` or a failing `--jq` expression still use the structured stderr format but preserve exit status `2`. Partial failures from `copy-tree --fail-on-error` and `versions-purge` emit their result JSON to stdout and signal the partial failure with exit status `1` instead of a structured error on stderr.
  458. ### Read a Page
  459. ```bash
  460. # Read by page ID
  461. confluence read 123456789
  462. # Read native Confluence storage content
  463. confluence read 123456789 --format storage
  464. # Read in markdown format
  465. confluence read 123456789 --format markdown
  466. # Read by URL (must contain pageId parameter)
  467. confluence read "https://your-domain.atlassian.net/wiki/viewpage.action?pageId=123456789"
  468. ```
  469. Use `--format storage` when you need Confluence's native storage representation, especially for macros and other Confluence-specific markup.
  470. Markdown reads resolve accessible Confluence page links, including links that omit a space key because they target the same space, to absolute URLs. Custom link text and inline formatting are preserved. Markdown exports use the same link resolution.
  471. Reading requires content with a storage body. Folders and other bodyless content return `Page <id> has no readable body (it may be a folder or an unsupported content type).`; use `confluence info <id>` to inspect their metadata.
  472. ### Get Page Information
  473. ```bash
  474. confluence info 123456789
  475. # Emit machine-readable metadata
  476. confluence info 123456789 --json
  477. ```
  478. `info` can inspect folders and other bodyless content because it only reads metadata.
  479. Example JSON shape:
  480. ```json
  481. {
  482. "id": "123456789",
  483. "title": "Architecture Overview",
  484. "type": "page",
  485. "status": "current",
  486. "spaceKey": "ENG",
  487. "parentId": "100200300",
  488. "version": 7,
  489. "url": "https://your-domain.atlassian.net/wiki/spaces/ENG/pages/123456789/Architecture+Overview"
  490. }
  491. ```
  492. ### Search Pages
  493. ```bash
  494. # Basic search
  495. confluence search "search term"
  496. # Limit results
  497. confluence search "search term" --limit 5
  498. # Paginate results
  499. confluence search "search term" --limit 5 --start 5
  500. ```
  501. ### List or Download Attachments
  502. ```bash
  503. # List all attachments on a page
  504. confluence attachments 123456789
  505. # Filter by filename and limit the number returned
  506. confluence attachments 123456789 --pattern "*.png" --limit 5
  507. # Download matching attachments to a directory
  508. confluence attachments 123456789 --pattern "*.png" --download --dest ./downloads
  509. ```
  510. ### Upload Attachments
  511. ```bash
  512. # Upload a single attachment
  513. confluence attachment-upload 123456789 --file ./report.pdf
  514. # Upload multiple files with a comment
  515. confluence attachment-upload 123456789 --file ./a.pdf --file ./b.png --comment "v2"
  516. # Replace an existing attachment by filename
  517. confluence attachment-upload 123456789 --file ./diagram.png --replace
  518. ```
  519. `--replace` adds a new version to the attachment with the same filename, and uploads the file as a new attachment when the page has none. It works on Confluence Cloud and on Server/Data Center. Without `--replace`, Confluence rejects a filename that already exists on the page with HTTP 400.
  520. ### Delete Attachments
  521. ```bash
  522. # Delete an attachment by ID
  523. confluence attachment-delete 123456789 998877
  524. # Skip confirmation
  525. confluence attachment-delete 123456789 998877 --yes
  526. ```
  527. ### Content Properties
  528. ```bash
  529. # List all properties on a page
  530. confluence property-list 123456789
  531. # Get a specific property
  532. confluence property-get 123456789 my-key
  533. # Set a property (creates or updates with auto-versioning)
  534. confluence property-set 123456789 my-key --value '{"color":"#ff0000"}'
  535. # Set a property from a JSON file
  536. confluence property-set 123456789 my-key --file ./property.json
  537. # Delete a property
  538. confluence property-delete 123456789 my-key
  539. # Skip confirmation on delete
  540. confluence property-delete 123456789 my-key --yes
  541. ```
  542. #### Content properties in Markdown front matter
  543. Markdown files can carry selected content properties (for example page width) in YAML front matter, so property changes can be reviewed in git and applied through the normal upload workflow.
  544. ```markdown
  545. ---
  546. properties:
  547. content-appearance-published: full-width
  548. ---
  549. # Page title
  550. ```
  551. ```bash
  552. # Export a page with the listed properties as front matter
  553. # (keys that do not exist on the page are omitted, in the order given)
  554. confluence read 123456789 --format markdown --front-matter content-appearance-published > page.md
  555. # Upload the body and apply the front matter properties
  556. confluence update 123456789 --file ./page.md --format markdown --front-matter
  557. confluence create "Page title" MYSPACE --file ./page.md --format markdown --front-matter
  558. confluence create-child "Page title" 123456789 --file ./page.md --format markdown --front-matter
  559. ```
  560. - Front matter is only processed with `--front-matter`; without it, a leading `---` stays part of the Markdown body (a thematic break), as before.
  561. - Only the `properties` map is used; other top-level keys are ignored (a warning is printed if the block has no `properties` map). Properties not listed are left untouched, and properties whose value already matches are not rewritten.
  562. - On Confluence Cloud the editor also keeps a `content-appearance-draft` property; set it alongside `content-appearance-published` so the width survives the next edit in the browser.
  563. - Front matter is parsed before anything is uploaded, so invalid YAML fails without changing the page.
  564. - The body is saved first, then the properties. If a property fails (for example because the token lacks the needed scope), the command exits non-zero and reports that the body was saved and which keys failed. With `--json`, the result on stdout includes `properties: { applied, unchanged, failed }` and stderr carries a `PARTIAL_FAILURE` error. Re-running `update` is safe: properties that already match are skipped. For `create` and `create-child`, the error names the `update` command that retries the properties on the new page (re-running `create` would try to make another page).
  565. - `read` → edit → `update` round trips keep the selected properties. Markdown output is stable and normalized, not byte-identical to the original file.
  566. ### Comments
  567. ```bash
  568. # List all comments (footer + inline)
  569. confluence comments 123456789
  570. # List inline comments as markdown
  571. confluence comments 123456789 --location inline --format markdown
  572. # Create a footer comment
  573. confluence comment 123456789 --content "Looks good to me!"
  574. # Create an inline comment (Confluence Cloud: no editor metadata needed)
  575. confluence comment 123456789 \
  576. --location inline \
  577. --content "Consider renaming this" \
  578. --inline-selection "foo"
  579. # Highlight the second occurrence of the selected text instead of the first
  580. confluence comment 123456789 \
  581. --location inline \
  582. --content "Consider renaming this one too" \
  583. --inline-selection "foo" \
  584. --match-index 2
  585. # Reply to a comment (inline or footer thread)
  586. confluence comment 123456789 --parent 998877 --content "Agree with this"
  587. # Resolve or reopen an inline comment thread (Confluence Cloud)
  588. confluence comment-resolve 998877
  589. confluence comment-resolve 998877 --reopen
  590. # Delete a comment
  591. confluence comment-delete 998877
  592. ```
  593. Inline comment creation (Confluence Cloud): `comment --location inline --inline-selection "<text on the page>"` creates a new inline thread through the v2 API, without any editor-generated highlight metadata. The CLI reads the page, counts how many times the selection text occurs, and fails with a clear error if the text is not on the page. When the text occurs more than once, `--match-index <n>` picks which occurrence to highlight (1-based: `1` is the first, the default). On Server/Data Center — and when `--inline-properties`, `--inline-original-selection`, or `--inline-marker-ref` is supplied — creation still goes through the v1 `POST /content` API, which does require editor highlight metadata (`matchIndex`, `lastFetchTime`, `serializedHighlights`, plus the selection text); supply the full `--inline-properties` payload captured from the editor there, or it can fail with a 400. Footer comments are fully supported everywhere.
  594. Replies and resolution (Confluence Cloud): `--parent <commentId>` posts through the v2 comment API, which needs no highlight metadata, so replies to inline and footer threads both work. The reply goes to the same kind of thread as its parent (any `--location` or `--inline-*` option is ignored for replies), and the command fails before posting if the parent belongs to a different page. Replying does not change whether a thread is resolved. `comment-resolve <commentId>` resolves a top-level inline thread and `--reopen` reopens it; asking for the state the thread already has changes nothing, and a dangling thread (its highlighted text was removed) cannot be updated. Server/Data Center keeps the v1 reply behavior, and `comment-resolve` requires Cloud. API tokens with granular scopes need the v2 comment scopes (`read:comment:confluence` and `write:comment:confluence`) for replies and `comment-resolve`; a token with only the classic content scopes gets a 401/403 on a reply that used to work through v1. Comment IDs must be numeric.
  595. ### Export a Page with Attachments
  596. ```bash
  597. # Export page content (markdown by default) and all attachments
  598. confluence export 123456789 --dest ./exports
  599. # Custom content format/filename and attachment filtering
  600. confluence export 123456789 --format html --file content.html --pattern "*.png"
  601. # Exclude matching attachments (comma-separated globs)
  602. confluence export 123456789 --exclude-attachments "*.mp4,*.mov"
  603. # Exclusions are applied after --pattern or --referenced-only when combined
  604. # Skip attachments if you only need the content file
  605. confluence export 123456789 --skip-attachments
  606. ```
  607. ### Export a Whole Page Tree (or Space)
  608. Add `--recursive` to export a page together with all of its descendants. Each page becomes a folder (named after the page title) containing `page.md` and its `attachments/`, nested to mirror the page hierarchy. Point it at a space's homepage to export the whole space:
  609. ```bash
  610. # Export a page and all descendants
  611. confluence export 123456789 -r --dest ./my-space
  612. # Preview which pages would be exported, without writing files
  613. confluence export 123456789 -r --dry-run
  614. # Limit depth, skip pages by title glob, and slow down between requests
  615. confluence export 123456789 -r --max-depth 3 --exclude "Archive*,Draft*" --delay-ms 500
  616. # Re-export over a previous run (replaces content, removes stale files)
  617. confluence export 123456789 -r --overwrite
  618. ```
  619. ### List Spaces
  620. ```bash
  621. # Default: up to 500 spaces (paginated automatically across requests)
  622. confluence spaces
  623. # Increase the cap when your tenant has more than 500 spaces
  624. confluence spaces --limit 2000
  625. # Fetch every space, regardless of how many pages it takes
  626. confluence spaces --all
  627. ```
  628. ### List Children
  629. ```bash
  630. # List direct child pages
  631. confluence children 123456789
  632. # List descendant pages recursively
  633. confluence children 123456789 --recursive
  634. # List child folders instead of pages (Confluence Cloud only)
  635. confluence children 123456789 --type folders
  636. # List both pages and folders; each item shows its content type
  637. confluence children 123456789 --type all
  638. # Display as tree structure
  639. confluence children 123456789 --recursive --format tree
  640. # Show child IDs and available URLs
  641. confluence children 123456789 --show-id --show-url
  642. # Limit page recursion depth
  643. confluence children 123456789 --recursive --max-depth 3
  644. # Output as JSON for scripting
  645. confluence children 123456789 --recursive --json > children.json
  646. ```
  647. `children --json` returns structured metadata for each child, including `id`, `title`, `type`, `status`, `spaceKey`, `parentId`, `version`, and `url`. Recursive page entries also include `depth`, and when available, `ancestors`.
  648. Use `--type` to choose what is listed: `pages` (default, unchanged behavior), `folders`, or `all`. The `type` field on each item distinguishes `page` from `folder`; when folders can appear, the human-readable list marks every item with `[page]` or `[folder]`, and tree output uses distinct page and folder icons. Folders are a Confluence Cloud concept; on Server/Data Center, `--type folders`/`all` prints a warning and skips folders instead of failing, while `all` still lists pages. When pages are included, `--recursive` lists their descendants as before, but folders remain limited to direct children of the requested page.
  649. Example recursive JSON item:
  650. ```json
  651. {
  652. "pageId": "123456789",
  653. "childCount": 2,
  654. "children": [
  655. {
  656. "id": "200300400",
  657. "title": "Child Page",
  658. "type": "page",
  659. "status": "current",
  660. "spaceKey": "ENG",
  661. "parentId": "123456789",
  662. "version": 4,
  663. "url": "https://your-domain.atlassian.net/wiki/spaces/ENG/pages/200300400/Child+Page",
  664. "depth": 1,
  665. "ancestors": [
  666. {
  667. "id": "123456789",
  668. "type": "page",
  669. "title": "Architecture Overview"
  670. }
  671. ]
  672. }
  673. ]
  674. }
  675. ```
  676. ### Find a Page by Title
  677. ```bash
  678. # Find page by title
  679. confluence find "Project Documentation"
  680. # Find page by title in a specific space
  681. confluence find "Project Documentation" --space MYTEAM
  682. ```
  683. ### Create a New Page
  684. ```bash
  685. # Create with inline content and markdown format
  686. confluence create "My New Page" SPACEKEY --content "**Hello** World!" --format markdown
  687. # Create from a file
  688. confluence create "Documentation" SPACEKEY --file ./content.md --format markdown
  689. # Auto-detect: keeps storage XHTML as-is, converts plain text/Markdown
  690. confluence create "My New Page" SPACEKEY --content "**Hello** World!" --format auto
  691. ```
  692. For create, create-child, update, and comment, `--format auto` detects the content type:
  693. it preserves content that starts with markup such as `<p>...</p>` or `<ac:structured-macro ...>`, and converts plain text or Markdown to Confluence storage XHTML. This is useful for older Confluence Server/Data Center versions that reject bare text in a `body.storage.value`.
  694. ### Create a Child Page
  695. ```bash
  696. # Create child page with inline content
  697. confluence create-child "Meeting Notes" 123456789 --content "This is a child page"
  698. # Create child page from a file
  699. confluence create-child "Tech Specs" 123456789 --file ./specs.md --format markdown
  700. ```
  701. ### Copy Page Tree
  702. ```bash
  703. # Copy a page and all its children to a new location
  704. confluence copy-tree 123456789 987654321 "Project Docs (Copy)"
  705. # Copy with maximum depth limit (only 3 levels deep)
  706. confluence copy-tree 123456789 987654321 --max-depth 3
  707. # Exclude pages by title (supports wildcards * and ?; case-insensitive)
  708. confluence copy-tree 123456789 987654321 --exclude "temp*,test*,*draft*"
  709. # Control pacing and naming
  710. confluence copy-tree 123456789 987654321 --delay-ms 150 --copy-suffix " (Backup)"
  711. # Dry run (preview only)
  712. confluence copy-tree 123456789 987654321 --dry-run
  713. # Quiet mode (suppress progress output)
  714. confluence copy-tree 123456789 987654321 --quiet
  715. ```
  716. Notes:
  717. - Preserves the original parent-child hierarchy when copying.
  718. - Continues on errors: failed pages are logged and the copy proceeds.
  719. - Exclude patterns use simple globbing: `*` matches any sequence, `?` matches any single character, and special regex characters are treated literally.
  720. - Large trees may take time; the CLI applies a small delay between sibling page creations to avoid rate limits (configurable via `--delay-ms`).
  721. - If the server answers `429` (for example a Data Center instance limited to a few requests per second), the CLI paces its requests: a positive `Retry-After` makes every request wait, and requests are spaced further apart until the server accepts them, then speeded up again. Traversals such as `copy-tree`, `export` and `children --recursive` therefore finish under a low shared limit instead of failing after a few retries, and a server that keeps refusing still fails after about as long as before. Without throttling nothing is slowed down. A `503` on a read is retried per request, as before.
  722. - Root title suffix defaults to ` (Copy)`; override with `--copy-suffix`. Child pages keep their original titles.
  723. - Use `--fail-on-error` to exit non-zero if any page fails to copy.
  724. ### Update an Existing Page
  725. ```bash
  726. # Update title only
  727. confluence update 123456789 --title "A Newer Title for the Page"
  728. # Update content only from a string
  729. confluence update 123456789 --content "Updated page content."
  730. # Update content from a file
  731. confluence update 123456789 --file ./updated-content.md --format markdown
  732. # Update both title and content
  733. confluence update 123456789 --title "New Title" --content "And new content"
  734. ```
  735. Title-only updates reuse the target's existing storage body. Folders and other bodyless content cannot be updated this way and return `Page <id> has no readable body (it may be a folder or an unsupported content type).`.
  736. ### Move a Page to New Parent
  737. ```bash
  738. # Move page by ID
  739. confluence move 123456789 987654321
  740. # Move page and rename it
  741. confluence move 123456789 987654321 --title "Relocated Page"
  742. # Move using URLs (for convenience)
  743. confluence move "https://domain.atlassian.net/wiki/viewpage.action?pageId=123456789" \
  744. "https://domain.atlassian.net/wiki/viewpage.action?pageId=987654321"
  745. ```
  746. **Note:** Pages can only be moved within the same Confluence space. Cross-space moves are not supported.
  747. ### Delete a Page
  748. ```bash
  749. # Delete by page ID (prompts for confirmation)
  750. confluence delete 123456789
  751. # Delete by URL
  752. confluence delete "https://your-domain.atlassian.net/wiki/viewpage.action?pageId=123456789"
  753. # Skip confirmation (useful for scripts)
  754. confluence delete 123456789 --yes
  755. ```
  756. ### Edit Workflow
  757. The `edit` and `update` commands work together to create a seamless editing workflow.
  758. ```bash
  759. # 1. Export page content to a file (in Confluence storage format)
  760. confluence edit 123456789 --output ./page-to-edit.xml
  761. # 2. Edit the file with your preferred editor
  762. vim ./page-to-edit.xml
  763. # 3. Update the page with your changes
  764. confluence update 123456789 --file ./page-to-edit.xml --format storage
  765. ```
  766. Only content with a storage body can be exported for editing. Folders and other bodyless content return `Page <id> has no readable body (it may be a folder or an unsupported content type).`.
  767. ### Profile Management
  768. ```bash
  769. # List all profiles and see which is active
  770. confluence profile list
  771. # Switch the active profile
  772. confluence profile use staging
  773. # Add a new profile interactively
  774. confluence profile add staging
  775. # Add a new profile non-interactively
  776. confluence profile add staging --domain "staging.example.com" --auth-type bearer --token "xyz"
  777. # Add a read-only profile (blocks all write operations)
  778. confluence profile add agent --domain "company.atlassian.net" --auth-type basic --email "bot@example.com" --token "xyz" --read-only
  779. # Remove a profile
  780. confluence profile remove staging
  781. # Use a specific profile for a single command
  782. confluence --profile staging spaces
  783. ```
  784. ### Read-Only Mode
  785. 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.
  786. **Enable via profile:**
  787. ```bash
  788. # During init
  789. confluence init --read-only
  790. # When adding a profile
  791. confluence profile add agent --domain "company.atlassian.net" --token "xyz" --read-only
  792. ```
  793. **Enable via environment variable:**
  794. ```bash
  795. export CONFLUENCE_READ_ONLY=true # overrides profile setting
  796. ```
  797. When read-only mode is active, any write command (`create`, `create-child`, `update`, `delete`, `move`, `edit`, `comment`, `comment-resolve`, `attachment-upload`, `attachment-delete`, `property-set`, `property-delete`, `comment-delete`, `copy-tree`) exits with code 1 and prints an error message.
  798. `confluence profile list` shows a `[read-only]` badge next to protected profiles.
  799. ### Raw API Requests
  800. Make arbitrary authenticated requests to any Confluence REST endpoint, modeled after `gh api`. Useful for endpoints the CLI hasn't wrapped yet (labels, restrictions, groups, audit, v2 API, …) without falling back to `curl`.
  801. **Endpoint resolution:**
  802. - **Relative path** (no leading slash) → resolved against the configured `apiPath` (the default for most calls).
  803. - **Absolute path** (leading `/`) → bypasses `apiPath`; resolved against the host. On Confluence Cloud, `apiPath` is typically `/wiki/rest/api`, so absolute endpoints must include the `/wiki` prefix.
  804. - **Full URL** (`https://…`) → used as-is, but only when it is **same-origin** with the configured host. A full URL pointing at a different origin (or an `http://` downgrade of an `https` host) is refused, so your credentials are never sent to an unexpected server.
  805. ```bash
  806. # List labels on a page (relative — uses apiPath)
  807. confluence api content/123456789/label
  808. # Same call written as an absolute path on Confluence Cloud
  809. confluence api /wiki/rest/api/content/123456789/label
  810. # Add a label to a page (relative form)
  811. confluence api content/123456789/label --input - <<< '[{"name":"reviewed"}]'
  812. # Remove a label from a page
  813. confluence api content/123456789/label/reviewed -X DELETE
  814. # View page restrictions
  815. confluence api content/123456789/restriction
  816. # List groups
  817. confluence api group
  818. # Check long-running task status
  819. confluence api longtask/123
  820. # Query the v2 API (absolute path required, since v2 lives outside apiPath)
  821. confluence api /wiki/api/v2/pages -f spaceKey=DEV -f limit=10 -X GET
  822. # Filter response with jq
  823. confluence api group --jq '.results[].name'
  824. # Include response status and headers
  825. confluence api audit -i
  826. # Read request body from a file
  827. confluence api content/123456789/restriction --input ./restrictions.json
  828. # Suppress success output (useful in scripts that only care about exit code)
  829. confluence api content/123456789/label --input - --silent <<< '[{"name":"approved"}]'
  830. ```
  831. Read-only profiles block write methods (`POST`, `PUT`, `PATCH`, `DELETE`) while allowing `GET` and `HEAD`. `--jq` requires `jq` to be installed and available in `PATH`.
  832. ### View Usage Statistics
  833. ```bash
  834. confluence stats
  835. ```
  836. ## Commands
  837. | Command | Description | Options |
  838. |---|---|---|
  839. | `init` | Initialize CLI configuration | `--read-only`, `--keychain` |
  840. | `read <pageId_or_url>` | Read page content | `--format <html\|text\|storage\|markdown>`, `--front-matter <keys>` |
  841. | `info <pageId_or_url>` | Get page information | `--json` |
  842. | `search <query>` | Search for pages | `--json`, `--limit <number>`, `--start <number>` |
  843. | `spaces` | List available spaces | `--json`, `--limit <number>`, `--all` |
  844. | `find <title>` | Find a page by its title | `--space <spaceKey>`, `--json` |
  845. | `children <pageId>` | List child pages and folders of a page | `--recursive`, `--max-depth <number>`, `--type <pages\|folders\|all>`, `--format <list\|tree>`, `--json`, `--show-url`, `--show-id` |
  846. | `create <title> <spaceKey>` | Create a new page or folder | `--content <string>`, `--file <path>`, `--format <auto\|storage\|html\|markdown>`, `--type <page\|folder>`, `--front-matter`, `--json` |
  847. | `create-child <title> <parentId>` | Create a child page or folder | `--content <string>`, `--file <path>`, `--format <auto\|storage\|html\|markdown>`, `--type <page\|folder>`, `--front-matter`, `--json` |
  848. | `copy-tree <sourcePageId> <targetParentId> [newTitle]` | Copy page tree with all children | `--max-depth <number>`, `--exclude <patterns>`, `--delay-ms <ms>`, `--copy-suffix <text>`, `--dry-run`, `--fail-on-error`, `--quiet`, `--json` |
  849. | `update <pageId>` | Update a page's title or content | `--title <string>`, `--content <string>`, `--file <path>`, `--format <auto\|storage\|html\|markdown>`, `--front-matter`, `--json` |
  850. | `move <pageId_or_url> <newParentId_or_url>` | Move a page to a new parent location | `--title <string>`, `--json` |
  851. | `delete <pageId_or_url>` | Delete a page by ID or URL | `--yes`, `--json` |
  852. | `versions <pageId_or_url>` | List historical versions of a page | `--json` |
  853. | `version-delete <pageId_or_url> <versionNumber>` | Delete a single non-current version of a page | `--yes`, `--json` |
  854. | `versions-purge <pageId_or_url>` | Delete every non-current historical version of a page | `--yes`, `--throttle <seconds>`, `--json` |
  855. | `edit <pageId>` | Export page content for editing | `--output <file>` |
  856. | `attachments <pageId_or_url>` | List or download attachments for a page | `--json`, `--limit <number>`, `--pattern <glob>`, `--download`, `--dest <directory>` |
  857. | `attachment-upload <pageId_or_url>` | Upload attachments to a page | `--file <path>`, `--comment <text>`, `--replace`, `--minor-edit`, `--json` |
  858. | `attachment-delete <pageId_or_url> <attachmentId>` | Delete an attachment from a page | `--yes`, `--json` |
  859. | `comments <pageId_or_url>` | List comments for a page | `--format <text\|markdown>`, `--json`, `--limit <number>`, `--start <number>`, `--location <inline\|footer\|resolved>`, `--depth <root\|all>`, `--all` |
  860. | `comment <pageId_or_url>` | Create a comment on a page | `--content <string>`, `--file <path>`, `--format <auto\|storage\|html\|markdown>`, `--parent <commentId>`, `--location <inline\|footer>`, `--inline-selection <text>`, `--inline-original-selection <text>`, `--inline-marker-ref <ref>`, `--inline-properties <json>`, `--match-index <n>`, `--json` |
  861. | `comment-resolve <commentId>` | Resolve (or reopen) an inline comment thread (Cloud) | `--reopen`, `--json` |
  862. | `comment-delete <commentId>` | Delete a comment by ID | `--yes`, `--json` |
  863. | `property-list <pageId_or_url>` | List all content properties for a page | `--json`, `--limit <number>`, `--start <number>`, `--all` |
  864. | `property-get <pageId_or_url> <key>` | Get a content property by key | `--json` |
  865. | `property-set <pageId_or_url> <key>` | Set a content property (create or update) | `--value <json>`, `--file <path>`, `--json` |
  866. | `property-delete <pageId_or_url> <key>` | Delete a content property by key | `--yes`, `--json` |
  867. | `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>`, `--exclude-attachments <patterns>`, `--referenced-only`, `--skip-attachments`, `-r, --recursive`, `--max-depth <depth>`, `--exclude <patterns>`, `--delay-ms <ms>`, `--dry-run`, `--overwrite` |
  868. | `profile list` | List all configuration profiles | |
  869. | `profile use <name>` | Set the active configuration profile | |
  870. | `profile add <name>` | Add a new configuration profile | `-d, --domain`, `-p, --api-path`, `-a, --auth-type`, `-e, --email`, `-t, --token`, `--protocol`, `--allow-insecure-http`, `--read-only`, `--keychain` |
  871. | `profile remove <name>` | Remove a configuration profile | |
  872. | `api <endpoint>` | Make an authenticated API request (relative path uses apiPath; absolute path bypasses it; full URL must be same-origin) | `-X, --method <method>`, `-f, --field <key=value>`, `-H, --header <key:value>`, `--input <file>`, `--jq <expression>`, `-i, --include`, `--silent` |
  873. | `convert` | Convert between content formats locally (no server required) | `--input-file <path>`, `--output-file <path>`, `--input-format <markdown\|storage\|html>`, `--output-format <markdown\|storage\|html\|text>` |
  874. | `stats` | View your usage statistics | |
  875. **Global option:** `--profile <name>` — Use a specific profile for any command (overrides `CONFLUENCE_PROFILE` env var and active profile).
  876. ## Examples
  877. ```bash
  878. # Setup
  879. confluence init
  880. # Read a page as text
  881. confluence read 123456789
  882. # Read a page as HTML
  883. confluence read 123456789 --format html
  884. # Get page details
  885. confluence info 123456789
  886. # Search with limit
  887. confluence search "API documentation" --limit 3
  888. # List spaces
  889. confluence spaces
  890. # Move a page to a new parent
  891. confluence move 123456789 987654321
  892. # Move and rename
  893. confluence move 123456789 987654321 --title "New Title"
  894. # Upload and delete an attachment
  895. confluence attachment-upload 123456789 --file ./report.pdf
  896. confluence attachment-delete 123456789 998877 --yes
  897. # Create a folder (no content body required)
  898. confluence create "Engineering Docs" MYSPACE --type folder
  899. confluence create-child "Sub-folder" 123456789 --type folder
  900. # View usage statistics
  901. confluence stats
  902. # Profile management
  903. confluence profile list
  904. confluence profile use staging
  905. confluence --profile staging spaces
  906. # List labels on a page via the raw API (jq filter)
  907. confluence api content/123456789/label --jq '.[].name'
  908. # Convert markdown to Confluence storage format (no server required)
  909. confluence convert --input-file doc.md --input-format markdown --output-format storage
  910. # Pipe conversion via stdin/stdout
  911. echo "# Hello" | confluence convert --input-format markdown --output-format storage
  912. # Convert storage format back to markdown
  913. confluence convert -i page.xml -o page.md --input-format storage --output-format markdown
  914. ```
  915. ## Emphasis in Chinese, Japanese and Korean text
  916. Markdown input follows the [CJK-friendly amendment](https://github.com/tats-u/markdown-cjk-friendly/blob/main/specification.md) to CommonMark's emphasis rules, so `*`, `**` and `~~` work next to CJK characters without spaces: `**「括弧」**の直後`, `これは**私のやりたかったこと。**だから`, `**스크립트(script)**라고` and ``**`npm publish`**를`` become bold, where plain CommonMark leaves the asterisks in place. `_` / `__` still never open or close inside a word. Text without CJK characters next to a delimiter parses as before, except that a variation selector (U+FE00–U+FE0E) right before a delimiter is looked through to the character it modifies, as the amendment specifies.
  917. ## Markdown Marker Conventions
  918. When converting markdown to Confluence storage format (via `confluence convert`, `create`, or `update`), the following paragraph-level markers produce native Confluence macros. Each marker round-trips back to its markdown form when going storage → markdown.
  919. ### Callout macros — `INFO`, `WARNING`, `NOTE`
  920. A blockquote whose first line is `**INFO**`, `**WARNING**`, or `**NOTE**` becomes the corresponding Confluence macro:
  921. ```markdown
  922. > **INFO**
  923. > Heads up — this is an info box.
  924. > **WARNING**
  925. > Watch out for this.
  926. > **NOTE**
  927. > Side note for the reader.
  928. ```
  929. The reverse direction emits the same `> **INFO**` / `> **WARNING**` / `> **NOTE**` blockquote form, so multi-paragraph bodies round-trip cleanly. The bare `[!info]` / `[!warning]` / `[!note]` shorthand is still accepted on input for backwards compatibility.
  930. A blockquote without one of these markers stays a **plain blockquote** (`<blockquote>…</blockquote>`) — `> …` is treated as a quotation, not an alert. Use the markers above when you want a callout.
  931. ### `**TOC**` / `[[_TOC_]]` — Table of Contents
  932. A paragraph containing only `**TOC**`, `[[_TOC_]]`, `<!-- _TOC_ -->`, or `<!-- [[_TOC_]] -->` becomes a Confluence Table of Contents macro using the macro's default heading levels:
  933. ```markdown
  934. **TOC**
  935. [[_TOC_]]
  936. <!-- _TOC_ -->
  937. ```
  938. ### `[[_LISTING_]]` — child page listing
  939. A paragraph containing only `[[_LISTING_]]`, `<!-- _LISTING_ -->`, or `<!-- [[_LISTING_]] -->` becomes a Confluence Children Display macro:
  940. ```markdown
  941. [[_LISTING_]]
  942. <!-- _LISTING_ -->
  943. ```
  944. ### `**ANCHOR: id**` — anchor
  945. A paragraph containing only `**ANCHOR: my-section**` becomes a Confluence anchor macro with the given id:
  946. ```markdown
  947. **ANCHOR: my-section**
  948. ```
  949. ### `**EXPAND: title** … **EXPAND_END**` — collapsible expand macro
  950. Wrap a block of content between `**EXPAND: title**` and `**EXPAND_END**` markers (each on its own paragraph) to render it as a Confluence expand macro with a collapsible body:
  951. ````markdown
  952. **EXPAND: Show generated code**
  953. ```js
  954. const x = 1;
  955. ```
  956. **EXPAND_END**
  957. ````
  958. The body may contain any content that is converted earlier in the pipeline (code blocks, tables, callout blockquotes). The reverse direction emits the same `**EXPAND: title**` / `**EXPAND_END**` markers so the conversion round-trips.
  959. Inline markdown inside the title (`*em*`, backtick code, links, `~~strike~~`) is stripped at capture time — Confluence's storage normalizer treats macro titles as plain text and will silently truncate or reject HTML in a `<ac:parameter>`. Title-less expand macros created in the Confluence UI still convert to `<details>/<summary>` blocks.
  960. ### ```` ```plantuml ```` — PlantUML diagram macro
  961. ````markdown
  962. ```plantuml
  963. @startuml
  964. Alice -> Bob: Authentication Request
  965. @enduml
  966. ```
  967. ````
  968. Emitted as `ac:name="plantuml"` (source in CDATA) by default, or as `ac:name="plantumlcloud"` (compressed `data` parameter, `filename=plantuml-diagram-<n>.svg`, `compressed=true`, `revision=1`, `toolbar=bottom`) when `plantumlFormat` is `plantumlcloud` — see [PlantUML macro format](#plantuml-macro-format-plantumlformat). Both shapes read back as the same fence.
  969. ### `[text](#id)` — same-page anchor link
  970. A standard markdown link whose href starts with `#` becomes an `ac:link` with `ac:anchor`, rendering as an in-page jump in Confluence:
  971. ```markdown
  972. See [the anchor](#my-section) above.
  973. ```
  974. This works under every `linkStyle` mode (`smart`, `plain`, `auto`, `wiki`) — the anchor-link conversion runs before the general `<a href>` handling.
  975. ## Development
  976. ```bash
  977. # Clone the repository
  978. git clone https://github.com/pchuri/confluence-cli.git
  979. cd confluence-cli
  980. # Install dependencies
  981. npm install
  982. # Run locally
  983. npm start -- --help
  984. # Run tests
  985. npm test
  986. # Lint code
  987. npm run lint
  988. ```
  989. ## Contributing
  990. 1. Fork the repository
  991. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  992. 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
  993. 4. Push to the branch (`git push origin feature/amazing-feature`)
  994. 5. Open a Pull Request
  995. ## License
  996. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  997. ## Roadmap
  998. - [x] **Create and update pages** ✅
  999. - [ ] Page templates
  1000. - [ ] Bulk operations
  1001. - [ ] Export pages to different formats
  1002. - [ ] Integration with other Atlassian tools (Jira)
  1003. - [x] Page attachments management (list, download, upload, delete)
  1004. - [x] Comments
  1005. - [ ] Reviews
  1006. ## Support & Feedback
  1007. ### 💬 We'd love to hear from you!
  1008. Your feedback helps make confluence-cli better for everyone. Here's how you can share your thoughts:
  1009. #### 🐛 Found a bug?
  1010. 1. Check the [Issues](https://github.com/pchuri/confluence-cli/issues) page
  1011. 2. Create a new [bug report](https://github.com/pchuri/confluence-cli/issues/new?template=bug_report.md)
  1012. #### 💡 Have a feature idea?
  1013. 1. Create a [feature request](https://github.com/pchuri/confluence-cli/issues/new?template=feature_request.md)
  1014. 2. Join our [Discussions](https://github.com/pchuri/confluence-cli/discussions) to chat with the community
  1015. #### 📝 General feedback?
  1016. - Share your experience with a [feedback issue](https://github.com/pchuri/confluence-cli/issues/new?template=feedback.md)
  1017. - Rate us on [NPM](https://www.npmjs.com/package/confluence-cli)
  1018. - Star the repo if you find it useful! ⭐
  1019. #### 🤝 Want to contribute?
  1020. Check out our [Contributing Guide](CONTRIBUTING.md) - all contributions are welcome!
  1021. ### 📈 Usage Analytics
  1022. confluence-cli tracks command usage statistics **locally** on your machine (in `stats.json` alongside your config file — see [Config file location](#config-file-location) above). No data is sent to any external server. This includes:
  1023. - Command usage counts (success/error)
  1024. You can view your stats with `confluence stats`, or disable tracking by setting: `export CONFLUENCE_CLI_ANALYTICS=false`
  1025. ---
  1026. Made with ❤️ for the Confluence community

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.