Confluence CLI (NPM Package)

Overview

confluence-cli is a community-developed command-line interface for Atlassian Confluence that enables content management directly from the terminal. This is a third-party tool (not official Atlassian), available via NPM.

Use this skill when:

•Users request CLI-based Confluence operations
•Documentation workflows need automation
•Bulk page operations are required
•Content migration between spaces is needed
•Users want to script documentation updates

Important: This is NOT the official Atlassian CLI (acli), which does not support Confluence. This is a community tool: https://github.com/pchuri/confluence-cli

Installation

Prerequisites

•Node.js and NPM installed

Install Options

bash

# Global installation (recommended for frequent use)
npm install -g confluence-cli

# Or use directly with npx (no installation)
npx confluence-cli --help

Configuration

Interactive Setup (Recommended)

bash

# Launch configuration wizard
confluence init

The wizard will guide you through:

•Selecting your Confluence instance type (Cloud or self-hosted)
•Choosing appropriate API endpoints
•Setting up authentication

Environment Variables

Alternatively, configure using environment variables:

bash

export CONFLUENCE_DOMAIN="yourcompany.atlassian.net"
export CONFLUENCE_EMAIL="your@email.com"
export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_API_PATH="/wiki/rest/api"  # Cloud default
export CONFLUENCE_AUTH_TYPE="basic"  # or "bearer"

API Path Defaults:

•Cloud: /wiki/rest/api
•Self-hosted/Data Center: /rest/api

Authentication

Getting API Tokens

•Go to: https://id.atlassian.com/manage-profile/security/api-tokens
•Click "Create API token"
•Label your token (e.g., "confluence-cli")
•Copy the generated token

Authentication Types

Basic Auth (Cloud - Default)

•Requires: Email + API Token
•Used automatically when CONFLUENCE_EMAIL is set

Bearer Token (Self-hosted/Data Center)

•Requires: Bearer token only
•Set CONFLUENCE_AUTH_TYPE="bearer"

Core Commands

1. Read Pages

Retrieve page content in various formats:

bash

# Read as text (default)
confluence read 123456789

# Read as HTML
confluence read 123456789 --format html

# Read as Markdown
confluence read 123456789 --format markdown

# Using page URL instead of ID
confluence read "https://yourcompany.atlassian.net/wiki/spaces/SPACE/pages/123456789"

Formats:

•text - Plain text (default)
•html - HTML format
•markdown - Markdown format (useful for documentation workflows)

2. Get Page Information

View metadata about a page:

bash

# Get page metadata
confluence info 123456789

# Using URL
confluence info "https://yourcompany.atlassian.net/wiki/spaces/SPACE/pages/123456789"

Returns: Page ID, title, space, version, created/modified dates, authors, etc.

3. Search Content

Find pages using Confluence Query Language (CQL):

bash

# Basic search
confluence search "API documentation"

# Search with result limit
confluence search "meeting notes" --limit 10

# Complex CQL queries
confluence search "type=page AND space=DEV AND title~'API'"

Common CQL Patterns:

•type=page - Pages only (not attachments)
•space=SPACEKEY - Within specific space
•title~'keyword' - Title contains keyword
•text~'keyword' - Content contains keyword
•created >= now()-7d - Created in last 7 days

4. List Spaces

View all accessible spaces:

bash

# List all spaces
confluence spaces

Returns: Space keys, names, types, and URLs

5. Find Pages by Title

Locate pages by exact or partial title:

bash

# Find in all spaces
confluence find "Project Documentation"

# Find in specific space
confluence find "API Guide" --space DEV

6. Create Pages

Create new pages with content:

bash

# Create with inline content
confluence create "My New Page" SPACEKEY --content "Hello World!"

# Create from file
confluence create "Documentation" SPACEKEY --file ./content.md --format markdown

# Create with HTML content
confluence create "Release Notes" SPACEKEY --content "<h1>Version 2.0</h1>" --format html

# Create with storage format (Confluence native)
confluence create "Technical Doc" SPACEKEY --file ./doc.xml --format storage

Key options:

