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

# 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)

# Launch configuration wizard
confluence init

The wizard will guide you through:

1. Selecting your Confluence instance type (Cloud or self-hosted)
2. Choosing appropriate API endpoints
3. Setting up authentication

Environment Variables

Alternatively, configure using environment variables:

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

1. Go to: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Label your token (e.g., "confluence-cli")
4. 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:

# 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:

# 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):

# 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:

# List all spaces
confluence spaces

Returns: Space keys, names, types, and URLs

5. Find Pages by Title

Locate pages by exact or partial title:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# View usage statistics
confluence stats

Disable analytics:

export CONFLUENCE_CLI_ANALYTICS=false

Content Formats

Storage Format (Confluence Native)

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

<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:

<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:

# Heading

Paragraph with **bold** text.

- List item 1
- List item 2

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

**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:

# 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:

# 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

#!/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

# 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

# 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

# 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

# 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

# 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

#!/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

# 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:

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

Troubleshooting

Authentication Issues

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

# Re-run initialization
confluence init

# Test connection
confluence spaces

API Errors

# 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

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

Content Format Issues

# 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

# 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)