CLI reference

Every rivet command and flag.

Generated

The command reference below is generated from Rivet’s own clap command tree by cargo run --bin rivet -- __cli-reference --write, and a unit test fails the build if this page and the binary disagree. Each command’s description here is its --help text: if it reads badly on one, it reads badly on both, and both are fixed in crates/rivet-cli/src/main.rs.

Running rivet with no subcommand prints a welcome summary.

Global flags

Accepted by every subcommand, wherever they appear on the line.

Flag	Effect
--verbose	Show individual paths and actions in addition to the compact summary.
--log <FILE>	Write detailed commands and file operations to this text file.
--json	Print this command’s result as JSON instead of prose. The schemas are documented in docs/JSON.md and are a supported automation interface.

rivet scan

Inspect this workstation and report supported candidates.

Takes no flags.

rivet checklist

Show the curated, currently present configuration checklist.

Flag	Effect
--repo <PATH>	Snapshot repository containing the saved selections.
--select	Interactively select found groups and persist them to –repo.
--only <CATEGORIES>	Select exactly these comma-separated categories, without prompting: configuration group ids from rivet checklist, and/or packages. Anything not named is deselected. This is the non-interactive counterpart to –select, and the capture-side twin of restore --only.

rivet init

Initialize a separate local Git repository for personal snapshots.

Flag	Effect
--repo <PATH>	Where to create the snapshot repository. Defaults to $RIVET_REPO, or to ~/rivet. On success this location is recorded, so later commands no longer need –repo.
--github <OWNER/REPOSITORY>	Create or attach this private GitHub repository using gh.
--backend <ID>	Add a snapshot destination beyond the default Git repository (repeatable across separate init calls, for fan-out): one of git, fs, rclone, restic.
--path <DIRECTORY>	Local or already-mounted directory, for --backend fs.
--remote <REMOTE>	An rclone remote (e.g. “b2:my-bucket/rivet”), for --backend rclone.
--restic-repo <LOCATION>	A restic repository location, for --backend restic.
--password-env <VAR>	Environment variable holding the restic repository password, for --backend restic.
--password-file <FILE>	File whose contents are the restic repository password, for --backend restic.
--no-encrypt	Skip Rivet-side age encryption for --backend fs/rclone (default: encrypted). Ignored for restic, which owns its own encryption, and for git.
--no-interactive	Only create the repository; skip the guided first-run setup. The wizard is skipped automatically when stdin is not a terminal.

rivet snapshot

Collect approved state and make a Git commit only when it changed.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
--message <TEXT>	Custom commit message for this snapshot.
--push	Push the snapshot commit to its configured origin remote.
--force-push	Replace origin/main only if the expected remote state still matches.
--delete-latest	Delete the newest local snapshot commit instead of creating one.
--yes	Required with –delete-latest; acknowledges destructive history removal.
--profile <NAME>	Capture only this machine profile’s subset of the policy (see [profile.<name>] in rivet.toml).

rivet status

Report selected configuration drift since the latest snapshot.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.

rivet audit

Report file, package and secret drift against a snapshot revision.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
--revision <GIT-REF>	Audit against a specific snapshot commit instead of the latest one (e.g. HEAD~1, or a commit hash).
--profile <NAME>	Audit only this machine profile’s subset of the policy.

rivet restore

Print a restore plan, or overwrite tracked configuration after explicit confirmation.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
--select	Interactively choose package sources and individual artifacts to restore.
--only <CATEGORIES>	Restore only these comma-separated categories: configuration group ids from the snapshot, and/or packages. Anything not named is excluded. Run rivet restore to see the available categories.
--diff	Show, per file, how the snapshot differs from your home directory before anything is written.
--apply	Apply tracked configuration files after making rollback copies.
--yes	Required with –apply; acknowledges that existing files will be overwritten.
--revision <GIT-REF>	Restore from a specific snapshot commit instead of the latest one (e.g. HEAD~1, or a commit hash).
--strict-packages	On a cross-distro restore, refuse lower-confidence Repology-derived package matches and keep only exact curated ones.
--backend <ID>	Restore from this configured backend instead of the first one (see rivet init --backend). Defaults to plain Git when no backend has been configured.
--profile <NAME>	Restore only this machine profile’s subset of the snapshot.

rivet track

Track an arbitrary file or directory beyond the built-in groups.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
<PATH>	The path to track; ~/$HOME are expanded and it must be inside your home directory. Omit with –list.
--list	Show the declared [[track]] entries instead of adding one.
--include <GLOB>	Only capture paths matching this glob, relative to the tracked path (repeatable), e.g. –include ‘**/*.sh’.
--exclude <GLOB>	Never capture paths matching this glob (repeatable).
--vault	Seal this path’s files into the encrypted vault instead of capturing them as plaintext (requires rivet vault init).
--allow-excluded-names	Relax Rivet’s name-based exclusions (cache, secrets, credentials, …) for this path only. The content secret scanner still applies.

rivet untrack

Stop tracking a path previously added with rivet track.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
<PATH>	Required. The tracked path, in any spelling rivet track accepts.

rivet tui

Browse the checklist, history, diff and restore plan in a terminal UI.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
--backend <ID>	Read from this configured backend instead of the first one.
--profile <NAME>	Show only this machine profile’s subset.

rivet plugins

List built-in and declarative user plugins and where they came from.

Takes no flags.

rivet vault

Manage the encrypted secrets vault (age-based; ADR-0003).

Takes no flags.

rivet vault init

Generate the vault identity and record its public recipient.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
--passphrase	Passphrase-protect the identity file at rest (prompted, no echo).
--recipient <age1...>	Also register a backup/offline recipient (strongly recommended so a lost identity does not mean lost secrets).

rivet vault add-recipient

Register another public recipient future seals also encrypt to.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
<RECIPIENT>	Required. The age1... public recipient to add.

rivet vault add

Declare a file to track as an encrypted secret (e.g. ~/.ssh/config).

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
<PATH>	Required. The source path; ~/$HOME are expanded, and it must be inside your home directory.
--store <STORE>	Which store seals it: age (built-in) or sops.
--name <NAME>	Override the name derived from the path.

rivet vault list

List configured recipients and declared secrets.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.

rivet vault rm

Undeclare a secret by name and drop its sealed blob.

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.
<NAME>	Required. The declared secret’s name (see vault list).

rivet vault seal

Seal declared secrets into the repo now (a preview; snapshot also seals them).

Flag	Effect
--repo <PATH>	The snapshot repository to work in. Defaults to $RIVET_REPO, or to the repository recorded by the last successful rivet init.

rivet about

Print Rivet’s supported workflow and safety boundary.

Takes no flags.

---

Notes and cross-links

These are the parts of the CLI that need more than a --help line.

• --json — the output schemas are a supported automation interface and are documented under JSON output.

• --profile — narrows a command to one machine’s subset of the policy. It can only ever narrow; see Machine profiles.

• rivet status is the file-only subset of rivet audit, kept as its own verb.

• rivet tui needs an interactive terminal and has no --json form. Every screen has a CLI equivalent — see the terminal UI guide.

  rivet tui --repo ~/rivet-snapshots

• rivet track --allow-excluded-names relaxes only the name-based exclusions (cache, secrets, …) for that one path. The content secret scanner still applies to every file, always.

• rivet vault … — public recipients live in rivet.toml; the private identity lives only at ~/.config/rivet/identity.age and never enters a snapshot.

Register a backup recipient

A lost identity with no second recipient means lost secrets. vault init --recipient age1... is strongly recommended. See Secrets vault.