Quickstart

One command takes you from a fresh Rivet install to a reviewable snapshot of your workstation. This page assumes you have already installed Rivet.

Use a separate repository

Personal snapshot data goes in its own private repository — never in the Rivet source tree, and never in a repository you would push publicly.

1. Run the setup wizard

rivet init

On an interactive terminal this walks you through the whole of steps 2 and 3 below: it shows what Rivet found on this machine, asks what to keep, and offers to take the first snapshot. If that is all you wanted, you are done — skip to step 4.

The repository is created at ~/rivet by default, and its location is recorded, so no later command needs --repo. To put it elsewhere, or to let Rivet create and attach a private GitHub repository via gh:

rivet init --repo ~/rivet-snapshots --github you/rivet-snapshots

Use --no-interactive to create the repository without the wizard. It is also skipped automatically when stdin is not a terminal, so scripts and packaging are unaffected.

By default snapshots go to Git only. To add a NAS, cloud remote, or restic repository as an additional destination, see Storage backends.

2. Choose what gets captured

The wizard already did this. To change your mind later:

rivet checklist --select

checklist shows only supported configuration groups that actually exist on this machine — there is no broad home-directory scan. --select walks you through those groups and then through package sources (Pacman repositories, AUR, AppImages, Snap, Flatpak). Answer y to include, n to exclude, or press Enter to keep the current state.

Your choices are saved to the snapshot repository’s rivet.toml, and later snapshots collect only what you approved.

To choose without being prompted — in a script, a CI job, or a packaging postinstall — name the categories instead:

rivet checklist --only shell-git,kde-plasma,packages

--only takes the group ids that rivet checklist --json reports, plus packages for package sources. Anything you do not name is deselected, so the same command always produces the same rivet.toml no matter what was selected before. An unrecognised name is rejected, listing the ones that would work.

Together with rivet init --no-interactive, this is the whole path from a fresh machine to a first snapshot without a terminal:

rivet init --no-interactive
rivet checklist --only shell-git,packages
rivet snapshot

--only packages is all-or-nothing

Naming packages enables Rivet’s default set of package sources; omitting it disables every one of them. There is no per-manager control from --only — for that, use --select, which toggles Pacman, AUR, AppImage, Snap, and Flatpak individually. APT, DNF, Zypper, XBPS, and Nix have no interactive toggle yet.

3. Snapshot

rivet snapshot --push

A commit is created only when content actually changed. Before pushing the first time, inspect what was captured:

cd ~/rivet
git show --stat

See Snapshot workflow for drift checking, deleting the latest snapshot, and pushing safely.

4. Restore, on this machine or the next one

rivet restore                    # plan only, writes nothing
rivet restore --apply --yes      # overwrites tracked files, after rollback copies

Without --apply you get a plan and nothing else. The plan also lists the categories in your snapshot, which you can restore a subset of:

rivet restore --only vim-neovim,packages   # just those categories
rivet restore --select                     # choose item by item

Anything not named in --only is excluded — including packages, unless you name packages. See Restore for diffs, earlier revisions, and cross-distro behaviour.

On a new machine, --repo is still needed the first time

The recorded default lives on the machine that ran rivet init, not inside the snapshot. After cloning your snapshot repository somewhere new, pass --repo once (or run rivet init --repo <path> against the clone) before the shorter commands work there.

Where to go next

• What Rivet excludes — the safety boundary, in full
• Secrets vault — carrying an SSH config or .netrc safely
• CLI reference — every command and flag