Command Line Interface

Relica is easy to use on the command line with its command line interface (CLI). All the things you can do with the web UI can also be done in the terminal. For an introduction on how to get started with Relica using its CLI, see the headless mode tutorial.

PATH

Relica might not be in your $PATH or %PATH% by default, meaning you'll have to type the path to the relica binary to run it. For example, on Linux: /opt/relica/bin/relica. But you can add Relica to your PATH easily enough so that you can just type relica:

Linux: Run export PATH=$PATH:/opt/relica/bin for a temporary fix, or add that command to your ~/.bashrc, ~/.bash_profile, or /etc/profile to make it permanent.

macOS: Run export PATH=$PATH:/Applications/Relica.app/Contents/MacOS for a temporary fix, or add that command to your ~/.bashrc or ~/.bash_profile to make it permanent.

Windows: In the Search bar next to your Start/Windows button, type "environment variables" (no quotes). Click either option that appears, to edit the system environment variables or just for your account. Click the "Environment Variables" button. Find the PATH or Path environment variable (in whichever list you prefer to modify) and select it. Click Edit. Click New. Add this path: C:\Program Files\Relica. Click OK. Close all remaining windows by clicking OK. You may need to log out and log back in for changes to take effect.

Syntax

Global flags come first, followed by the command as the first positional argument to the relica command. Parameters are given either as subsequent flags or positional arguments. Some examples of valid syntax:

$ relica --global-flag global-val command --flag val $ relica command --flag val $ relica command val $ relica command

Remember that your shell will parse values with whitespace, punctuation, or special characters. Be mindful to enclose values in quotes or to escape characters as necessary, and according to the specifics of your shell.

Flags start with two dashes (--). Values have an expected data type:

Type Description Examples
string A string of text. Quotes are only required if the shell needs them to parse correctly. foo
"foo bar"
"This is a string."
int A whole number. 42
0
-7
float A decimal number. 3.14159
-6.3
bool True or false. For true values, the value can be omitted; merely the presence of the flag is enough to give a value of true. true
false
list[type] A list contains one or more values of the same type. Lists comprise one or more arguments as parsed by the shell, where the first argument starts with open square bracket [ and the last argument ends with close square bracket ]. The open and close brackets must be part of the first and last arguments, respectively, not arguments by themselves. If the values have spaces, be sure to put them (but not the brackets) in quotes so that the shell won't split the string. [Item1 Item2]
["First item" "Second item"]

Lists can also contain complex types such as structures. To create a complex list, each list element should be individually described using array notation. For example, the flag notation of --arr[n].field creates an n-th index item and sets the value of a field called field to the value of the flag. In practice you would replace n with an actual index, starting from 0: --arr[0].field val.

Global Flags

Global flags may apply to any/every command, and must appear before the command (but after the relica command, of course).

Flag Description
--configstring optional The path to the config file.
--logstring optional The path to the log file. Can also be stdout or stderr.

All Commands

account-info

Lists all the information about your account that is cached locally by Relica so that it can continue to work offline.

This command has no parameters.

Example

relica account-info

backup

Runs a backup. The backup will be run immediately even if it is scheduled for another time.

Flag Description
string required The backup ID.

Example

relica backup 3784c07a-fee2-4a0b-a397-3998fa085558

cancel-task

Cancels a running task. Note that cancelling a backup which is configured with multiple destinations cancels the backup to the current destination only; it will proceed to back up to the other destinations. To cancel the backup operation entirely, you will need to cancel all the remaining tasks.

Flag Description
string required The task ID.

Example

relica cancel-task c1e2624b-eb78-438e-b0ef-5fbb26c4c95c

check-destination

Runs an integrity check on the specified destination. The check happens in the background. Normally these checks are automated, but you may manually invoke a check whenever the destination is not in use (since the operation requires an exclusive lock).

Flag Description
string required The destination ID.

Example

relica check-destination 51419f20-0e3c-4b3d-8fbf-322c97903eec

create-account

Creates a new Relica account and begins the trial period.

Flag Description
--emailstring required The email address for the account.
--passwordstring required The account password. Must be at least 12 characters and totally unique.
--referred-bystring optional The account ID of another customer that referred this new account.

Example

relica create-account --email "me@mine.com" --password "supersecure1234"

create-backup

Creates a backup.

If a schedule is configured and enabled, all configured fields of the schedule must align in order for the backup to be performed. In other words, if times of day and days of month are both set, then the backup will only run automatically if both the time of day and the day of month match the current timestamp.

