Command Reference

Syntax

rigo [-f <path>] <command> [flags] [<path>]

Global Flags

Flag	Description
-f, --file <path>	Names the rigo.toml inside the vault directly. Meant for the first-run bootstrap; normally the vault is discovered automatically through the ~/.config/rigo/rigo.toml symlink
-v, --version	Prints the version
-h, --help	Prints help

Path Arguments

Commands that take a <path> resolve both logical paths (home-relative, slash-separated; for example .zshrc or .config/git/config) and real paths (~/.zshrc or absolute paths) to the same entry. A leading ~/ is expanded by Rigo itself even when the shell does not expand it.

Exit Codes

On error, Rigo prints rigo: <message> to standard error and exits with code 1. The exception is diff, which exits with code 1 and no message when differences exist (the same convention as diff(1)).

Interactive and Non-Interactive

Dialogs such as conflict resolution only run when standard input is a terminal (TTY). In non-interactive contexts such as scripts, an operation that would need a dialog fails with an error naming the flag that replaces it (see the individual commands).

status

rigo status [<path>]

Shows the state of managed entries. With an argument, shows only that entry.

host: mymac (mode: exclude)

linked    .config/rigo/rigo.toml
linked    .zshrc
pending   .config/git/config
excluded  .vim/

The header shows this machine's host name and selection mode (exclude = blacklist / include = allowlist). See How It Works for what the states mean.

apply

rigo apply

Converges every selected entry.

• pending (not deployed) and unlinked (real but identical) → linked. Unlinked content is identical to the vault, so nothing is lost
• conflict → listed only, never touched (resolve with rigo link <path>)
• broken → listed only, never touched (clean up with rigo clean)
• excluded → counted only
• A failure on one entry (a disconnected drive, say) is recorded for that entry and the rest still converge

linked    .config/git/config
conflict  .zshrc  (resolve with "rigo link .zshrc")

1 linked, 1 conflict, 0 broken, 0 failed, 0 excluded

One or more failures make the exit code 1. Remaining conflicts or broken links are not treated as errors.

link

rigo link [--force] <path>

Links one entry from the vault. The behavior per state:

State	Behavior
linked	Does nothing (says so)
pending / unlinked	Links
broken	Shows where the link pointed, then re-points it
conflict	Resolves interactively (below)

Resolving a Conflict

Shows file information for both sides and a diff summary (+12 -3 for text, binary files differ for binaries, 2 added, 1 removed, 3 changed (local vs vault) for directory units). A diff of 40 lines or fewer is shown inline; beyond that, a d) option is added to the choices.

conflict: .zshrc
  vault: 1234 B, modified 2026-07-18 10:00:12
  local: 987 B, modified 2026-07-01 08:15:44
  +12 -3

  1) take the vault version (local content is replaced)
  2) adopt the local content into the vault, then link
  3) abort
choice:

• 1
  Takes the vault side. The local content is replaced
• 2
  Adopts the local content into the vault, then links
• 3
  Aborts without doing anything

--force is the non-interactive version of choice 1 (take the vault side). A conflict on a non-TTY without --force is an error.

Linking always plays it safe: the existing content is staged aside before the symlink is created, and restored if that fails.

unlink

rigo unlink <path>

Materializes a linked entry: the symlink is replaced by a real copy of the vault content, the vault copy is kept, and the entry stays managed (status shows it as unlinked). Use it to experiment locally for a while; rigo link puts it back.

In any state other than linked, the command fails with a message naming the current state and the operation to use instead.

add

rigo add [flags] <path>

Moves the real content at <path> into the vault and links it back into place. The move and the link roll back on failure (content is never left in limbo).

Flag	Description
--os	Places the entry in the OS-specific layer (.os/<goos>/)
--dir	Deploys a directory as one symlink (recorded automatically in dirs in rigo.toml)
--files	Moves and links each file inside individually instead of the directory as a unit
--tag <name>	Records the entry as a member of the named tag in rigo.toml
--keep-symlink	When <path> is itself a symlink, stores the symlink as-is instead of adopting its referent
--volume <name>	Names the volume for a Windows path on a non-system drive

Directories

--dir and --files are mutually exclusive. Running add on a directory with neither flag asks interactively (on a non-TTY it fails, asking for one of the flags).

With --files, the directory itself stays a real directory and each file inside becomes an individual entry. Files matching an ignore pattern are skipped. Combined with --tag, each moved file is recorded as a member of the tag.

Adding a Symlink

When <path> is a symlink, the default is to adopt the referent's content into the vault (a copy; the referent itself stays where it is). To store the symlink itself as part of your configuration, use --keep-symlink.

Paths Outside Home, and Windows

