Restore a Space

space restore puts a space back into Confluence from a backup taken with space get: the pages and folders it no longer has, the pages edited since, or the whole space under its own key or a new one.

It compares the backup with the space — the same comparison space check makes — shows the plan, asks for confirmation, and then restores page by page, parents first. Each page comes back with its body, attachments, labels and content properties.

Available from acs2md v1.0.12. space restore and page restore are the only acs2md commands that write to Confluence, and they never delete, trash, archive or move anything.

Restore by key


acs2md space restore by-key SPACE_KEY --backup-dir DIR [flags]

Aliases: key, k — the restore command itself also answers to recover.

--backup-dir is the backup’s space directory, for example ./backups/DEVOPS.

Examples


# See what would come back, change nothing
acs2md space restore by-key DEVOPS --backup-dir ./backups/DEVOPS --dry-run
 
# Bring back what was deleted since the backup
acs2md space restore by-key DEVOPS --backup-dir ./backups/DEVOPS
 
# Also roll back edits made since the backup, unattended
acs2md space restore by-key DEVOPS --backup-dir ./backups/DEVOPS --mode all --yes
 
# Rebuild a lost space, or copy it under a new key
acs2md space restore by-key DEVOPS2 --backup-dir ./backups/DEVOPS --create-space --mode all

Flags

Flag	Short	Default	Description
`--backup-dir`	—	—	Backup to restore from (its space directory)
`--mode`	—	`missing`	What to restore: `missing`, `changed`, `all`
`--create-space`	—	`false`	Create the space if it does not exist
`--prefer-version-restore`	—	`true`	Revert to the backed-up version when Confluence still has it
`--overwrite-properties`	—	`false`	Replace content properties whose value differs
`--reset-state`	—	`false`	Forget an unfinished earlier restore
`--concurrency`	—	`4`	Lookups run at once while comparing
`--dry-run`	—	`false`	Show the plan without writing anything
`--yes`	`-y`	`false`	Apply without asking for confirmation

The plan comes first


♻️  Restore from ./backups/DEVOPS (manifest, storage, last updated 2026-10-31 12:00)
   Into:  DevOps (DEVOPS)
   Mode:  missing
   Plan:  create 1 folder, create 3 pages

┌────────┬────────┬────────────┬───────────────┬─────────┐
│ DO     │ KIND   │ ID         │ TITLE         │ WHY     │
├────────┼────────┼────────────┼───────────────┼─────────┤
│ create │ page   │ 3134096561 │ Release Guide │ trashed │
│ create │ folder │ 5989695572 │ Operations    │ missing │
│ create │ page   │ 3134096562 │ Chapter 1     │ trashed │
│ create │ page   │ 3134096563 │ Runbook       │ missing │
└────────┴────────┴────────────┴───────────────┴─────────┘

Left alone (1):
  • page "Moved away" (3134096570): now lives in another space; restore it there with page restore if needed

Restore 4 item(s)? [y/N]

In a terminal, space restore asks before writing. In a script, pass --yes; without it, the command stops before writing anything. --dry-run shows the plan and writes nothing.

Restore by ID


acs2md space restore by-id SPACE_ID --backup-dir DIR [flags]

Aliases: id

The flags and behaviour mirror space restore by-key, except that a space that does not exist cannot be created by ID: use by-key with the key it should have.

Modes

`--mode`	Restores
`missing` (default)	Pages and folders Confluence no longer has — trashed, archived, purged — created anew under their backed-up parent
`changed`	Pages edited or renamed since the backup, brought back to the backed-up version (the version itself when Confluence still has it)
`all`	Both, and every other page gets the attachments, labels and properties it lacks

How a restore behaves

Parents first. A page goes under its backed-up parent: the parent as it is in the space, or the new page or folder this restore created for it. A page whose parent could not be restored waits for it and is retried with it on the next run. Folders come back too.

Links follow the restore. Once every page exists, links between restored pages are pointed at their new IDs. Links to Jira, to other sites and to pages that were not recreated stay as they are, and pages the restore did not write are never edited.

A page already there is adopted. Before creating a page, the restore looks for a current page with its title in the space. If one is there — put back by hand, or by an earlier run that was interrupted — it is taken as the restored page and only what it lacks is added.

Content properties are not overwritten. Apps keep state in properties — a document-control approval state, for example. Missing properties are created; a property with a different value is kept unless you pass --overwrite-properties.

Interrupted? Run it again. Progress is saved after every page in .restore-state.json in the backup directory. A second run of the same command skips what is done, retries what failed, and places children under the parents the first run created. The backup directory must be writable. --reset-state starts over; a restore into a different space requires it.

Left alone, and listed: pages that now live in another space, pages moved to another parent, and live pages the backup does not hold. Nothing is ever deleted, trashed, archived or moved.

A new space

--create-space creates the space when it does not exist, with the backup’s name, and puts the backed-up homepage onto the new space’s homepage. Restoring under another key makes a copy of the space: pages whose originals still exist in the source space are created in the copy too.

What cannot come back

IDs. Restored pages and folders are new: their IDs, authors, creation dates and version history are new. Links between restored pages are fixed; links from other spaces still point at the old IDs.
Moves. Pages moved to another parent since the backup are not moved back. Deleting a folder in Confluence moves its pages up rather than trashing them; restore brings the folder back but leaves those pages where they are.
Permissions. Page restrictions and space permissions are not part of the backup.

Permissions

Restoring needs the Confluence permissions to add and edit pages, folders, attachments and labels in the space, and to create spaces for --create-space.

Disaster recovery, end to end


# 1. Every night: a restorable backup (only changed pages are fetched again)
acs2md space get by-key DEVOPS --output-dir /backups
 
# 2. Any time: what has changed, been trashed or deleted since?
acs2md space check by-key DEVOPS --backup-dir /backups/DEVOPS
 
# 3. When something is lost: see the plan, then restore
acs2md space restore by-key DEVOPS --backup-dir /backups/DEVOPS --dry-run
acs2md space restore by-key DEVOPS --backup-dir /backups/DEVOPS
 
# 4. Confirm: restored pages now match their originals
acs2md space check by-key DEVOPS --backup-dir /backups/DEVOPS

To put back a single page instead, use page restore — see Restore Pages in the acp2md manual; acs2md ships the same command:


acs2md page restore --backup-dir ./backups/DEVOPS --page-id 3134096561