Flag Description
--namestring optional A name for the backup configuration.
--includelist[string] required A list of files and folders to back up.
--excludelist[string] optional A list of files and folders or patterns to NOT back up.
--destinationslist[string] required A list of destination IDs to which to back up.
--schedule.scheduledbool optional Whether to run the backup on a schedule automatically.
--schedule.flexiblebool optional If true and a scheduled time was missed, the backup may run at the next opportunity.
--schedule.times-of-daylist[string] optional A list of times of day at which to start the backup. Must be in 4-digit, 24-hour format (e.g. 14:30). To run every hour at a certain minute, specify only the minute: :35.
--schedule.days-of-weeklist[int] optional A list of days of the week on which to run the backup. 0 = Sunday, ... 6 = Saturday.
--schedule.days-of-monthlist[int] optional A list of days of the month on which to run the backup. If the month does not have a given day, the last day of the month will still count.
--schedule.months-of-yearlist[int] optional A list of the months of the year in which to perform the backup.
--hooks[n].descriptionstring optional The description of the backup hook.
--hooks[n].commandstring optional The backup hook's command. See backup hooks.
--hooks[n].timingstring optional The timing of the backup hook. Can be one of beginning, before, after, or end.
--hooks[n].on-errorstring optional What to do in case the backup hook errors. Either continue or stop.
If creating any backup hooks, command, timing, and on-error are required for each one.

Example

relica create-backup \ --name "Important files" \ --include [/home/me /mnt/harddrive/important] \ --destinations [c9f83ae9-aafb-4c07-ad97-800b3ea39dbb]

create-destination

Creates a destination. Destinations are places where backups can be stored.

Flag Description
--namestring optional A name for the destination.
--typestring required The type of destination. Allowed values: local, peer, cloud. (Use set-cloud-escrow to create a Relica Cloud destination.) Depending on this value, other parameters are required.
--retention-daysint optional The number of days to retain old backup snapshots. Default: 0 (unlimited)
--local-dirstring required
if --type=local
 The absolute path to the directory where the destination will be created.
Required if --type is local.
--peer-idstring required
if --type=peer
 The ID of the peer to use as the destination.
--peer-manual-hoststring optional The hostname or IP address to use to connect to the peer, if not using the public/default IP that is recorded automatically for you. Useful if connecting to a peer directly on an internal network.
--peer-size-limitint optional Maximum size in bytes that this destination can store. Can be set only by the owner of the peer.
--peer-share-keystring optional The peer's share key, which can be obtained from the peer owner. Required if the peer is owned by a different account.
--peer-invited-emailstring optional The email address of the account to which this destination will belong. If it is not currently associated with a Relica account, it will be invited, and may immediately back up to this destination upon signing up. Setting this parameter essentially creates a destination for a different account and can only be done by the peer owner.
--account-idstring optional This creates the destination for the account given by this ID; can only be used when the current account owns the peer specified by --peer-id.
Only if --type is peer.
--cloud-account.provider-namestring required
if --type=cloud
 The user-friendly name of the cloud provider.
--cloud-account.remote-typestring required
if --type=cloud
 The type of protocol the cloud provider implements. Allowed values: b2, google cloud storage, azureblob, s3, sftp, webdav, jottacloud, swift
--cloud-account.remote-base-pathstring required
if --type=cloud
 The container or bucket name, along with any path, prefix, or subdirectory within the cloud account, in which the destination should be stored.
--cloud-account.enabledbool required
if --type=cloud
 Whether the cloud account is enabled. Access to the cloud account through Relica is not allowed while the cloud account is disabled.
--cloud-account.credentials[n].keystring required
if --type=cloud
 The key or identifier for the associated value of the credential or configuration parameter for accessing the cloud account. See docs for available fields.
--cloud-account.credentials[n].valuestring required
if --type=cloud
 The actual value of the credential or configuration parameter for accessing the cloud account as defined by the associated key.
--cloud-account.credentials[n].notestring optional An optional note or description of the credential.
Only if --type is cloud.

Example

relica create-destination \ --name "External Hard Drive" \ --type "local" \ --local-dir "/Volumes/backups"

create-peer

Creates a peer. A peer is a place on your computer where other people (or other computers on your own account) can back up to.

