Skip to content

Litebackup on the command line

One binary and a systemd service back up your SQLite databases, keep replicas current, and fail over, without a line of your code changing.

Quick start

Run these on the machine where your app already runs. Steps 2 and 3 are for Linux with systemd; on macOS, see the last section.

1. Install the command

Linux, x86-64 (Intel or AMD)

sudo curl -fsSL -o /usr/local/bin/litebackup https://litebackup.com/pkg/cli/stable/litebackup-linux-amd64 && sudo chmod +x /usr/local/bin/litebackup

Linux, ARM (such as AWS Graviton or Ampere)

sudo curl -fsSL -o /usr/local/bin/litebackup https://litebackup.com/pkg/cli/stable/litebackup-linux-arm64 && sudo chmod +x /usr/local/bin/litebackup

macOS, Apple silicon

sudo mkdir -p /usr/local/bin && sudo curl -fsSL -o /usr/local/bin/litebackup https://litebackup.com/pkg/cli/stable/litebackup-darwin-arm64 && sudo chmod +x /usr/local/bin/litebackup

macOS, Intel

sudo mkdir -p /usr/local/bin && sudo curl -fsSL -o /usr/local/bin/litebackup https://litebackup.com/pkg/cli/stable/litebackup-darwin-amd64 && sudo chmod +x /usr/local/bin/litebackup

Not sure which? uname -m prints x86_64 for x86-64, and aarch64 or arm64 for ARM.

2. Join your server as a service

With the join token from Machines, Add machine in your console:

sudo litebackup install service --user app --join TOKEN@your-instance.litebackup.cloud

The service starts at boot, restarts if it stops, and runs as your app's user, so files keep their owner.

3. Back up your databases

sudo litebackup backup '/var/lib/app/*.sqlite' --prefix app/ --wait server

Every change to the matching files reaches your server within seconds. Your app does not change: it keeps opening the same files with the same driver.

Back up

Name your databases

A database's name is its file name in lowercase, with every other character turned into -, so My App.sqlite becomes my-app.sqlite. --prefix puts a prefix in front, and --name sets the whole name for one file. --wait server or --wait cloud returns once the latest change is on your server or in your bucket.

See and stop backups

sudo litebackup backup list                      # what this machine backs up
sudo litebackup backup stop app/main.sqlite      # stops backing up; the backups stay

If another machine already backs up a name, backup refuses and changes nothing. Pass --prefix or --name, or use failover.

Read on other machines

On each machine that reads, join with a readonly token and replicate one database, or every database under a prefix:

sudo litebackup install service --user app --join READ_ONLY_TOKEN@your-instance.litebackup.cloud
sudo litebackup replicate app/main.sqlite --to /var/lib/app/main.sqlite
sudo litebackup replicate --prefix app/ --to /var/lib/app/replicas

Replicas stay current within seconds. Your app reads them with any SQLite driver, and writes to them are refused. replicate list shows them, and replicate stop app/main.sqlite stops one.

Keep writing when a server goes down

Run the same app on several servers, and run this on each one:

sudo litebackup failover /var/lib/app/main.sqlite
sudo litebackup writer main.sqlite      # the machine that writes now

One server becomes the origin and takes writes; the others keep a live readonly copy at the same path. If the origin stops, a replica takes over in about 60 seconds. Your server's --session-lease sets that time, and --name sets the database's name.

The high availability guide shows how to send writes to the origin.

Share databases across a worker pool

When any worker may run any job, acquire the database where the job runs and release it when the job is done. Only one machine holds it at a time.

sudo litebackup acquire customers/42.sqlite --to /var/lib/app/customer-42.sqlite --timeout 30s
# Write with any SQLite driver, then close the database.
sudo litebackup release customers/42.sqlite --wait cloud --offload

--offload removes the local copy once your bucket holds it, and acquire brings it back next time. acquire --offload released does the same after every release.

Restore a version

sudo litebackup versions app/main.sqlite
sudo litebackup restore app/main.sqlite --to /tmp/main.sqlite --time 2026-11-15T09:30:00Z
sudo litebackup restore app/main.sqlite --to /tmp/main-v120.sqlite --version 120

A restore always writes a new file, never overwrites one, and checks it before it finishes. The directory must already exist.

Day to day

See what is happening

sudo litebackup status           # every database, with its role and state
sudo litebackup sync             # send pending changes now
sudo litebackup conflict list    # conflict copies for you to look at

A database's role is origin or replica. Its state is syncing, synced, waiting (another machine is the origin), offloaded, stopped, conflicted, or error.

Manage your instance

litebackup admin login                              # sign in to your instance from any machine
litebackup admin database versions app/main.sqlite  # the versions your server keeps

Commands are grouped by where they go. Top-level commands talk to Litebackup on this machine, litebackup server runs on your Litebackup server's own host, litebackup admin reaches your instance over HTTPS as you, and litebackup account manages your Litebackup account.

Update or remove

sudo litebackup install cli          # the version your server runs
sudo litebackup uninstall service    # keeps this machine's join; --purge removes it

install cli checks every download against Litebackup's signed release before it replaces the binary, then restarts the service onto it. Update your server first, then each machine.

On macOS

Install with the macOS command in step 1, then join with litebackup up TOKEN@HOST. The client starts on demand whenever a command or the SDK needs it.

To back up from your app's code instead, use the SDK.