Manage Confluence from the Command Line

Why Manage Confluence from the Terminal?

Confluence is the documentation hub for most Atlassian teams, but the web editor is optimized for writing single pages -- not for managing hundreds of them at scale. When you need to export an entire space, audit stale pages, bulk-add labels, or synchronize documentation from a Git repository, the browser becomes a bottleneck.

A Confluence CLI tool lets you script these operations. Search pages with CQL (Confluence Query Language), pipe results to jq, export spaces to JSON for backup, upload attachments from CI/CD pipelines, and manage permissions across spaces -- all without clicking through the web UI. If you already use atlassian-cli for Jira or Bitbucket, the Confluence commands follow the same patterns: profiles, output formats, dry-run, and bulk operations.

This guide covers every Confluence command available in atlassian-cli, with copy-paste examples for each.

Getting Started

Install

# Homebrew (macOS / Linux)
brew tap omar16100/atlassian-cli
brew install atlassian-cli

# Cargo (Rust toolchain)
cargo install atlassian-cli

# Verify
atlassian-cli --version

Authentication

Confluence uses the same Atlassian API tokens as Jira. Create a token at id.atlassian.com, then set up a profile:

# Add a profile
atlassian-cli auth login \
  --profile work \
  --base-url your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

# Verify
atlassian-cli auth list

Credentials are stored with AES-256-GCM encryption in ~/.atlassian-cli/config.yaml. The same profile works for both Jira and Confluence commands -- no separate setup needed.

First command

# List available Confluence spaces
atlassian-cli confluence space list --limit 10

CQL Search

CQL (Confluence Query Language) is the most powerful way to find content. The confluence search command supports three modes: raw CQL queries, full-text search, and space-scoped search.

CQL queries

Use search cql for structured queries with exact control over space, type, label, and date filters:

# All pages in a specific space
atlassian-cli confluence search cql \
  --cql "space = DEV and type = page" \
  --limit 5

# Pages with a specific label
atlassian-cli confluence search cql \
  --cql "label = 'api-docs' and type = page"

# Recently updated pages across all spaces
atlassian-cli confluence search cql \
  --cql "type = page and lastModified >= '2026-01-01'" \
  --format json

# Blog posts in a space
atlassian-cli confluence search cql \
  --cql "space = ENG and type = blogpost"

# Pages containing specific text
atlassian-cli confluence search cql \
  --cql "text ~ 'deployment runbook' and space = OPS"

Full-text and space-scoped search

For simpler searches where you do not need full CQL syntax:

# Full-text search across all spaces
atlassian-cli confluence search text \
  --query "meeting notes" \
  --limit 10

# Search within a specific space
atlassian-cli confluence search in-space \
  --space DEV \
  --query "api docs"

All search commands support --format json, --format csv, and --format yaml for downstream processing.

Space Management

Spaces are the top-level containers in Confluence. The CLI gives you full CRUD operations plus permission management.

# List all spaces
atlassian-cli confluence space list --limit 10

# Get details for a specific space
atlassian-cli confluence space get DEV

# Create a new space
atlassian-cli confluence space create \
  --key DOCS \
  --name "Documentation" \
  --description "Team docs"

# Update space name
atlassian-cli confluence space update DEV \
  --name "Development Space"

# Delete a space (requires --force for safety)
atlassian-cli confluence space delete OLD --force

Permissions

View and manage who can access a space directly from the terminal:

# View current permissions
atlassian-cli confluence space permissions DEV

# Grant read access to a user
atlassian-cli confluence space add-permission DEV \
  --principal user@example.com \
  --operation read

Page Operations

Pages are the core content unit in Confluence. The CLI covers creating, updating, versioning, labeling, commenting, and managing restrictions.

CRUD operations

# List pages in a space
atlassian-cli confluence page list --space DEV --limit 25

# Get a page by ID
atlassian-cli confluence page get --id 12345

# Create a new page
atlassian-cli confluence page create \
  --space DEV \
  --title "New Page" \
  --body "<p>Page content here</p>"

# Update a page title
atlassian-cli confluence page update --id 12345 \
  --title "Updated Title"

# Delete a page
atlassian-cli confluence page delete --id 12345

Labels and comments

# Add a label to a page
atlassian-cli confluence page add-label --id 12345 \
  --label documentation

# Remove a label
atlassian-cli confluence page remove-label --id 12345 \
  --label outdated

# List comments on a page
atlassian-cli confluence page comments --id 12345

# Add a comment
atlassian-cli confluence page add-comment --id 12345 \
  --body "Reviewed and approved."

Versions and restrictions

# View page version history
atlassian-cli confluence page versions --id 12345

# View page restrictions
atlassian-cli confluence page get-restrictions --id 12345

# Restrict editing to a specific user
atlassian-cli confluence page add-restriction --id 12345 \
  --operation update \
  --user user@example.com

# Remove a restriction
atlassian-cli confluence page remove-restriction --id 12345 \
  --operation update \
  --user user@example.com

