Back up and restore Athenode

A backup archive is a copy of the athenode daemon's whole data folder, made with athenode backup and put back with athenode restore. The athenode daemon is the local Athenode server that the athenode package installs: it keeps your projects on your machine and serves the web UI and the Athenode MCP server at http://127.0.0.1:3717. Its data folder is ~/.athenode by default (C:\Users\<you>\.athenode on Windows), or the folder that --data-dir or ATHENODE_DATA_DIR names, as Configuration describes.

The copies Athenode makes differ in what they hold and in how you put them back.

Copy	What it holds	Made by	Put back with
Backup archive, `athenode-backup-<version>-<time>.tar.gz`	The daemon's database with every project, the master key and the data folder's `config.json`	`athenode backup`, when you run it	`athenode restore`, into a whole data folder
Automatic backup, `backups/athenode-<version>-<time>.tar.gz`	The daemon's database	The daemon, before it upgrades the database to a new version	By hand, with `tar`
Project archive, `<name>.athenode-project.tgz`	One project's specifications, ToDo cards and plugins	Export project in the web UI, or `athenode project export`	Import archive, or `athenode project import`, as a new project on any daemon or Athenode Pro server

In every file name, <time> is the date and time in UTC, written as yyyyMMddHHmmss.

athenode backup and athenode restore work on the daemon's data folder only. Athenode Pro is the Athenode server a team runs itself, with accounts, project roles and a licence. Its data is in PostgreSQL, and you back up the database and the server's master key separately, as Install Athenode Pro describes.

Back up the data folder with athenode backup

Back up before you change machines, before you delete the data folder and at regular times. You need the athenode package installed, as Install Athenode describes. The daemon may be running or stopped.

Open a terminal.
Run backup:
```
athenode backup
```
Optional: write the archive somewhere other than the current directory with --output, which takes a file name or a folder:
```
athenode backup --output ~/backups
```
Copy the archive to a place outside the machine, such as an external drive.

The CLI prints "Backed up the data folder to", then the archive's path and "(readable only by you; it holds the master key: keep it safe).". The archive is named athenode-backup-<version>-<time>.tar.gz, for example athenode-backup-0.12.1-20261029080000.tar.gz, after the version of Athenode that wrote it.

The archive holds three things:

the database, with every project of the daemon and its specifications, ToDo cards, plugins and SSH connections;
the master key, which encrypts the secrets the daemon stores. The archive holds the key in effect, also when it comes from ATHENODE_MASTER_KEY or ATHENODE_MASTER_KEY_FILE;
the data folder's config.json.

The logs, the automatic backups in backups/ and the CLI's sign-ins to Athenode Pro servers are not in the archive.

With the daemon running, backup asks the daemon for the copy, and the daemon pauses writes while it copies the database. With the daemon stopped, backup reads the data folder itself. Because it works in both states, you can run athenode backup from a scheduled task.

When the data folder holds no database, because the daemon has never started there, backup stops with "nothing to back up" and writes no file.

Warning

Anyone who has the backup archive can read every secret stored in it, because the archive holds the master key. Keep it where only you can reach it.

Restore a backup with athenode restore

Restore a backup to undo changes since the backup, to recover a data folder that was lost or to set up the same daemon on another machine. restore replaces the database, the master key and config.json of the data folder with the ones in the archive.

Stop the daemon:
```
athenode stop
```

Restore the archive:

athenode restore athenode-backup-0.12.1-20261029080000.tar.gz

If the data folder already holds a database or a master key, restore stops and names --force. Run it again with --force to move them aside first:
```
athenode restore athenode-backup-0.12.1-20261029080000.tar.gz --force
```
Start the daemon again:
```
athenode service restart
```
If you run the daemon in a terminal, run athenode start instead.

The CLI prints "Restored the backup of", then the product, the version and the data folder, and the command that starts the daemon. With --force it first prints where it moved the previous database, master key and config.json: a folder backups/pre-restore-<time>/ in the data folder. To go back to the state before the restore, stop the daemon and move those three back.

