Using the command line¶

Everything the app does can also be done by typing commands in a terminal. Commands start with deucalion, followed by what you want to do:

deucalion backup
deucalion restore ~/Documents/report.pdf

New to the terminal? See Opening a terminal.

All commands¶

$ deucalion --help
usage: deucalion [-h] [--version] COMMAND ...

Back up your Ubuntu machine to an external drive, and restore or rebuild from it.

positional arguments:
  COMMAND
    gui        open the app (also what plain 'deucalion' does)
    deps       check (and install) what Deucalion needs, including VeraCrypt
    drives     list connected drives
    register   use a drive (or a folder on it) for backups
    targets    list registered backup drives
    setup-drive
               prepare a drive for backups (format, encrypt)
    open       unlock an encrypted backup drive
    close      lock/unmount the backup drive so it can be unplugged
    backup     back up everything, or only some folders
    status     show the state of the backup
    ls         list what is in the backup (with original names)
    restore    restore files or folders from the backup
    rebuild    rebuild this machine from a backup (new machine or new Ubuntu)
    verify     check the backup on the drive is complete and undamaged
    removed    list or empty _removed/ (old versions and deleted files)
    exclude    manage what is left out of your home backup
    folder     manage extra folders outside your home (e.g. /srv)
    profile    manage saved selections for partial backups
    config     show or edit the configuration

options:
  -h, --help   show this help message and exit
  --version    show program's version number and exit

Command	What it does	Page
`deucalion`	Opens the app (on a desktop); prints the list of commands otherwise.	gui
`gui`	Opens the app.	gui
`deps`	Checks (and installs) what Deucalion needs, including VeraCrypt.	deps
`drives`	Lists the drives plugged into this computer.	drives and targets
`targets`	Lists your registered backup drives.	drives and targets
`setup-drive`	Prepares a drive for backups: format and/or encrypt it.	setup-drive
`register`	Uses a drive (or a folder on it) as it is, for backups.	register
`open`, `close`	Unlock or lock an encrypted backup drive; close any backup drive before unplugging it.	open and close
`backup`	Backs up everything, or only some folders.	backup
`status`	Shows the state of the backup.	status
`ls`	Lists what is in the backup, with the original names.	ls
`restore`	Restores files or folders.	restore
`rebuild`	Rebuilds this computer from a backup, step by step.	rebuild
`verify`	Checks that the backup on the drive is complete and undamaged.	verify
`removed`	Lists or empties Removed Files (`_removed/`).	removed
`exclude`	Manages what is left out of your home folder's backup.	exclude
`folder`	Manages extra folders outside your home folder.	folder
`profile`	Manages saved selections for partial backups.	profile
`config`	Shows or edits the configuration file.	config

Things that work the same everywhere¶

Help. Add --help (or -h) to any command to see its options: deucalion backup --help. deucalion --version prints the version.

Which drive. Commands that use a backup drive take --target NAME, where NAME is the drive's name (as deucalion targets shows it) or its id. Without it, Deucalion uses your default drive; if you have several drives and no default, it asks you to choose one with --target.

Locked drives. If the backup drive is encrypted and locked, commands that need it ask for its password and unlock it first:

$ deucalion status
The backup drive 'Alex Backup' is locked.
  Backup password:
  Unlocking (you will be asked for your administrator password)…
  Unlocking (VeraCrypt volumes can take up to a minute)…
Backup drive 'Alex Backup'
  Folder:        /media/alex/Alex Backup/Deucalion-Backup
  Filesystem:    exfat   Encrypted: yes
  Backed up:     659 files, 178.4 MB
  Free space:    5.5 GB
  _removed/:     334.0 MB in 3 batch(es)
  From machine:  alex-laptop (Ubuntu 24.04.5 LTS), user alex
  Last full:     2026-10-12T09:11:57+01:00
  Recent runs:
    2026-10-12T09:11:56+01:00  full     completed                12 copied, 21.6 MB
    2026-10-12T09:10:41+01:00  full     completed_with_warnings  3 copied, 294.4 KB
    2026-10-12T09:10:22+01:00  partial  completed                0 copied, 0 B  [/home/alex/Projects, /home/alex/Documents/Work]
    2026-10-12T09:10:20+01:00  partial  completed                1 copied, 72 B  [/home/alex/Documents, /home/alex/Pictures]
    2026-10-12T09:10:17+01:00  full     completed                5 copied, 2.4 MB

Paths. Files and folders can be given as you see them on your computer (~/Documents/report.pdf, /home/alex/Documents) or as they are named in the backup (home/Documents). Put names with spaces or special characters in quotes: "~/Documents/Budget 2026.ods".

Questions. When a command needs a yes or no, it asks: Restore now? [y/N]. Type y and press Enter for yes; anything else (or just Enter) means no. -y or --yes answers yes in advance. Without a terminal to ask in (for example in a script), a question counts as no unless you give --yes.

Stopping. Press Ctrl+C once to stop a backup, restore, rebuild or verify safely: Deucalion prints Stopping safely… (press Ctrl+C again to abort immediately) and stops at the next safe point. A half-copied file is thrown away, never left behind; a file a restore was replacing is put back. Press it a second time to stop immediately. Either way, the next run continues where it stopped. Package installations and /etc changes during a rebuild are never cut off half way.

Colours. Deucalion colours its output in a terminal (green for success, yellow for warnings, red for errors). Set NO_COLOR=1 to turn colours off.

Administrator password. Deucalion never needs sudo in front of it, and refuses to run as root. When a step needs administrator rights, it asks: [Deucalion] administrator password for alex:. See Administrator access.

Exit codes¶

Every command ends with a number that scripts can check (echo $? shows it):

Code	Meaning
`0`	Done. (For `verify`: the backup is intact.)
`1`	Something went wrong, or you answered no to a question. The message says what. (For `verify`: problems were found.)
`2`	The command was typed wrong (unknown command or option); the usage is printed.
`130`	Stopped with `Ctrl`+`C` (or stopped safely).

Unexpected errors¶

If something unexpected happens, Deucalion prints:

Unexpected error: <the error>
Nothing on your machine was changed by a backup. Run again with DEUCALION_DEBUG=1 for details, and please report it.

Run the command again as DEUCALION_DEBUG=1 deucalion … to see the full details, and report it.