Attachments

Upload, download, and manage file attachments on any page:

# List attachments on a page
atlassian-cli confluence attachment list --page-id 12345

# Upload a file
atlassian-cli confluence attachment upload \
  --page-id 12345 \
  --file ./diagram.png

# Download an attachment
atlassian-cli confluence attachment download \
  --id 11111 \
  --output ./download.png

# Get attachment metadata
atlassian-cli confluence attachment get --id 11111

# Delete an attachment
atlassian-cli confluence attachment delete --id 11111

Blog posts

Blog posts in Confluence follow the same pattern as pages:

# List blog posts
atlassian-cli confluence blog list --space DEV --limit 10

# Create a blog post
atlassian-cli confluence blog create \
  --space DEV \
  --title "Sprint Recap" \
  --body "<p>Summary of sprint work</p>"

# Update a blog post
atlassian-cli confluence blog update --id 67890 \
  --title "Updated Recap"

# Delete a blog post
atlassian-cli confluence blog delete --id 67890

Bulk Export & Backup

Bulk operations are where the Confluence CLI delivers the most value. Exporting hundreds of pages, bulk-labeling content, or deleting stale pages would take hours in the browser. The CLI handles it with concurrency, rate-limit awareness, and dry-run previews.

Bulk export

# Export all pages from a space to JSON
atlassian-cli confluence bulk export \
  --space DEV \
  --output backup.json \
  --format json

# Export pages matching a CQL query
atlassian-cli confluence bulk export \
  --cql "space = DOCS AND type = page" \
  --output docs-export.json \
  --format json

Bulk label management

# Preview: add labels to pages matching CQL (dry-run)
atlassian-cli confluence bulk add-labels \
  --cql "space = DEV" \
  --labels docs,reviewed \
  --dry-run

# Execute the label addition
atlassian-cli confluence bulk add-labels \
  --cql "space = DEV" \
  --labels docs,reviewed

Bulk delete

# Preview: delete all pages in a space (dry-run first!)
atlassian-cli confluence bulk delete --space OLD --dry-run

# Execute the deletion
atlassian-cli confluence bulk delete --space OLD

Backup script example

Combine Confluence CLI commands with shell scripting for automated nightly backups:

#!/bin/bash
# Nightly Confluence backup script
DATE=$(date +%Y-%m-%d)
BACKUP_DIR="./confluence-backups/$DATE"
mkdir -p "$BACKUP_DIR"

# Export each critical space
for SPACE in DEV OPS DOCS ENG; do
  echo "Exporting space: $SPACE"
  atlassian-cli confluence bulk export \
    --space "$SPACE" \
    --output "$BACKUP_DIR/${SPACE}.json" \
    --format json
done

# Export space metadata
atlassian-cli confluence space list \
  --format json > "$BACKUP_DIR/spaces-metadata.json"

echo "Backup complete: $BACKUP_DIR"

Markdown to Confluence

Many teams write documentation in Markdown and store it in Git. You can convert Markdown to Confluence storage format using pandoc and publish it with the CLI. This creates a documentation pipeline that keeps Confluence pages in sync with your repository.

# Convert Markdown to Confluence storage format (XHTML)
pandoc README.md -f markdown -t html -o /tmp/page-body.html

# Read the converted HTML and create a Confluence page
BODY=$(cat /tmp/page-body.html)
atlassian-cli confluence page create \
  --space DOCS \
  --title "Project README" \
  --body "$BODY"

# Or update an existing page
atlassian-cli confluence page update --id 12345 \
  --title "Project README"

In CI/CD, this pattern runs on every merge to main, keeping your Confluence documentation automatically in sync with the codebase. The same approach works for publishing ADRs (Architecture Decision Records), runbooks, or any documentation that lives in Git.

Real-World Workflows

Documentation sync from Git

Automatically publish Markdown documentation to Confluence on every merge to main. Set ATLASSIAN_CLI_TOKEN_DEFAULT, ATLASSIAN_CLI_EMAIL, and ATLASSIAN_CLI_BASE_URL as pipeline environment variables, then use the Markdown-to-Confluence pattern above in a CI step. Every merge publishes the latest docs.

Space audit

Find stale or orphaned pages across spaces:

# Pages not updated in 6 months
atlassian-cli confluence search cql \
  --cql "type = page and lastModified < '2025-09-01'" \
  --format json

# Space-level analytics
atlassian-cli confluence analytics space-stats --space DEV

# Page view stats for a specific page
atlassian-cli confluence analytics page-views --id 12345 \
  --from 2025-01-01

Migration between spaces

Export pages from one space and use the data to recreate them in another. The JSON export contains page titles, bodies, labels, and metadata -- everything needed to rebuild a space:

# Export source space
atlassian-cli confluence bulk export \
  --space OLD_DOCS \
  --output migration.json \
  --format json

# Create the target space
atlassian-cli confluence space create \
  --key NEW_DOCS \
  --name "New Documentation" \
  --description "Migrated from OLD_DOCS"