confluence-cli

A CLI tool for creating Confluence pages from templates or storage-format HTML, and updating existing pages through downloaded storage-format HTML files.

Installation

Install the published package globally:

npm install -g @h4pplness/confluence-cli

Or install from a local checkout:

npm install -g .

Quick Start

# 1. Configure a profile
confluence-cli config set

# 2. List available templates
confluence-cli template list

# 3. Inspect template variables
confluence-cli template detail feature-design

# 4. Create a new page
confluence-cli page create \
  --space "DEV" \
  --parent "123456" \
  --title "Authentication Module" \
  --template "feature-design" \
  --data '{"title":"Authentication Module","mo_ta_chuc_nang":"...","thiet_ke_api":"..."}'

# Or use a JSON file
confluence-cli page create --from-file ./input.json

# Download, edit, and update an existing page
confluence-cli page get --page-id "789012" --download
confluence-cli page update --file ./confluence-pages/789012-v3-page-title.html --dry-run
confluence-cli page update --file ./confluence-pages/789012-v3-page-title.html

Config

Set Up a Profile

confluence-cli config set                    # Interactive wizard
confluence-cli config set --profile dc-prod  # Specific profile name

The CLI supports 3 authentication methods:

| Method | Use case | Header | |---|---|---| | cloud_basic | Confluence Cloud | Basic base64(email:apiToken) | | server_basic | Server / Data Center | Basic base64(username:password) | | pat | Server / Data Center v7.9+ | Bearer <token> |

Config Commands

confluence-cli config list                   # List profiles
confluence-cli config show                   # Show active profile details
confluence-cli config show --profile dc-prod
confluence-cli config use dc-prod            # Switch active profile
confluence-cli config delete dc-prod         # Delete a profile
confluence-cli config test                   # Test the connection

Template

Manage Templates

confluence-cli template list                          # List templates
confluence-cli template detail feature-design         # Show details and variables
confluence-cli template detail feature-design --full  # Also show generated HTML
confluence-cli template create                        # Create a template interactively
confluence-cli template create --name my-tpl --file ./my.hbs
confluence-cli template delete my-tpl
confluence-cli template export my-tpl --output ./export/
confluence-cli template import ./my.hbs ./my.json

Template Structure

Each template contains 2 files stored in the app data directory:

feature-design.hbs - HTML content using Handlebars:

<h1>{{title}}</h1>
<h2>Feature Description</h2>
<p>{{{mo_ta_chuc_nang}}}</p>

{{var}} escapes HTML | {{{var}}} preserves raw HTML and line breaks

feature-design.json - Metadata:

{
  "name": "feature-design",
  "displayName": "Feature Design",
  "variables": [
    { "key": "mo_ta_chuc_nang", "label": "Description", "required": true, "type": "text" }
  ]
}

System variables are injected automatically and do not need to be provided:

• {{_generated_at}} - generation time
• {{_template_name}} - template name

Page

Create a Page

# Using flags
confluence-cli page create \
  --space "DEV" \
  --parent "123456" \
  --title "Page Title" \
  --template "feature-design" \
  --data '{"mo_ta_chuc_nang":"...", "thiet_ke_api":"..."}'

# Using a JSON file
confluence-cli page create --from-file ./input.json

# Without a template: create from a Confluence storage HTML file
confluence-cli page create \
  --space "DEV" \
  --parent "123456" \
  --title "Page Title" \
  --file ./page.html

# Without a template: provide storage HTML directly
confluence-cli page create \
  --space "DEV" \
  --title "Page Title" \
  --html "<p>Page content</p>"

# Dry run: preview HTML without calling the API
confluence-cli page create --from-file ./input.json --dry-run

Update a Page

# Download raw Confluence storage HTML and metadata
confluence-cli page get --page-id "789012" --download

# Edit the downloaded .html file, then dry-run the update
confluence-cli page update --file ./confluence-pages/789012-v3-page-title.html --dry-run

# Push the edited file back to Confluence
confluence-cli page update --file ./confluence-pages/789012-v3-page-title.html

# Optional: change the title while updating body HTML
confluence-cli page update --file ./confluence-pages/789012-v3-page-title.html --title "Page Title v2"

Downloaded pages are saved to ./confluence-pages/ by default as a .html body file plus a .meta.json file. The metadata records the page ID, title, version, URL, and profile name. page update --file checks the downloaded version against the current server version and stops if the page changed; use --force only when you intentionally want to overwrite with the local file.

Create JSON File Format (--from-file)

Create:

Using a template:

{
  "spaceKey": "DEV",
  "parentPageId": "123456",
  "title": "Authentication Module",
  "templateName": "feature-design",
  "data": {
    "title": "Authentication Module",
    "mo_ta_chuc_nang": "Handle login/logout with JWT",
    "thiet_ke_api": "POST /auth/login\nPOST /auth/refresh",
    "thiet_ke_database": "Tables: users, refresh_tokens"
  }
}

Without a template, provide either contentFile:

{
  "spaceKey": "DEV",
  "parentPageId": "123456",
  "title": "Authentication Module",
  "contentFile": "./page.html"
}

Or provide htmlContent directly:

{
  "spaceKey": "DEV",
  "title": "Authentication Module",
  "htmlContent": "<h1>Authentication Module</h1><p>Page content</p>"
}

spaceKey and title are required. Provide exactly one content source: templateName, contentFile, or htmlContent. parentPageId is optional. Content must use Confluence storage-format HTML.

Get Page Details

confluence-cli page get --page-id "789012"
confluence-cli page get --page-id "789012" --raw
confluence-cli page get --page-id "789012" --download
confluence-cli page get --page-id "789012" --download --output ./docs

Search

Search for Confluence pages by keyword or CQL (Confluence Query Language).

Search by Keyword

# Simple keyword search
confluence-cli search "authentication module"

# Limit search to a specific space
confluence-cli search "release notes" --space DEV

# Limit number of results
confluence-cli search "API" --limit 20

Search by CQL

# Direct CQL query
confluence-cli search --cql 'type=page AND label="release"'

# CQL with space filter
confluence-cli search --cql 'creator=currentUser()' --space DEV

# Recently modified pages
confluence-cli search --cql 'lastModified > now("-7d")'

Pagination

# First 10 results (default)
confluence-cli search "keyword"

# Next 10 results
confluence-cli search "keyword" --start 10

# Custom page size
confluence-cli search "keyword" --limit 5 --start 15

Search Options

| Option | Description | |---|---| | --cql <cql> | Direct CQL query (takes priority over keyword) | | -s, --space <key> | Limit search to a specific space | | -l, --limit <n> | Max results (default: 10) | | --start <n> | Start offset for pagination | | -p, --profile <name> | Auth profile (default: active profile) |

Data Location

| OS | Config & Templates | |---|---| | Windows | %APPDATA%\confluence-cli\ | | macOS | ~/Library/Application Support/confluence-cli/ | | Linux | ~/.config/confluence-cli/ |