Skip to main content

Getting Started

CLI

Flags for report, JSON, dry-run, apply, undo, preflight, and MCP.

wsl-shadow                          # report
wsl-shadow --json                   # schemaVersion 1, for agents and CI
wsl-shadow --fix                    # prints proposals, changes nothing
wsl-shadow --apply                  # shows plan, asks you to type "apply"
wsl-shadow --undo                   # reverts only what --apply recorded
wsl-shadow --preflight              # pass/fail; stdout is a PATH prefix
wsl-shadow --mcp                    # read MCP configs (read-only)
wsl-shadow --view=exec              # interactive, login, exec, exec-zsh, here
wsl-shadow --require=node,npm
wsl-shadow --expect-windows=claude  # treat that tool as expected Windows

Safety

  • --fix: dry run. Prints proposals, changes nothing.
  • --apply: shows the plan; you type apply. Only a marked PATH block and /usr/local/bin symlinks. Backups first. Sudo for links only, never stored.
  • --undo: reverts only what --apply recorded.

Never touches /etc/wsl.conf, .wslconfig, /etc/profile, /etc/environment, ~/.bashrc, WSLENV, Windows PATH, System32, anything under /mnt/<drive>/, or anything it did not create. Never runs wsl --shutdown. Does not install nvm, Node, Bun, or claude.

One --apply run

Lab run on WSL2 Ubuntu. Sudo prompt was a stand-in; real sudo --apply not yet tested.

$ wsl-shadow --apply

plan
  link     sudo ln -s .../corepack /usr/local/bin/corepack
  backups  ~/.local/state/wsl-shadow/backups

Type "apply" to continue: apply

applied  /usr/local/bin/corepack -> .../corepack
before   npm shadow (exit 1)
after    npm ok (exit 0)

Limits

Measured on WSL2 Ubuntu. Untested: WSL1, Alpine, arm64 hardware, --apply with a real sudo prompt.