Home Assistant: How to Restore a Backup via the CLI

When the Home Assistant web interface becomes unreachable after an update, direct access via monitor and keyboard or a VM console is often the only option left. The problem in the terminal (CLI): The list of all backups scrolls past illegibly fast and is not sorted chronologically. With just a few commands, you can filter out the required backup point and trigger the restoration.

What You Need

• Direct access to the Home Assistant CLI (via monitor/keyboard on a Raspberry Pi or through a VM console)
• A previously created full backup

1. Log In

Right after booting, you will find yourself in the standard Home Assistant CLI. First, enter the following command:

login

login

2. List Backups with Pagination

After logging in, use the paging command more to browse through the list of backups step by step:

ha backups | more

ha backups | more

Alternatively, you can switch to the backup directory and display the files sorted by creation date:

cd /mnt/data/supervisor/backup
ls -lath | more

cd /mnt/data/supervisor/backup
ls -lath | more

3. Note the Backup Slug

Locate the desired snapshot in the list and take note of its slug (the unique backup identifier).

4. Start the Restore via CLI

Return to the main CLI with exit:

exit

exit

Then, run the restore command using the slug you noted down earlier (used here as placeholder 1234abcd):

backup restore 1234abcd

backup restore 1234abcd

Did It Work?

The restoration process will now run. Once it completes successfully, the web interface should be accessible in your browser again as usual.

Troubleshooting

• “is only a partial backup” error: The default backup restore command expects a full backup. Make sure you do not select a partial backup snapshot.
• Check your input: Do not include the .tar extension when running the restore command.
• The “more” command does not work: The standard Home Assistant CLI shell does not directly support piping to more. Make sure you only run this command after entering login.
• Web interface remains blocked: Check whether you still have access to the backup section via the official Home Assistant Companion app on your smartphone to initiate the restore from there instead.

Sources: Forum: Home Assistant Community, community.home-assistant.io