restore refuses in these cases and changes nothing:

Case	What to do
A daemon runs on the data folder	Stop it with `athenode stop` and run `restore` again.
The backup was written by a newer version of Athenode	Install that version or a newer one with `npm i -g athenode`, then restore.
The backup holds data that the installed version does not know	Install the version the message names, or a newer one, then restore.
The data folder holds a database or a master key	Add `--force`, which moves them into `backups/pre-restore-<time>/` first.

A backup of an older version restores without a step of yours. At its next start, the daemon upgrades the database to the installed version and saves an automatic backup first, as the next section describes.

When ATHENODE_MASTER_KEY or ATHENODE_MASTER_KEY_FILE is set in your environment, that key replaces the restored one at the next start, and restore prints a note that says so. Unset the variable to use the key from the backup, because the restored database needs the key it was backed up with.

To restore onto another machine, install the athenode package there, run athenode restore before the daemon starts for the first time, then run athenode service install. If the daemon has already started on the new machine, it has created a database and a master key of its own: stop it and restore with --force. The CLI signs in to each Athenode Pro server again the first time you use it on the new machine.

Restore the automatic backup taken before an upgrade

When you update the athenode package to a version that changes the database, the daemon saves the database to backups/athenode-<version>-<time>.tar.gz in the data folder at its first start, before it changes anything. <version> is the version you updated from. The daemon writes the path of the backup to its log, and athenode doctor shows a pending change of the database as "pending (applied with a backup at the next start)".

Restore this backup to go back to the version you updated from. An older version cannot open a database that a newer one has changed: it refuses to start and names the backups folder. The automatic backup holds the database only. The master key and config.json stay in the data folder as they are.

Stop the daemon:
```
athenode stop
```
Install the version in the backup's file name, for example 0.11.2:
```
npm i -g athenode@0.11.2
```
Move the current database aside:
```
mv ~/.athenode/db ~/.athenode/db-0.12.1
```
Create an empty db folder:
```
mkdir ~/.athenode/db
```

Unpack the backup into it:

tar -xzf ~/.athenode/backups/athenode-0.11.2-20261029080000.tar.gz -C ~/.athenode/db

Start the daemon:
```
athenode service restart
```

On Windows, run the same steps in PowerShell, with the data folder at C:\Users\<you>\.athenode.

The daemon starts with the database as it was before the upgrade. Changes made after the upgrade are in the folder you moved aside, not in the restored database.

The daemon keeps every automatic backup it saves. Delete old ones from backups/ yourself when you no longer need them.

Move a project to another server with a project archive

A project archive carries one project from one server to another: from your daemon to an Athenode Pro server, from Pro to a daemon, or between two daemons. The project arrives as a new project with new ids, and the project on the first server stays as it is. Projects describes what an archive holds, how the web UI exports and imports it, and the messages of an import.

In a repository bound to the project, export it:
```
athenode project export
```
Outside a bound repository, name the project with --project <id>. The project id is in the project's settings in the web UI.
Import the archive on the other server. In a repository bound to that server, import uses it; elsewhere it uses the local daemon:
```
athenode project import web-shop.athenode-project.tgz
```
Add --name <name> to give the new project another name.
In each repository that should use the new project, bind it with the id that import printed:
```
athenode init --project <id>
```
For a project on Athenode Pro, add --server with the server's address, as Connect to Athenode Pro describes.
Recreate the project's SSH connections on the new server, because an archive does not carry them. On the same server, Copy to project copies a connection to another project, as the SSH gateway describes.

export prints "Exported the project", its name and id and the path of the archive, which is readable only by you. import prints the new project's name and id, the warnings of the import, if there are any, and the init command for step 3. Against an Athenode Pro server, both commands use the CLI's sign-in, and sign you in through the browser when there is none. The Athenode CLI reference lists the options of backup, restore and project.

Last updated: 2026-10-29