•--content - Inline content string
•--file - Read content from file
•--format - Content format: markdown, html, or storage (default: storage)

7. Create Child Pages

Create pages under existing parent pages:

bash

# Create child page with inline content
confluence create-child "Subsection" 123456789 --content "Child content"

# Create from file
confluence create-child "API Reference" 123456789 --file ./api-docs.md --format markdown

# Using parent page URL
confluence create-child "Details" "https://...pages/123456789" --content "Details here"

8. Update Pages

Modify existing pages:

bash

# Update title only
confluence update 123456789 --title "Updated Title"

# Update content only
confluence update 123456789 --content "New content" --format markdown

# Update from file
confluence update 123456789 --file ./updated-content.md --format markdown

# Update both title and content
confluence update 123456789 --title "New Title" --content "New content"

Key options:

•--title - Change page title
•--content - Inline content
•--file - Read content from file
•--format - Content format (markdown, html, storage)

9. Edit Workflow (Export → Modify → Update)

Export page for local editing:

bash

# Export page to file in storage format
confluence edit 123456789 --output ./page.xml

# Edit the file locally with your preferred editor
# Then update back to Confluence
confluence update 123456789 --file ./page.xml --format storage

This workflow is useful for:

•Complex formatting changes
•Offline editing
•Version control integration
•Batch processing

10. Copy Page Trees

Duplicate page hierarchies with all children:

bash

# Copy entire page tree
confluence copy-tree 123456789 987654321

# Copy with custom title for root page
confluence copy-tree 123456789 987654321 "Copied Documentation"

# Limit depth of copy
confluence copy-tree 123456789 987654321 --max-depth 2

# Exclude pages by pattern (wildcards supported)
confluence copy-tree 123456789 987654321 --exclude "temp*,*draft*,*obsolete*"

# Add delay between operations (for rate limiting)
confluence copy-tree 123456789 987654321 --delay-ms 500

# Dry run (preview without making changes)
confluence copy-tree 123456789 987654321 --dry-run

Key options:

•--max-depth <number> - Limit tree depth (default: unlimited)
•--exclude <patterns> - Comma-separated wildcard patterns to skip
•--delay-ms <number> - Milliseconds delay between API calls
•--dry-run - Preview what would be copied without making changes

Exclusion patterns:

•* matches any characters
•? matches single character
•Examples: temp*, *draft*, archive-?

11. View Statistics

Check CLI usage analytics:

bash

# View usage statistics
confluence stats

Disable analytics:

bash

export CONFLUENCE_CLI_ANALYTICS=false

Content Formats

Storage Format (Confluence Native)

Confluence's internal XML-based format (XHTML):

xml

<p>This is <strong>bold</strong> and <em>italic</em> text.</p>
<ac:structured-macro ac:name="code">
  <ac:plain-text-body><![CDATA[console.log('Hello');]]></ac:plain-text-body>
</ac:structured-macro>

When to use:

•Maximum fidelity for Confluence-specific features
•Macros, layouts, and advanced formatting
•Export/import workflows

HTML Format

Standard HTML:

html

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> text.</p>
<ul>
  <li>List item 1</li>
  <li>List item 2</li>
</ul>

When to use:

•Familiar syntax
•Converting from other HTML sources
•Simple formatting needs

Markdown Format

GitHub-flavored Markdown:

markdown

# Heading

Paragraph with **bold** text.

- List item 1
- List item 2

```code
console.log('Hello');

code


**When to use:**
- Developer documentation
- README files and similar content
- Simple, readable syntax
- Integration with markdown-based tools

**Note**: Markdown is converted to storage format server-side. Complex Confluence features may not be available.

## Best Practices

### 1. Authentication and Security

```bash
# Store credentials securely in environment variables
# Add to ~/.bashrc, ~/.zshrc, or use a secrets manager
export CONFLUENCE_API_TOKEN="your-token-here"

# Rotate API tokens regularly
# Revoke old tokens from: https://id.atlassian.com/manage-profile/security/api-tokens