Flag Description
--namestring optional A name for the peer.
--pathstring required The absolute path to the folder where the peer will be created. This path must not yet exist, and the path must not be prefixed by another peer folder.
--enabledbool optional Whether to allow connections to this peer.

Example

relica create-peer \ --name "Matt's Computer" \ --path "/media/backups/others"

daemon

Run Relica in daemon mode. The process will block indefinitely. This command will not typically be run manually, but rather by a system's service/process manager.

This command has no parameters.

Example

relica --config ../myconfig.toml --log stdout daemon

delete-destination

Deletes a destination. This endpoint cannot be used to delete a cloud_escrow destination type (the "Relica Cloud"); use set-cloud-escrow to set the provider count to 0 instead.

This endpoint can be invoked by the destination owner or the owner of the peer associated with the destination, if it is a "peer" destination type.

Flag Description
--destination-idstring required The ID of the destination to delete.
--delete-filesbool optional If true, the actual files contained in the destination's folder will be deleted. This is not allowed for local destinations that are on another origin or peer destinations that are hosted on another computer. In all cases, we generally recommend leaving this as false and deleting the files manually, in case other files that you'd still want got put into the destination folder inadvertently. Default: false.

Example

relica delete-destination \ --destination-id 6946530a-6297-478c-802e-40b42dbb92f9

delete-origin

Deletes an origin (an "origin" is a computer on your account). It deletes all backups and destinations associated with, or relying on, the origin. An origin cannot delete itself; you can only delete other computers on your account, not the current one.

Flag Description
--origin-idstring required The ID of the origin to delete.

Example

relica delete-origin \ --origin-id b36274bb-ed31-47c4-b1b6-21dd7818e091

delete-peer

Deletes a peer (a "peer" is a shared folder to which you or others can back up to). This deletes all destinations associated with it.

Flag Description
--peer-idstring required The ID of the peer to delete.
--delete-filesbool optional If true, the actual files contained in the peer folder will be deleted. This is only allowed when being invoked on the computer/origin that hosts the peer. In all cases, we generally recommend leaving this as false and delete the files manually instead, to ensure nothing still wanted is inadvertently deleted. Default: false.

Example

relica delete-peer \ --peer-id 8f5926a5-937a-49e4-8a24-3c5debcca428

edit-backup

Modifies an existing backup.

Note that the parameters passed into this command completely replace the backup with the given ID. All parameters must be provided, even the ones that are not being changed. This ensures correctness, since there is no question as to what the values should be when performing the update.

See create-backup for more information about all the parameters.

Flag Description
--idstring required The ID of the backup to modify.
--interrupt-runningbool optional If true, and if the backup is currently running, it will be cancelled immediately and restarted with the new configuration.
See create-backup for additional parameters.

Example

relica edit-backup \ --id 3784c07a-fee2-4a0b-a397-3998fa085558 \ --name "Not-so-important files" \ --include [/home/me] \ --destinations [c9f83ae9-aafb-4c07-ad97-800b3ea39dbb] --interrupt-running

encryption-password

Sets or changes your account's encryption password. The password is only stored locally, so you will have to run this command on each computer immediately after logging in or creating an account.

The encryption password should be long and unique. Avoid changing it often; we recommend changing it only if it is lost or compromised. Do not lose it!

Flag Description
--setstring required
if setting
 The encryption password. If one already exists for your account, it must match exactly.
Only use immediately after creating an account or logging in.
--oldstring required
if changing
 The old/current encryption password.
--newstring required
if changing
 The new encryption password.
--destination-idstring optional The ID of the destination in which to update the repository's encryption password. If this is specified, the encryption password will only be updated at this destination; it must have already been set or changed on the account. Use only if changing the encryption password on this destination failed earlier, for example if it was offline, or was not accessible from the computer where the encryption password was initially changed.
Only use when changing the encryption password.

Example

relica encryption-password --set "choose a good, long password"

get-account-origins

Lists the origins on your account. Useful before logging in to get the ID of an origin you are replacing or logging in as.

Flag Description
--emailstring required Your email address.
--passwordstring required Your password.

Example

relica get-account-origins \ --email "foo@example.com" \ --password "correct horse battery staple"

install

Installs Relica as a system service. Linux and macOS only; not for use on Windows, which installs the system service with the installation wizard. This command is idempotent. This is invoked implicitly on the first run of Relica, so it is only useful if downloading and installing in headless environments or in advanced setup situations.

This command has no parameters.

Example

relica install

