Tutorial (Windows)

This tutorial runs the same scenario as the macOS and Linux tutorial in Windows Terminal. Starting from nothing under management, it puts your dotfiles under Rigo and syncs them with a second machine. On top of that, it covers the Windows-specific locations (the .local / .appdata sections and named volumes).

Command examples use PowerShell as the primary shell, with NYAGOS tabs added only where the syntax differs. NYAGOS is a Unix-like shell, so wherever there is no tab, the macOS-style commands work as written.

Prerequisites

• Installation is done
• Developer Mode is enabled (Settings → System → For developers), or you run from an elevated prompt. Rigo creates symlinks, so one of the two is required
• You have some way to sync a directory between machines (Syncthing, Dropbox, OneDrive, and so on). Rigo does not care which. Trying things out on a single machine needs none

The examples place the vault at ~\Sync\Vault; substitute the directory your sync tool actually syncs.

~ works as written

PowerShell does not expand ~ in arguments to external commands; it passes the character through literally. Rigo, however, expands a leading ~, ~/, or ~\ to the home directory itself, so the examples in this tutorial work as written. $HOME works equally well. NYAGOS expands ~ on the shell side by default (tilde_expansion enabled).

Step 1 — Create the Vault

The vault is a plain directory. The only fixed thing is where the config file rigo.toml sits (<vault>\.config\rigo\rigo.toml), and it can be empty.

PowerShell

mkdir ~\Sync\Vault\.config\rigo
New-Item ~\Sync\Vault\.config\rigo\rigo.toml

NYAGOS

mkdir /p ~/Sync/Vault/.config/rigo
touch ~/Sync/Vault/.config/rigo/rigo.toml

Only for the first run, name this rigo.toml directly with -f and run apply.

rigo -f ~\Sync\Vault\.config\rigo\rigo.toml apply

linked    .config/rigo/rigo.toml

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

At this point the rigo.toml inside the vault has been linked to ~\.config\rigo\rigo.toml. Rigo follows this symlink to discover the vault, so -f is no longer needed from here on.

rigo status

host: workpc (mode: exclude)

linked    .config/rigo/rigo.toml

The workpc in the header is this machine's host name (the identifier used later for per-machine selection).

If symlink creation is not permitted, this is where you get the error "creating symlinks on Windows requires Developer Mode or an elevated prompt"; check the Developer Mode prerequisite.

Step 2 — Manage Your First File

rigo add moves the real content into the vault and links it back into place. We start with .gitconfig, universal on Windows too.

rigo add ~\.gitconfig

added .gitconfig

Let's see what happened.

PowerShell

Get-Item ~\.gitconfig | Format-List LinkType, Target

NYAGOS

ls -l ~/.gitconfig

LinkType : SymbolicLink
Target   : C:\Users\ada\Sync\Vault\.gitconfig

Open and edit ~\.gitconfig in your editor as you always have; what actually changes is the vault copy. The change rides the sync tool to your other machines as it is. There is no extra "edit, then apply" step.

Step 3 — Manage a Directory

When you add a directory, you choose between two treatments.

• --dir
  Deploys the whole directory as one symlink. New files created inside come under management automatically
• --files
  Moves and links each file inside individually instead of the directory as a unit

# Manage the whole vim runtime directory as one symlink, under a tag
rigo add --dir --tag vim ~\vimfiles

added vimfiles/ (directory unit)

Running add on a directory without either flag asks interactively. A directory added with --dir is recorded automatically in dirs in rigo.toml (or in [tags] when --tag is given).

Manual Work Is Fine Too

We have used rigo add so far, but it is not a required path. Rigo keeps no hidden state file or database; its only sources of truth are the vault's directory tree and the actual state of your files. As long as the result is the same, doing things by hand breaks nothing.

• Move a file into its place in the vault yourself and create the symlink yourself (with New-Item -ItemType SymbolicLink, for example). The next rigo status recognizes it as linked
• Put a file in the vault without linking it. The entry shows up as pending (if you moved it) or unlinked (if you copied it and the contents are identical), and rigo apply picks it up and links it
• Edit rigo.toml directly. The automatic additions made by --dir / --tag and the automatic volume declarations are conveniences only; writing the same thing by hand is equivalent

The commands exist to save you busywork: staging and rollback, conflict checks, config bookkeeping. Mix them with manual work freely.

