Headless Mode Tutorial

Relica's full functionality can be accessed headless via SSH or via the shell on machines without a desktop display. This tutorial shows you how to install Relica with the terminal and get it set up using its command line interface (CLI).

This tutorial assumes a Linux system with bash. But after installation, Relica's CLI works the same on pretty much every platform.

On this page:

Install with curl
Adding to PATH
Creating an account
Logging in
Finishing login
Getting account information
Creating a backup
Restoring files

Install with curl

This can be done with a single command (sudoer privileges may be required):

curl https://relica.run | bash

After that completes successfully, Relica will be running as a service. (Relica requires systemd for proper installation on Linux.)

Adding to PATH

You will want to add Relica to your PATH so you can use it without typing the full path to the binary each time. Depending on your distro and preferences, you can do it using one of these commands (only ONE is necessary):

$ echo "export PATH=\$PATH:/opt/relica/bin" >> ~/.bash_profile
$ echo "export PATH=\$PATH:/opt/relica/bin" >> ~/.bashrc
# echo "export PATH=\$PATH:/opt/relica/bin" >> /etc/profile

Then restart your shell or source the file you just modified.

Creating an account

If you already have a Relica account, skip this section and go to Logging In.

Creating an account takes just one command (give it several seconds to complete):

relica create-account \
	--email "YOUR_EMAIL" \
	--password "YOUR_PASSWORD" \
	--referred-by "REFERRAL_CODE"

The referred-by field is optional; use it if you have a referral code from an existing member.

This function partially logs you in, so you can skip the next section and go straight to Finishing Login.

Logging in

There are two ways to log in: (1) from a new computer on your account, or (2) from a computer that you had already logged in with Relica before.

If (1), meaning you HAVE NOT logged into Relica from this computer before, log in with your credentials and specify a name for this new computer, like "Home server":

relica login \
	--email "YOUR_EMAIL" \
	--password "YOUR_PASSWORD" \
	--origin-name "Home server"

If (2), meaning you HAVE used this computer with Relica before, then you will need to know which computer ("backup origin") is the one you are currently using before you log in. Get its ID from this command:

relica get-account-origins --email "YOUR_EMAIL" --password "YOUR_PASSWORD"
[
	{
		"account_id": "aa409f52-963e-4d8a-a16a-31e3420e7f87",
		"created": "2018-05-25T05:35:06.756098Z",
		"id": "436c5352-01a0-4c7f-90aa-334ce03a3604",
		"key": "JhDMfiNJXtudLVM3XvqK",
		"last_connected": "2018-06-01T02:47:13.354307Z",
		"last_ip": "12.34.123.234",
		"name": "Office desktop",
		"peer_port": 4334
	}
]

The id field is what you want. Use that value in your login command:

relica login \
	--email "YOUR_EMAIL" \
	--password "YOUR_PASSWORD" \
	--origin-id "YOUR_ORIGIN_ID"

After you create an account or log in, you MUST specify your encryption password. Relica will not function unless you provide your encryption password after you create an account or log in.

relica encryption-password --set "YOUR_ENCRYPTION_PASSWORD"

At this point, Relica will run your scheduled backups, and you can continue to use relica to perform other tasks. You won't need to log in on this machine again unless you explicitly log out, or, more specifically, delete the cache in $HOME/.relica. Merely stopping the Relica daemon (systemctl --user stop relica) does NOT log you out (but it does make Relica inaccessible until you start it again).

Getting account information

You can get a full dump of the information Relica is using to operate on your machine:

relica account-info

This is how you can get IDs and other information you will need to run other commands. It's a bit of a mouthful of JSON, so you may want to use jq to help parse it.

Creating a backup

You can create a simple backup like this:

relica create-backup \
	--name "Important files" \
	--include ["/home/me" "/mnt/harddrive/important"] \
	--destinations ["DESTINATION_ID"]

This will create a backup configuration which is not scheduled to run automatically. To schedule it automatically, use the flags related to scheduling.

Creating a backup does not perform one. To execute the backup, run:

relica backup "BACKUP_ID"

Restoring files

First, you need to choose a destination to restore from. Get its ID using account-info. Then you'll need to choose a snapshot on that destination to restore from. You can list snapshots in the destination like this:

relica list-snapshots --destination-id "DESTINATION_ID"

To list the files in a snapshot (optionally scoped to a certain directory):

relica list-snapshot-files \
	--destination-id "DESTINATION_ID" \
	--snapshot-id "SNAPSHOT_ID" \
	--dir "/"

Once you're ready to restore, use the restore command. For example, to restore all the files from a snapshot:

relica restore \
	--destination-id "DESTINATION_ID" \
	--snapshot-id "SNAPSHOT_ID" \
	--into "RESTORE_DIR"

See the documentation for restore for more options and details.

That should get you started with using Relica's CLI. See the full command line interface for more commands and a full description of each one.