list-snapshot-files

Lists the files in a snapshot, optionally filtered by directory.

Flag Description
--destination-idstring required The ID of the destination containing the snapshot being accessed.
--snapshot-idstring required The ID of the snapshot.
--dirstring optional Only show files in this directory.

Example

relica list-snapshot-files \ --destination-id "c9f83ae9-aafb-4c07-ad97-800b3ea39dbb" \ --snapshot-id "c9816b9b" \ --dir "/Users/matt/Documents"

list-snapshots

Lists the snapshots in a destination.

Flag Description
--destination-idstring required The ID of the destination for which to list snapshots.
--origin-idstring optional Only list snapshots created by this origin.
--backup-idstring optional Only list snapshots created by this backup configuration.
--pathstring optional Only list snapshots containing this path.
--latestbool optional Only show the latest snapshot.

Example

relica list-snapshots --destination-id c9f83ae9-aafb-4c07-ad97-800b3ea39dbb

login

Logs you in.

Immediately after logging in, you should run encryption-password to set your encryption password so Relica can access your repositories from that computer.

Flag Description
--emailstring required Your email address.
--passwordstring required Your password.
--origin-namestring optional If logging in from a new computer, this sets the name of your computer so you can recognize it later.
--origin-idstring optional If logging on an existing computer, this is the ID of the computer (origin) for the current device to assume.
These flags are mutually exclusive.

Example

relica login \ --email "foo@example.com" \ --password "correct horse battery staple" \ --origin-name "Home server"

logout

Logs you out. Stops all running tasks (including scheduled backups) and stops serving any peers. Logging out is almost never necessary, unless you want to disconnect this computer from Relica.

This command has no parameters.

Example

relica logout

modify-destination

Modifies a destination. Of the optional fields, specify only those to be changed. The cloud-account values can be changed (see docs for create-destination), but to do so, all the fields for the entire cloud account need to be specified, since it is entirely replaced by what you specify here.

Flag Description
--idstring required The ID of the destination to modify.
--namestring optional The updated name for the destination. Note that the Relica Cloud destination cannot be renamed.
--retention-daysint optional The number of days to retain snapshots; snapshots older than this will be deleted. Default: 0 (unlimited).
--cloud-account.*(multiple) optional If this is a cloud destination and if the cloud account is being changed, specify the entire cloud account's new configuration. See docs for create-destination for possible fields.

Example

relica modify-destination \ --id 7ad40c4f-1304-4b93-9006-cad7b544ccdc \ --name "External hard drive"

modify-origin

Modifies an origin on your account. Of the optional fields, specify only those to be changed.

Flag Description
--idstring required The ID of the origin to modify.
--namestring optional The updated name for the origin.
--peer-portint optional The port on which to serve peer connections. Default: 4334
--auto-port-forwardbool optional If true, port forwarding for serving incoming connections will be automatic using UPnP. Set this to false if you do your own port forwarding.

Example

relica modify-origin \ --id c9f8dae9-aafb-4c07-ad9e-8f00ab3033cded \ --name "Lab Machine"

restore

Restores files from a snapshot. The restore operation happens in the background.

Flag Description
--destination-idstring required The ID of the destination from which to perform the restore.
--snapshot-idstring required The ID of the snapshot to restore. Can also be latest to restore the most recent snapshot.
--includelist[string] optional A list of specific files or folders to restore.
--excludelist[string] optional A list of specific files or folders or patterns to NOT restore.
--intostring required A directory into which to place the restored files. A subdirectory will be created.

Example

relica restore \ --destination-id "f0c299cd-493a-4432-a00f-5ecc6bb0fb74" \ --snapshot-id "latest" \ --into "/home/matt/restored_files"

set-cloud-escrow

Changes how many cloud providers your account backs up to. An increase of the current value will replicate your existing backups to other cloud providers. A decrease will delete your data from the excess cloud providers. The changes take effect immediately and will affect your monthly bill. WARNING: Setting to 0 deletes all of your cloud backups and cancels your cloud storage subscription.

To help keep your costs low, we do not allow reducing this count within 5 weeks of raising it. Frequently changing this value is discouraged, as it cannot be changed while previous replication or reduction operations are still working on our end. The command will fail if a previous operation is still in progress.

Flag Description
int required The number of providers, in the range [0,5].

Example

relica set-cloud-escrow 3

version

Prints the version.

This command has no parameters.

Example

relica version