# Use separate tokens for different environments
export CONFLUENCE_DEV_TOKEN="dev-token"
export CONFLUENCE_PROD_TOKEN="prod-token"

2. Bulk Operations

For bulk operations, combine with shell tools:

bash

# Search and process multiple pages
confluence search "type=page AND space=DEV" | while read -r line; do
  # Extract page ID and process
  # Add delays to respect rate limits
  sleep 1
done

# Batch create pages from directory of markdown files
for file in docs/*.md; do
  title=$(basename "$file" .md)
  confluence create "$title" DEV --file "$file" --format markdown
  sleep 0.5  # Rate limit protection
done

3. Rate Limiting

Respect Confluence API rate limits:

bash

# Add delays in scripts
sleep 0.5  # 500ms between calls

# Use --delay-ms for copy-tree operations
confluence copy-tree SOURCE TARGET --delay-ms 500

# Monitor for rate limit errors and implement backoff

4. Error Handling in Scripts

bash

#!/bin/bash

# Check if confluence is installed
if ! command -v confluence &> /dev/null; then
  echo "confluence-cli not found. Install: npm install -g confluence-cli"
  exit 1
fi

# Check authentication
if ! confluence spaces &> /dev/null; then
  echo "Authentication failed. Run: confluence init"
  exit 1
fi

# Perform operations with error checking
if confluence create "My Page" DEV --content "Hello"; then
  echo "Page created successfully"
else
  echo "Failed to create page"
  exit 1
fi

5. Version Control Integration

bash

# Export pages for version control
mkdir -p confluence-backup
for page_id in 123456 234567 345678; do
  confluence read "$page_id" --format markdown > "confluence-backup/${page_id}.md"
done

# Commit to git
cd confluence-backup
git add .
git commit -m "Backup Confluence pages"
git push

6. Content Migration

bash

# Migrate space documentation to new space

# 1. Export all pages from source space
SOURCE_SPACE="OLD"
TARGET_SPACE="NEW"

# Get root pages in source space
confluence search "type=page AND space=$SOURCE_SPACE AND parent is null" > root_pages.txt

# 2. For each root page, copy tree to target space
# (Manual: create corresponding parent page in target space first)
# Then copy children:
confluence copy-tree SOURCE_PAGE_ID TARGET_PAGE_ID

Common Use Cases

Documentation Workflow

bash

# 1. Create documentation structure
confluence create "API Documentation" DEV --content "# API Docs"
ROOT_ID=123456789

# 2. Create subsections
confluence create-child "Authentication" $ROOT_ID --file ./auth.md --format markdown
confluence create-child "Endpoints" $ROOT_ID --file ./endpoints.md --format markdown
confluence create-child "Examples" $ROOT_ID --file ./examples.md --format markdown

# 3. Update as docs evolve
confluence update $ROOT_ID --file ./updated-overview.md --format markdown

Content Search and Export

bash

# Find and export all API documentation
confluence search "type=page AND title~'API'" --limit 50 | \
  grep -o '[0-9]\{8,\}' | \
  while read page_id; do
    confluence read "$page_id" --format markdown > "export/${page_id}.md"
  done

Space Migration

bash

# Copy documentation from one space to another
# (Requires manual creation of target parent page first)

SOURCE_ROOT=123456789  # Root page in source space
TARGET_ROOT=987654321  # Root page in target space (pre-created)

confluence copy-tree $SOURCE_ROOT $TARGET_ROOT "Migrated Documentation" \
  --exclude "*draft*,*temp*" \
  --delay-ms 500 \
  --dry-run  # Remove after verifying

Automated Updates

bash

#!/bin/bash
# Update release notes automatically

VERSION="2.0.0"
DATE=$(date +"%Y-%m-%d")
PAGE_ID=123456789

# Generate release notes from git log
echo "# Release $VERSION ($DATE)" > release-notes.md
echo "" >> release-notes.md
git log --oneline --since="2 weeks ago" >> release-notes.md

# Update Confluence page
confluence update $PAGE_ID --file release-notes.md --format markdown

echo "Release notes updated for version $VERSION"

Backup and Restore

bash

# Backup script
BACKUP_DIR="./confluence-backup-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Export pages from specific space
confluence search "type=page AND space=DEV" | \
  grep -o '[0-9]\{8,\}' | \
  while read page_id; do
    confluence read "$page_id" --format storage > "$BACKUP_DIR/${page_id}.xml"
    confluence info "$page_id" > "$BACKUP_DIR/${page_id}-info.json"
    sleep 0.5
  done

tar -czf "confluence-backup-$(date +%Y%m%d).tar.gz" "$BACKUP_DIR"

Integration with Claude Code

When using this skill in Claude Code:

•Check installation: Verify confluence command is available
•Verify authentication: Run confluence spaces to test
•Use Bash tool: Execute confluence commands via Bash tool
•Parse output: Most commands output human-readable text; use --format flags where available
•Handle page IDs: Extract page IDs from URLs or search results
•Rate limiting: Add delays in bulk operations
•Error handling: Check exit codes and provide helpful error messages
•Confirm destructive operations: Warn before bulk updates or deletions

Troubleshooting

Authentication Issues

bash

# Check if configuration exists
ls -la ~/.confluence/

# Re-run initialization
confluence init

# Test connection
confluence spaces

API Errors

bash

# Verify API token is valid
# Check: https://id.atlassian.com/manage-profile/security/api-tokens

# Ensure correct domain format
# Cloud: "yourcompany.atlassian.net"
# NOT: "https://yourcompany.atlassian.net"

# Check API path matches your instance type
# Cloud: /wiki/rest/api
# Self-hosted: /rest/api

Rate Limiting

bash

# If you encounter rate limits:
# - Add delays between operations (--delay-ms or sleep)
# - Reduce batch sizes
# - Space out operations over time

Content Format Issues

bash

# If content doesn't render correctly:
# - Try different format: --format storage, html, or markdown
# - Export existing similar page to see format: confluence edit PAGE_ID --output example.xml
# - Use storage format for maximum compatibility

Limitations

Third-Party Tool

•Not official Atlassian product: Community-maintained
•Support: Through GitHub issues, not Atlassian support
•Updates: Dependent on community contributions
•Compatibility: May lag behind Confluence API changes

API Limitations

•No attachment management: Cannot upload/download attachments via this CLI
•Limited macro support: Complex Confluence macros may not work with markdown/HTML formats
•No admin operations: User/space management not supported
•Rate limits: Subject to Confluence Cloud API rate limits

Format Conversions

•Markdown limitations: Not all Confluence features available in markdown
•HTML to storage: May require manual adjustment for complex layouts
•Macros: Best created/edited in storage format

Alternative Tools

Official Atlassian CLI (acli)

•Status: Does NOT currently support Confluence (only Jira)
•If support added: May become preferred official tool
•Current: Use for Jira operations only

Appfire Confluence CLI

•Type: Commercial Marketplace app
•Features: More comprehensive admin/automation features
•Cost: Requires purchase/licensing
•Use case: Enterprise automation, advanced admin tasks

Confluence REST API

•Direct API calls: Using curl or similar tools
•Flexibility: Maximum control
•Complexity: More code required
•Use case: Custom integrations, specific requirements

Help and Documentation

bash

# Main help
confluence --help

# Command help
confluence read --help
confluence create --help
confluence copy-tree --help

# Version info
confluence --version

External Resources:

•GitHub: https://github.com/pchuri/confluence-cli
•NPM: https://www.npmjs.com/package/confluence-cli
•Confluence REST API: https://developer.atlassian.com/cloud/confluence/rest/v1/

Important Notes

•Third-party tool: Not official Atlassian - community-developed
•Cloud and self-hosted: Supports both, but configuration differs
•API tokens: Required for authentication - obtain from Atlassian account settings
•Rate limits: Respect Confluence API rate limits in bulk operations
•Content formats: Storage format provides best fidelity for Confluence features
•No official CLI: Atlassian's official CLI (acli) does not support Confluence currently
•Analytics: Tool collects anonymous usage data (opt-out via environment variable)