Rigo

When you replace a computer, you want your terminal and editor to feel familiar again. When you use both a Mac and Linux, you may want to share most settings while keeping a few differences separate. Rigo helps you organize and carry those configuration files between computers.

Rigo runs in the terminal on macOS, Linux, and Windows. It gathers the actual files into one folder and links them back to their original locations, so you can keep editing settings where you normally do.

This page introduces what Rigo can do and how to get started. Download a release, or follow the tutorial one step at a time.

Familiar settings on another computer

Git's .gitconfig, the shell's .zshrc, and editor settings inside .config/ are often called dotfiles. Rigo can also manage application settings whose names do not begin with a dot.

Rigo gathers the actual files into a folder called a vault. The vault is an ordinary folder. Use a sync service you already have, such as Syncthing, Dropbox, or iCloud Drive, to bring it to another computer.

On the other computer, use Rigo to put the settings in place. Keep using the same editing locations and your preferred editor.

Start with one computer and one file

You only need a sync service when you want to share settings with another computer. Start by managing a single configuration file on one machine.

Even on one computer, a vault makes scattered settings easier to locate and backs them up as a group. You can organize them without changing where you normally edit them.

A look at the workflow

Run rigo status to see how your managed settings are deployed on this computer.

Figure 1: A status list in a small sample environment. linked means the setting is linked to the vault. pending means the vault has the file but nothing exists at its target location on this computer yet.

In this example, .config/starship.toml is pending. Running rigo apply creates links for entries that have not yet been deployed. Settings that are already linked remain in place.

These screenshots were captured in Prompt for Mac while running the real Rigo in a demonstration environment. You can run Rigo commands in your usual terminal.

Folders and links

The vault follows the same layout as your home folder. For example:

~/Sync/Vault/
├── .gitconfig
├── .zshrc
└── .config/
    └── rigo/
        └── rigo.toml

Rigo creates a symbolic link from ~/.gitconfig to .gitconfig in the vault, and from ~/.zshrc to the vault's .zshrc. A link lets an app read the actual file through its usual location.

When you open and save ~/.gitconfig, you edit the actual file in the vault. There is no need to copy it or run a command after each edit. If you sync the vault, the sync tool carries the change to your other computers.

Use apply when putting new settings in place, including files newly delivered by your sync tool. Editing a file's contents and creating a link at its target location are separate operations.

Design philosophy

Three ideas guide everyday use of Rigo.

• Choose your own sync method
  Rigo puts settings in place and leaves synchronization to your preferred tool. If you want version history, you can also put the vault under Git.
• Your edits update the actual file
  The app reads the linked file directly, so you can keep editing as usual. Some apps need to reload their settings or restart after a change arrives.
• File locations describe the setup
  There is no need to encode file names or list managed files in a separate manifest. Looking inside the vault tells you what it contains.

Use rigo.toml to annotate the vault, for example to link an entire directory as one unit or choose which machines receive particular settings. You can start with an empty file and add options as needed.

Check differences before choosing

A new computer may already have configuration files. If their contents differ from the vault, Rigo reports a conflict. rigo apply leaves these files untouched so you can review them individually.

Specify a file, such as rigo link .gitconfig, to compare the differences and choose which version to use.

Figure 2: The vault has editor = vim, while this computer has editor = code --wait. Compare the contents before making a choice.

The choices are to take the vault version, adopt this computer's version into the vault, or cancel. Lines marked - show the vault's contents; lines marked + show this computer's contents.

To stop managing a setting, use rigo forget to turn the link back into a regular file. The vault's copy moves to the vault's trash rather than being deleted immediately.

What you can do

You do not need every feature at once. Start with shared settings and add differences as your setup grows.

What you want to do	How Rigo helps
Add settings gradually	Add files individually, or link a whole directory as one unit
Check deployment	Shows five states: linked, pending, unlinked, conflict, and broken
Keep differences between Mac and Linux	Layer shared files with OS-specific, Linux distribution, and WSL settings
Separate work and personal setups	Select entries by host or group, including extra files for particular machines
Handle related editor settings together	Use tags to link or unlink entries in a group
Use Windows too	Supports application configuration locations and drives outside the home directory
Store sensitive information separately	Use secrets to write values from 1Password references to designated files
Recover a setting removed from management	Inspect the vault's trash and restore the saved copy

See How Rigo works for layouts and states, and the configuration reference for per-machine deployment and 1Password integration.

Why I made Rigo

I wanted to gather settings into a folder I already synced and use them across Mac, Linux, and Windows. Editing a file in its usual location should update the actual file directly. Deploying it on another computer should let me compare existing settings before choosing. Rigo brings those ideas together.

The name combines “rig,” as in setting up an environment, with “Go,” the implementation language.

Requirements

Platform	Requirements
macOS	13 or later
Linux	Linux binaries are available
Windows	11. Creating symbolic links requires Developer Mode or an elevated prompt

Rigo is a terminal-based CLI tool. It has no template engine for transforming file contents per machine. Store differing settings as separate files in OS layers or other supported layers.

Installation

Choose an archive for your OS and processor from the download page. Extract rigo (rigo.exe on Windows) and place it somewhere on your command search path. Linux .deb and .rpm packages are also available.

If you use Go, you can also install with:

go install github.com/rinodrops/rigo@latest

Check the installed version:

rigo version

Then continue to the macOS and Linux tutorial or the Windows tutorial.

Where to go next

What you want to learn	Read
Try the first setup and deploy to another computer	macOS and Linux tutorial / Windows tutorial
Understand the vault, links, and OS differences	How Rigo works
Look up command options and behavior	Command reference
Configure tags and per-machine deployment	Configuration reference

License

Rigo is released under the MIT license. Find the source and releases on GitHub.