Export and Back Up Confluence Spaces from the CLI

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

A confluence space export from the command line means pointing a single command at a space key and getting every page, blog post, and comment in that space back as one machine-readable file. With atlassian-cli the whole space becomes a JSON archive you can commit to git, drop in object storage, or diff against last week's copy. Because it is one non-interactive command, the same export doubles as a scheduled backup: wrap it in a script, add a cron line, and you have off-Confluence copies of your knowledge base without ever opening a browser.

This guide focuses narrowly on the space-level export and backup loop: dumping a full space, choosing the right format, capturing the parts the JSON does not cover (attachments and permissions), and scheduling it. For a broader walkthrough of restore strategy and retention, see the Confluence backup runbook.

What a Confluence space export captures

Before exporting, it helps to know what a space actually contains and which parts a JSON export preserves. A Confluence space is a container of content plus configuration:

• Content, pages, blog posts, and the comments attached to them. This is the bulk of what you want to preserve, and it is exactly what the bulk export writes to JSON.
• Attachments, images, PDFs, and other binaries embedded in pages. These are separate files, so they need a separate download pass (covered below).
• Configuration, the space name, description, and permission grants. These live on the space object, not in page bodies, so snapshot them explicitly.

Start by finding the space key you want to export. Space keys are the short uppercase identifiers (like DOCS or ENG) that appear in page URLs:

# List every space you can see, with its key
atlassian-cli confluence space list --limit 50

# Inspect one space before backing it up
atlassian-cli confluence space get DOCS

The space get output confirms you are targeting the right space and shows its name and type. Once you have the key, the export itself is a single command.

Export a whole space in one command

The workhorse is confluence bulk export. Instead of a page ID, you give it a CQL query, and any query that matches a whole space will export that entire space in one shot. Preview first with --dry-run so you know how much content is about to move:

# Preview: how many items match, nothing is written
atlassian-cli confluence bulk export \
  --cql "space = DOCS" \
  --output docs-backup.json \
  --format json \
  --dry-run

# Run the real export of the whole space
atlassian-cli confluence bulk export \
  --cql "space = DOCS" \
  --output docs-backup.json \
  --format json

The CLI paginates through the entire result set automatically, so a space with 2,000 pages ends up in one docs-backup.json file without you touching a page-token. Large spaces process concurrently; if you are on a rate-limited instance you can dial the parallelism down:

# Gentler on rate limits for very large spaces
atlassian-cli confluence bulk export \
  --cql "space = DOCS" \
  --output docs-backup.json \
  --format json \
  --concurrency 2

You do not always need the whole space. CQL lets you scope the export to exactly the slice you care about, which is useful for incremental backups that only capture what changed:

# Pages only (skip blog posts and comments)
atlassian-cli confluence bulk export \
  --cql "space = DOCS and type = page" \
  --output docs-pages.json \
  --format json

# Only content modified in the last 7 days: a delta backup
atlassian-cli confluence bulk export \
  --cql "space = DOCS and lastmodified > now(\"-7d\")" \
  --output docs-delta.json \
  --format json

Because everything is driven by CQL, the same mechanism scales from a single space to a curated subset of pages across spaces. See the command reference for the full list of Confluence subcommands and global flags.

Choose an archival format

atlassian-cli accepts --format on every command. For a backup, the format you pick decides how faithful and how reusable the archive is. Here is how the options compare for space export specifically:

For the durable backup, keep JSON. To also produce a quick flat index of what a space contains, run a CQL search and write CSV alongside the archive:

# Flat inventory of every page: title, id, and more
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format csv \
  --limit 500 > docs-inventory.csv

If what you actually want is portable, readable copies of each page rather than a structural backup, that is a different job. The export Confluence to Markdown guide and the markdown sync runbook cover converting page bodies to .md files for a docs-as-code workflow. This post stays focused on the JSON archive you would restore from.

Back up attachments and permissions

The JSON export captures page content and structure, but two things live outside page bodies: binary attachments and the space's permission grants. A complete backup captures both.

Attachments

Attachments are separate files, so back them up with a loop: list the pages in the space, list each page's attachments, and download every one. This uses confluence attachment list and confluence attachment download:

