Configuration Reference

Rigo's configuration is a single TOML file at the fixed location <vault>/.config/rigo/rigo.toml inside the vault. It is linked to ~/.config/rigo/rigo.toml like any other managed file, so editing it on any machine reaches all of them.

The file annotates the vault; it is not a manifest. "What to manage" is decided by the vault's directory tree. Every key below is optional, and an empty file is valid. Unknown keys are errors (to catch typos).

Some keys are also written by Rigo itself: rigo add --dir appends to dirs, --tag to [tags], using an undeclared volume on Windows adds a declaration to [volumes], and rigo forget removes the references to the forgotten entry.

Full Example

# Directories deployed as ONE symlink (new files inside follow
# automatically). For any directory not named here, only the files
# inside are managed individually.
dirs = [".hammerspoon/"]

# Extra ignore patterns (gitignore-style globs against vault paths).
# OS droppings and sync-service artifacts are ignored built-in.
ignore = ["*.bak", "**/node_modules/"]

# Which directories under .os/linux/ are distro overlays,
# matched against the ID field of /etc/os-release.
distros = ["ubuntu", "debian"]

[tags]                       # name → members; naming a directory here
vim = [".vim/", ".vimrc"]    # also declares directory-unit deployment

[groups]                     # group → hosts (Ansible inventory style)
work = ["workpc", "buildbox"]

[include]                    # host/group → ONLY these deploy (allowlist)
servers = ["zsh", ".gitconfig"]

[exclude]                    # host/group → these do NOT deploy
work = ["vim"]

[volumes]                    # named volumes for Windows drives
data = { default = "d", workpc = "e" }

[secrets]                    # target path → password-manager reference
".netrc"           = { ref = "op://Personal/netrc/notesPlain", mode = 0o600 }
".config/gh/token" = "op://Personal/GitHub/token"

Path and Name Formats

Two shared formats, defined ahead of the keys:

• Logical paths
  Home-relative, slash-separated paths (for example .zshrc or .config/gh/token). A leading / or ~, and .., are not allowed. A trailing / is meaningful: it declares directory-unit deployment (dirs / tags)
• Host and group names
  Lowercase only, no dots. The constraint keeps runtime host-name matching independent of case folding. default is reserved as the fallback key in [volumes]

Top-Level Keys

dirs

An array of logical paths of vault directories deployed as a unit (one symlink). Any directory not listed here (or in [tags]) is not managed itself; the files inside are managed individually.

• Only directories can be listed. A file on the vault side is an error at scan time
• Paths inside a directory-unit entry cannot appear in other declarations (an error at scan time)
• A declaration with no vault counterpart produces a warning

ignore

An array of additional patterns excluded from scanning, matched as gitignore-style globs against vault-relative paths.

• A pattern without / matches basenames at any depth (for example *.bak)
• ** crosses directories (for example **/node_modules/)
• A trailing / restricts the pattern to directories

OS droppings (.DS_Store, Thumbs.db, and friends) and the artifacts of the major sync services (Syncthing, Dropbox, iCloud Drive, Google Drive, OneDrive, Nextcloud/ownCloud, Resilio Sync, Synology, NFS/FUSE temporary files, and so on) are excluded built-in. For services that localize conflict-copy filenames (Dropbox, Nextcloud), only the English forms are built in; cover other locales here.

Paths matching an ignore pattern are also refused by rigo add (they would become invisible once added).

distros

An array declaring which directories directly under .os/linux/ are distribution overlays. The values are ID fields from /etc/os-release (lowercase machine-readable IDs, for example ubuntu, debian, arch).

A declared directory is overlaid only on Linux machines whose ID matches. Undeclared directories count as ordinary home content (with a warning when one happens to match the host's distribution).

os_dir / abs_dir / trash_dir

Renames for the structural directories. Only a single directory name without path separators is accepted.

Key	Default	Role
os_dir	.os	Home of the OS-specific layers
abs_dir	.abs	Home of absolute paths outside home (inside each OS layer)
trash_dir	.trash	The forget trash

[tags]

A table of tag name → members (an array of logical paths). Tags serve two roles:

• The unit of bulk operations via rigo tag link/unlink/show <name>
• A name that [include] / [exclude] items can refer to

Listing a directory member with a trailing / doubles as a directory-unit declaration, just like dirs.

[tags]
vim = [".vim/", ".vimrc"]
zsh = [".zshrc", ".zprofile"]

[groups]

A table of group name → array of host names. The same idea as an Ansible inventory: it lets [include] / [exclude] / [volumes] refer to sets of hosts by name.

• A host name is the machine's host name up to the first dot, lowercased (the rigo status header shows it)
• The same name cannot serve as both a group name and a host name

[include] / [exclude]

Tables of host or group name → array of items (logical paths or tag names), selecting what deploys on each machine.

A host's effective include / exclude is the union of its own entries and those of every group it belongs to. Then:

• A host whose effective include is empty runs in exclude mode (the default): everything deploys, minus what matches the effective exclude
• A host with any effective include runs in include mode (an allowlist): only what matches the effective include deploys, minus the effective exclude

An item's path matches the entry itself, and naming a directory also matches every entry beneath it. For example ".config" covers every individual entry under .config/.

[include]
servers = ["zsh", ".gitconfig"]   # servers deploy ONLY zsh-tagged entries and .gitconfig

[exclude]
work = ["vim"]                    # work machines skip the vim tag

Deselected entries show as excluded in status and are not touched by apply / link. The same selection applies to secrets.

[volumes]

The table of named volumes for Windows. It declares the volume-name → drive-letter mapping that decides which drive the entries under .os/windows/.abs/<volume>/... deploy to.

Two value forms exist:

[volumes]
media = "m"                            # every host: M:\
data  = { default = "d", workpc = "e" } # D:\ by default, E:\ on workpc

• Drive letters are a single lowercase letter
• The keys of the table form are default (the fallback), host names, and group names. Precedence is the host itself > its groups > default; two of a host's groups assigning different letters is an error
• Entries of a volume that does not resolve on this host are skipped, with a warning
• The built-in volume system resolves to %SystemDrive% and needs no declaration (overriding it is allowed)

[secrets]

A table of target logical path → password-manager reference. rigo secrets apply fetches the value from the backend and writes it as a real file. The content never enters the vault, nor the sync.

Two value forms exist:

[secrets]
".config/gh/token" = "op://Personal/GitHub/token"           # shorthand: ref only
".netrc" = { ref = "op://Personal/netrc/notesPlain", mode = 0o600, os = ["darwin", "linux"] }

Key	Required	Description
ref	yes	The backend reference, a URI with a scheme. Currently supported: 1Password's op:// (requires the op CLI)
mode	—	Permissions of the written file. Default 0o600
os	—	An array of OSes the secret applies to ("darwin" / "linux" / "windows"). All OSes when omitted

• Target paths are logical paths (home-relative) and resolve to each OS's real path by the same rules as ordinary entries
• The same path cannot be both a vault entry and a secret (symlink deployment and file materialization cannot coexist; an error at run time)
• Per-machine selection via [include] / [exclude] applies to secrets as well

Validation Errors

rigo.toml is validated on load, and violations fail with specific messages. The main ones:

• Unknown keys (typo detection)
• Logical-path violations (absolute paths, a leading ~, or ..)
• Host or group name violations (uppercase, dots, or the reserved name default)
• A name used as both a group and a host
• A distros value that is not a lowercase os-release ID
• A [volumes] drive letter that is not a single lowercase letter
• A [secrets] ref without a scheme, a mode out of range, or an invalid os value
• An os_dir / abs_dir / trash_dir that is not a single directory name