sympath

Universal PATH manager and tool version switcher.

One directory in PATH. All your tools linked there. Switch active versions instantly. No downloads — sympath links what you already have installed.

pip install sympath

Windows: Symlinks require Developer Mode or Administrator. Use sympath link --shim as a no-admin alternative (creates a .cmd wrapper).

---

The Problem

• PATH has 30+ entries, thousands of characters long
• Package managers add their own dirs and fight each other
• No easy way to switch between Python 3.12 and 3.13
• New machine setup means rebuilding PATH from scratch
• Windows users hit the 260-char PATH limit

sympath solves all of this. One managed folder. One PATH entry. Full control.

---

Quick Start

# 1. Register a folder to hold your symlinks
sympath add-folder tools C:\tools\bin        # Windows
sympath add-folder tools /home/user/.local/bin  # Linux/macOS

# 2. Run doctor to get the exact PATH snippet for your shell
sympath doctor

# 3. Add that snippet to your shell config (shown by doctor)

# 4. Start linking tools
sympath link "C:\Python313\python.exe"
sympath link "C:\Neovim\bin\nvim.exe" --name vim.exe

# 5. See what you have
sympath list

# 6. Audit your current PATH for waste
sympath audit

---

Commands

Diagnostics

sympath info

Show config file location, default folder, registered folders with link counts, and versioned tools.

sympath doctor

Detect your shell, check if managed folders are in PATH, and print the exact snippet to paste into your shell config.

Shell: powershell
Managed folders:
  tools  ✗ NOT in PATH  →  C:\tools\bin

Add to $PROFILE:
  $env:PATH = "C:\tools\bin;" + $env:PATH

sympath audit [--json]

Scan every directory in your live PATH. Reports duplicates, broken dirs, empty dirs, and total executable count.

PATH entries: 34
  broken:     3
  duplicates: 5
  empty:      8
  total executables exposed: 189

  C:\Windows\system32  (142 exe)
  C:\tools\bin  (31 exe)  [managed]
  C:\Python312  (DUPLICATE)
  C:\OldApp\bin  (BROKEN)

---

Folder Management

sympath add-folder <name> <path> [--force]

Register a directory to hold symlinks. First folder registered becomes the default.

sympath add-folder tools C:\tools\bin
sympath add-folder dev   C:\dev\bin

sympath remove-folder <name>

Unregister a folder. Disk contents are NOT deleted.

sympath list-folders

List all registered folders and which is the default.

sympath set-default <name>

Change which folder is used when --folder is omitted.

---

PATH Migration

sympath migrate-path <dir> [--dry-run] [--confirm] [--folder NAME] [--force]

Link all executables from an existing PATH directory into your managed folder. Always preview with --dry-run first.

sympath migrate-path "C:\MinGW\bin" --dry-run
sympath migrate-path "C:\MinGW\bin" --confirm

---

Link Management

sympath link <target> [--name ALIAS] [--folder NAME] [--force] [--dry-run] [--shim]

Create a symlink to an executable.

sympath link "C:\Neovim\bin\nvim.exe"
sympath link "C:\Neovim\bin\nvim.exe" --name vim.exe
sympath link "C:\Python313\python.exe" --shim    # Windows: no admin needed

--shim creates a .cmd wrapper (Windows) or shell script (POSIX) instead of a symlink. Callable without extension on Windows.

sympath link-folder <path> [--folder NAME] [--force] [--dry-run]

Link every executable found in a directory.

sympath link-folder "C:\Program Files\LLVM\bin"
sympath link-folder /usr/local/go/bin --folder dev

sympath remove <name> [--folder NAME]

Remove a managed symlink.

sympath list [--folder NAME] [--json]

List all symlinks with targets. Broken links flagged.

sympath repair [--folder NAME] [--delete] [--dry-run] [--json]

Find broken symlinks. Use --delete to remove them.

---

Version Switching

Track multiple installed versions of any tool and switch between them instantly. sympath does not download anything — it links what you already have.

sympath register <tool> <path> --version <ver> [--folder NAME] [--force]

Register a named version of any tool. First version registered is automatically activated.

sympath register python C:\Python313\python.exe --version 3.13
sympath register python C:\Python312\python.exe --version 3.12
sympath register node   C:\nvm\v20\node.exe     --version v20

sympath use <tool> <version> [--folder NAME]

Switch the active version (swaps the symlink instantly).

sympath use python 3.12
sympath use node v20

sympath which <tool>

Show active and all registered versions.

Tool: python
Active: 3.13 *
Versions:
  * 3.13  →  C:\Python313\python.exe
    3.12  →  C:\Python312\python.exe

sympath versions

List all tools that have registered versions.

---

Environment Profiles

Profiles are named snapshots of active tool versions. Switch your entire tool environment in one command.

sympath profile create <name> [--force]

Save current active versions as a named profile.

sympath profile create dev
sympath profile create ml

sympath profile switch <name>

Activate a saved profile (swaps all version symlinks).

sympath profile switch ml

sympath profile list

List all saved profiles.

---

Export / Import

Portable setup — replicate your tool registry on a new machine or share with teammates.

sympath export [--file <path>]

Export all folders, versions, and profiles to JSON.

sympath export --file tools.json

sympath import <file> [--force]

Import from a previously exported file.

sympath import tools.json

---

Configuration

State is stored in ~/.sympath.json:

{
  "default": "tools",
  "folders": {
    "tools": "C:\\tools\\bin",
    "dev":   "C:\\dev\\bin"
  },
  "versions": {
    "python": {
      "active": "3.13",
      "entries": {
        "3.13": "C:\\Python313\\python.exe",
        "3.12": "C:\\Python312\\python.exe"
      }
    }
  },
  "profiles": {
    "dev": { "python": "3.13" },
    "ml":  { "python": "3.12" }
  }
}

---

Cross-Platform

Feature	Windows	Linux	macOS
Symlinks	Requires Developer Mode or Admin	✓	✓
Shims (--shim)	✓ .cmd wrapper	✓ shell script	✓ shell script
Executable detection	.exe .cmd .bat .ps1 .sh	executable bit	executable bit
PATH separator	;	:	:
Config location	%USERPROFILE%\.sympath.json	~/.sympath.json	~/.sympath.json

---

Development

uv sync --dev          # install deps
uv run pytest          # run tests
uv build               # build dist/
.\dev.ps1 test-cov     # tests with coverage

---

Roadmap

• sympath tui — interactive dashboard (browse, switch versions, repair)
• .sympathrc — per-project profile auto-activation via shell hook
• sympath shell hook — generate cd hook for auto-profile switching

---

License

MIT — github.com/moneytosms/sympath