# Download every attachment in a space to ./attachments/
mkdir -p attachments
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format json --limit 500 \
| jq -r '.[].id' \
| while read -r PAGE; do
    atlassian-cli confluence attachment list "$PAGE" --format json \
    | jq -r '.[].id' \
    | while read -r ATT; do
        atlassian-cli confluence attachment download "$ATT" \
          --output "attachments/$ATT"
      done
  done

Space configuration and permissions

Snapshot the space object and its permission grants as JSON so you can see exactly who had access at backup time. This is invaluable if you ever need to recreate the space or audit an access change:

# Space metadata (name, description, type)
atlassian-cli confluence space get DOCS --format json > docs-space.json

# Permission grants at the time of backup
atlassian-cli confluence space permissions DOCS --format json > docs-permissions.json

Together, the content JSON, the attachments directory, and these two metadata files make a self-contained snapshot of the space. For an ongoing view of size and activity that helps you decide backup frequency, the space report runbook pulls page counts and analytics per space.

Schedule automated space backups

The real payoff of a CLI export is that it runs unattended. Because there is no interactive prompt, you can put the whole backup in a shell script and hand it to cron. Save this as backup-space.sh:

#!/usr/bin/env bash
# Usage: backup-space.sh SPACEKEY
set -euo pipefail

SPACE="${1:?usage: backup-space.sh SPACEKEY}"
PROFILE="prod"
STAMP="$(date +%Y-%m-%d)"
DEST="$HOME/confluence-backups/$SPACE/$STAMP"
mkdir -p "$DEST"

# 1. Space metadata and permissions
atlassian-cli confluence space get "$SPACE" --profile "$PROFILE" \
  --format json > "$DEST/space.json"
atlassian-cli confluence space permissions "$SPACE" --profile "$PROFILE" \
  --format json > "$DEST/permissions.json"

# 2. All pages, blog posts, and comments
atlassian-cli confluence bulk export \
  --cql "space = $SPACE" \
  --output "$DEST/content.json" \
  --format json \
  --profile "$PROFILE"

echo "Backup of $SPACE written to $DEST"

Make it executable and add a cron entry. This one runs every night at 2am and appends output to a log file so you can confirm it ran:

# chmod +x backup-space.sh, then: crontab -e
0 2 * * * /home/you/backup-space.sh DOCS >> /home/you/conf-backup.log 2>&1

A few practical notes for scheduled runs:

• Use a dedicated profile. The script targets --profile prod. Configure it once with auth login so the cron job authenticates non-interactively with a stored API token.
• Timestamp the output. The $STAMP directory keeps each night's snapshot separate, so you build a history rather than overwriting yesterday's copy.
• Prune old snapshots. Pair the job with a retention step (for example, delete backup directories older than 30 days) so the archive does not grow without bound.
• The same script works in CI. If you prefer not to run cron on a box, drop the export into a scheduled pipeline. The Confluence automation guide covers running these commands from CI runners.

Verify and restore a backup

A backup you have never opened is a guess. After each export, do a cheap sanity check that the archive actually contains content. Because it is JSON, jq makes this a one-liner:

# How many items did we capture?
jq 'length' docs-backup.json

# List the titles so you can eyeball them
jq -r '.[].title' docs-backup.json | head -20

Compare that count against what the space actually holds. A quick space get and a search count confirm nothing was silently truncated:

# Count pages currently in the space
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format json --limit 500 | jq 'length'

Restoring is deliberate rather than a single import command, which is a feature: you decide exactly what comes back and where. The JSON archive is a faithful record of each page's title and body, so you rebuild pages from it with confluence page create, scripting the loop the same way the attachment backup loops over IDs:

# Recreate a page from a saved title and body
atlassian-cli confluence page create \
  --space DOCS \
  --title "Runbook: Incident Response" \
  --body "<p>Restored from backup</p>"

For selective restores, filter the JSON with jq to the pages you need and feed each into page create. For the full restore-and-retention strategy, including how often to run these exports and where to store them, follow the Confluence backup runbook.

FAQ

Related Resources