Step 4 — Connect a Second Machine

Install Rigo on the second machine too, and wait for the sync tool to finish syncing the vault. All that remains is the first-run bootstrap.

rigo -f ~\Sync\Vault\.config\rigo\rigo.toml apply

linked    .config/rigo/rigo.toml
linked    vimfiles
conflict  .gitconfig  (resolve with "rigo link .gitconfig")

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

Files that did not exist yet (pending) were simply linked. The second machine, however, already had a ~\.gitconfig with different content, so it is reported as a conflict. Rigo never resolves a conflict silently. Resolve it as instructed.

rigo link .gitconfig

conflict: .gitconfig
  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:

To align with the first machine, choose 1; to make the second machine's content the truth and adopt it into the vault, choose 2. To skip the dialog, rigo link --force .gitconfig takes the vault side.

The procedure is the same when the second machine runs macOS or Linux. Entries in the common layer deploy on every OS, so a .zshrc added on a Mac shows up as pending on Windows too. Files that belong to one OS go under .os (the next step) or get excluded per machine (Step 6).

Step 5 — Windows-Specific Locations

Per-OS with --os

Even inside the home directory, files that only make sense on Windows go into the OS layer with --os.

# WSL settings only make sense on Windows
rigo add --os ~\.wslconfig

added .wslconfig

The entry goes under .os\windows\ in the vault and deploys only on Windows machines. The NYAGOS config ~\.nyagos is another good candidate for --os if you use NYAGOS on Windows only.

%APPDATA% / %LOCALAPPDATA% Are OS-Specific Automatically

Much of Windows application configuration sits under %APPDATA% / %LOCALAPPDATA% rather than directly in home. Paths under these are treated as OS-specific automatically, no --os needed, and land in the .os\windows\.appdata\ / .os\windows\.local\ sections of the vault. Windows Terminal's settings make a good example.

PowerShell

rigo add "$env:LOCALAPPDATA\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"

NYAGOS

rigo add "%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"

added .local/Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json

The leading .local/ in the logical path is the section corresponding to %LOCALAPPDATA%. From now on, this setting deploys to the same place on your other Windows machines.

Step 6 — Choose What Deploys Where

Entries you do not want on a work machine, and similar choices, are declared in rigo.toml. Since rigo.toml is itself managed, editing it on any machine reaches all of them.

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

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

Host names are the identifier shown in the rigo status header (host name up to the first dot, lowercased), and list items can be tag names or paths. Deselected entries show as excluded in status. See How It Works for details.

Step 7 — Secrets

Sensitive files such as API tokens are materialized from a password manager instead of having real content in the vault. Only references go into rigo.toml (the current backend is 1Password's op:// references; the Windows op CLI is required).

[secrets]                    # target path → password-manager reference
".config/gh/token" = "op://Personal/GitHub/token"

rigo secrets apply

applied  .config/gh/token

1 secret(s) written

On Windows, logical paths under .config/... resolve to ~\.config\... (when XDG_CONFIG_HOME is unset). The written files are real files and never enter the vault (nor the sync). After updating a value, re-run rigo secrets apply on each machine.

Step 8 — Named Volumes and Daily Operations

Managing Files on Another Drive

Absolute paths outside home can be managed too. Drives other than the system drive (usually C:) may carry different letters on different machines, so they go through a named volume. The first time, you just pick a volume name interactively.

rigo add D:\Tools\foo.ini

volume name for drive D: [data]:
added data:/Tools/foo.ini
declared volume data = "d" in rigo.toml

The entry goes under .os\windows\.abs\data\ in the vault and is addressed by the logical path data:/Tools/foo.ini. On a machine that keeps the same content on drive E:, you just widen the declaration per host in rigo.toml.

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

Daily Operations

The everyday commands are the same on every OS.

rigo diff                  # anything drifted? (read-only)
rigo apply                 # converge after the sync tool delivers new entries
rigo unlink .gitconfig     # materialize locally for a while
rigo forget .gitconfig     # stop managing (vault copy goes to the trash)
rigo trash ls              # the trash is the undo for forget
rigo clean                 # clean up broken links

For details, see Step 8 of the macOS and Linux tutorial and the command reference. Every rigo.toml item is covered in the configuration reference.