CLI reference
Every backdown command and option, generated from the program's own help.
Everything below comes from the backdown program itself (backdown --help), so it matches what it accepts: version 1.0.0-beta.5.
Run backdown help <command> for the same text in a terminal.
backdown [OPTIONS] <COMMAND>Commands
| Command | What it does |
|---|---|
index | Index every file under each PATH as a new scan (read-only; re-run to update). |
forget | Remove an indexed drive or folder from the index: its files, folders, scans and what was recognised on it (signed manifests and the chain of custody stay). Nothing on it is touched. |
hash | Hash only what could be a duplicate: size, then a sample, then full SHA-256. |
dupes | List duplicated content, largest reclaimable space first (runs hash first). |
check | Is PATH safe to wipe? Every file needs a SHA-256-identical copy outside PATH (runs hash first). Exits 0 when safe, 2 when files must be copied first. |
import-legacy | Import the index the pre-Rust scripts wrote (bd-index.sh, bd-hash.py), so their crawling and hashing aren't repeated. |
volumes | Every disk and partition on this machine: what's on it, and what BackDown can do with it (read-only; needs no root). |
health | How each drive is doing: SMART verdict, temperature, bad sectors, wear, and what changed since its first reading (read now, without root; kept in the index). Exits 2 when a connected drive is failing. |
mount | Mount a partition read-only (one backdown volumes calls mountable), or attach a disk image read-only and mount what's on it; never read-write, and as you: udisks on Linux, diskutil and hdiutil on macOS (Windows attaches ISO, VHD and VHDX images). Without a target, lists what BackDown has mounted. |
unmount | Unmount a partition, or detach a disk image, that BackDown mounted (nothing else). |
scans | Finished scans, oldest first. |
serve | Browse the index in your web browser: folders at any scan, versions, copies, file viewers. |
status | What's in the index (and what the daemon is doing). |
daemon | Run in the background: rescan drives, hash, serve the web UI. Usually started by backdown service install rather than by hand. |
open | Open the running daemon's web UI in your browser. |
token | The background service's browser token, for opening BackDown from a browser yourself (in a terminal, also the links with it in, including the one for other devices with --host). |
completions | Tab completion for backdown's commands and options: print the script for a shell, or --install it for yours. |
app | Open BackDown in a window of its own, starting its background service first if need be (what the applications menu, Start menu and BackDown.app run). |
desktop | Add BackDown to your applications menu, ~/Applications or the Start menu (or remove it). |
update | Is there a newer BackDown? Install it (verified against the release's signature and SHA-256 sums), from the network or from a folder carried over. |
service | Run the daemon as a service (systemd on Linux, a login item on macOS, a task at logon on Windows): install, uninstall or check it. |
entities | What things are: mail stores, backups, phones, systems, repositories, libraries… with where they came from (reads small files like backup scripts on connected drives). |
people | Who the things are about: everyone with a mailbox, a Nextcloud account, a home folder or a mail identity on any drive, with everything found of them. |
databases | The databases behind the dumps, data directories and sites on every drive: each one with every dump and live copy of it, and what used it. |
search | Search inside things: mail by subject, sender and recipient; database dumps and SQLite files by table, column and, at full depth, the text in their rows. Reuses Dovecot's own index for mail headers and SQLite's full-text tables in place. |
overlaps | How much of each drive, folder and recognised thing already exists elsewhere, and where. |
report | The whole picture as a document: drives, what's on them, overlaps, duplicates, and which drives are safe to wipe. |
plan | Propose where everything on the old drives goes in one archive, and why (saved, so it can be applied). |
plans | Plans made so far. |
apply | Apply a plan: show what it would do, or with --go copy, verify and journal every file (never deletes anything). |
rescue | Get files back from a failing, formatted or emptied drive or card (only reads it). |
mirror | Keep a folder (usually part of the archive) copied on another drive, and check the copy now and then. |
wipe | Free drives (or folders on them): delete only what has a verified copy elsewhere, moving what exists only here to --move-to first. Without --go, only shows what would happen. |
license | Your BackDown Pro licence: add a key, or show the one you have. |
remote | Other machines (a NAS, another computer) whose BackDown index is read over ssh, so copies there count for duplicates and wiping. |
pool | The pool: folders on the swarm's drives that drives are filed into, each file once. On the machine whose drive it's on: pool add FOLDER; pool list shows every machine's. |
swarm | Every machine as one: each machine's drives, how full they are and what's indexed on them (this machine and the ones backdown remote reaches); swarm where NAME finds files on all. |
dedup | Tidy an archive: identical files in FOLDER share their storage, as hardlinks or clones. Both files are re-read first; every link is journaled. Without --go, only shows what would happen. |
mail | Mailboxes: merge copies of one into a single Maildir, or export a Maildir folder as mbox. |
custody | The chain of custody: every copy, move, deletion, link and merge BackDown made, in a hash-chained log sealed with this installation's key. Export it as a signed bundle, verify one, or check the log in the index. |
manifest | Signed, tamper-evident manifests of what a drive held at a scan: sign one, check one (anyone can, here or on another computer), list the ones kept, show your signing key. |
Global options
Every command takes these.
--db <DB>- Index database (default: your BackDown data folder; see
backdown status). Also read from$BACKDOWN_DB. --local- Work on the index directly even if a BackDown daemon is running.
-h,--help- Print help (
--helpshows more than-h). -V,--version- Print the version.
When the daemon is running
When the daemon is running, it owns the index: index, hash, dupes, check, scans, status, health, remote sync and apply --go are handed to it and you follow its progress in the terminal; wipe, dedup --go and mail merge check first, then hand the work to it. Everything else reads the index directly. --local makes any command work on the index itself instead. import-legacy refuses to write while a daemon is running: stop it first. On Windows, commands always use the index directly.
Exit codes
| Code | Meaning |
|---|---|
0 | Done. For check: safe to wipe. |
1 | Something went wrong; the message says what. license show: no licence. In a release version, a Pro command without a licence. |
2 | Finished, with a result to act on: check found files that exist nowhere else (or couldn't be read); apply, wipe, mirror sync, mirror verify, dedup or mail merge had conflicts, failures or mismatches; health found a connected drive failing; rescue image couldn't read everything; rescue find or rescue partitions found nothing. |
3 | service status: the service isn't running. |
10 | update --check: there's a newer version. |
Environment
BACKDOWN_DB- The index database, like
--db. BACKDOWN_PORT- The daemon's port for the browser, like
backdown daemon --port. BACKDOWN_BROWSER- The Chromium-family browser
backdown appuses, like--browser. BACKDOWN_NO_UPDATE_CHECK- When set, the daemon never looks for updates, whatever Settings says.
XDG_DATA_HOME,XDG_RUNTIME_DIR(Linux)- Where the data folder and the daemon's socket go:
$XDG_DATA_HOME/backdown(default~/.local/share/backdown) and$XDG_RUNTIME_DIR/backdown. LOCALAPPDATA(Windows)- The data folder is
%LOCALAPPDATA%\BackDown.
Last updated · What's released, and what's next