Absolute paths outside home automatically go under .abs/ in the OS-specific layer. On Windows, paths under %APPDATA% / %LOCALAPPDATA% map to the .appdata/ / .local/ sections, and paths on non-system drives go through named volumes. A non-system drive needs --volume, or an interactive volume-name choice; an undeclared volume is declared automatically in [volumes] in rigo.toml.

volume name for drive D: [data]:
declared volume data = "d" in rigo.toml

Refusals

For safety, the following adds fail:

• A path inside the vault
• An entry already managed, or a path inside a directory-unit entry
• A path matching an ignore pattern (it would be invisible once managed)
• A path whose vault-side counterpart already exists

forget

rigo forget <path>

Stops managing an entry. A link deployed locally is materialized first (a real copy stays with you), the vault copy moves to the trash, and references in rigo.toml (dirs / tags / include / exclude) are removed automatically.

forgot .vim/ (vault copy moved to .trash/20260718T093000Z/.vim)
removed 2 reference(s) from rigo.toml

• Real local content (files in the unlinked / conflict states) is never overwritten
• Works on entries excluded on this host too (it is a vault-level operation; only the local materialization is skipped)
• rigo.toml itself cannot be forgotten

After syncing, the other machines are left with dangling symlinks; rigo clean cleans those up on each machine.

diff

rigo diff [<path>]

A read-only command showing the differences between local content and the vault. Changes nothing.

• Without an argument
  Shows the diff of every entry in the conflict state
• With an argument
  Shows that entry's diff, or a note on its state when it is not a conflict

The exit code is 1 when differences were shown (the diff(1) convention; usable for drift detection in CI and scripts).

clean

rigo clean

Cleans up broken symlinks interactively. Two kinds are covered:

• Entries that scanning detected as broken
• Dangling links left behind by a forget synced in from another machine (found through the trash records; only symlinks pointing into the vault are touched, unrelated dangling links are not)

For each link, choices are offered; when a trash copy remains, restoring it is one of them.

broken: .vimrc (pointed to /Users/ada/Sync/Vault/.vimrc)
  r) restore the trash copy (20260718T093000Z) as a real file
  d) delete the symlink
  s) skip
choice:

• r
  Restores the trash copy as a real file (the trash copy is kept for the other machines)
• d
  Deletes the symlink (real content is never deleted)
• s
  Does nothing

On a non-TTY, only the list is printed.

tag

rigo tag show <name>
rigo tag link [--force] <name>
rigo tag unlink <name>

Bulk operations on the groups defined in [tags] in rigo.toml.

• show
  Lists the members and their states. Members with no vault counterpart show as missing
• link
  Links every member. Conflicts are resolved interactively (or with --force); on a non-TTY without --force they are skipped and reported. excluded members are left alone
• unlink
  Materializes every linked member. Members in other states are reported as (left alone)

Each command ends with a summary line.

1 linked, 2 already linked, 0 conflict, 1 excluded, 0 missing

trash

rigo trash ls
rigo trash restore <path>
rigo trash empty [--force] [--older-than <age>]

Operations on the in-vault trash, the safety net behind forget.

trash ls

Lists generations, newest first. Entries that do not deploy on this host (another OS's layer, say) are marked (not deployed on this host).

2026-07-18 18:30:00  .vim
2026-07-16 09:12:33  .os/windows/.appdata/foo.ini  (not deployed on this host)

trash restore <path>

Moves the newest trashed generation of the path back into the vault (the undo of forget). References that forget removed from rigo.toml (dirs / tags / include / exclude) are not restored; re-add them if needed. To deploy the entry again, run rigo apply or rigo link.

trash empty

Permanently deletes generations. The trash is a safety net shared by all machines, so a confirmation prompt appears by default.

Flag	Description
--force	Skips the confirmation prompt (required on a non-TTY)
--older-than <age>	Only deletes generations older than the given age, written in days (d) or Go duration syntax, for example 30d or 72h

secrets

rigo secrets apply  [<path>]
rigo secrets status [<path>]
rigo secrets remove [<path>]

Fetches the references declared in [secrets] in rigo.toml from the password manager and writes them to their target paths. The scope is the entries that pass the OS filter (the os key) and per-machine selection, and the argument narrows it to one. The current backend is 1Password (op:// references; the op CLI is required).

secrets apply

Fetches each secret and writes it to its target (overwriting an existing file). Parent directories are created with mode 0700, the file gets its declared mode (0600 by default), and the write is atomic via a temporary file, so an interruption never leaves a partial secret. 1Password's own authentication prompts (Touch ID and so on) pass through untouched.

secrets status

Reports applied / missing for each secret's target. The check is existence only; by design there is no hash or freshness comparison (the backend remains the source of truth, and you re-run apply after updating a value).

secrets remove

Deletes the written files (the reverse of apply; for handing off a machine, say). A missing file is not an error. A note reminds you that secure erasure is not guaranteed on SSDs.