sympath 0.1.0

A powerful symlink-based path manager for developers

sympath

A powerful, cross-platform symlink-based path manager for developers.

sympath lets you stop cluttering your system PATH with dozens of directories. Instead, maintain one folder full of symlinks that point to the real executables — and only add that single folder to PATH.

This is how Linux distros manage /usr/local/bin, and now you can do it on any OS.

---

Why sympath?

Problem	sympath's Solution
PATH is thousands of characters long	One clean directory in PATH
Duplicate / stale PATH entries	Managed symlinks you can list & repair
Package managers fight over PATH	You decide what's exposed
Hard to see what tools are available	sympath list shows everything
Different projects need different tools	Multiple named link folders

---

Installation

From source (editable / development)

git clone https://github.com/your-user/sympath.git
cd sympath
pip install -e .

Run without installing

python -m sympath --help

Note (Windows): Creating symlinks may require Administrator privileges or Developer Mode enabled.

---

Quick Start

# 1. Register a link directory
sympath add-folder tools C:\tools\bin

# 2. Add that directory to your system PATH (once, manually)

# 3. Link individual executables
sympath link "C:\Program Files\Neovim\bin\nvim.exe"
sympath link "C:\MinGW\bin\gcc.exe"
sympath link "C:\Python313\python.exe" --name py.exe

# 4. Or link every executable in a folder at once
sympath link-folder "C:\Program Files\LLVM\bin"

# 5. See what you have
sympath list

# 6. Remove a link you no longer need
sympath remove gcc.exe

# 7. Find and report broken links
sympath repair

After this, running nvim, gcc, or py from any terminal will just work — they all resolve through C:\tools\bin.

---

Commands

sympath add-folder <name> <path>

Register a directory that will hold symlinks. The first folder you register automatically becomes the default.

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

sympath set-default <name>

Change which registered folder is used when no --folder flag is given.

sympath set-default dev

sympath link <target> [options]

Create a symlink inside the default (or specified) folder pointing to <target>.

Option	Description
--name <alias>	Use a custom filename for the symlink instead of the target's basename
--folder <name>	Place the link in a specific registered folder
--force	Overwrite an existing symlink without prompting

# Basic
sympath link "C:\Program Files\Neovim\bin\nvim.exe"

# Custom name
sympath link "C:\Program Files\Neovim\bin\nvim.exe" --name vim.exe

# Into a specific folder, overwriting if it exists
sympath link "C:\Python313\python.exe" --folder dev --force

sympath link-folder <path> [options]

Scan a directory and create symlinks for every executable found inside it.

Option	Description
--folder <name>	Target link folder
--force	Overwrite existing links

Executable detection:

• Windows — .exe, .cmd, .bat, .ps1, .sh
• Linux / macOS — any file with the executable permission bit

sympath link-folder "C:\Program Files\LLVM\bin"

sympath remove <name> [--folder <name>]

Delete a managed symlink.

sympath remove gcc.exe
sympath remove gcc.exe --folder dev

sympath list [--folder <name>]

Display all symlinks in a folder with their targets. Broken links are flagged.

sympath list

  python.exe → C:\Python313\python.exe
  gcc.exe    → C:\MinGW\bin\gcc.exe
  nvim.exe   → C:\Program Files\Neovim\bin\nvim.exe  [BROKEN]

sympath repair [--folder <name>]

Scan for symlinks whose targets no longer exist and report them.

sympath repair

  Broken: C:\tools\bin\nvim.exe
  Broken: C:\tools\bin\python.exe

Global Options

Flag	Description
-h, --help	Show help for any command
-v, --version	Print the installed version

sympath --help
sympath link --help
sympath --version

---

Configuration

sympath stores its state in a single JSON file:

~/.sympath.json

Example contents:

{
  "default": "tools",
  "folders": {
    "tools": "C:\\tools\\bin",
    "dev": "C:\\dev\\bin"
  }
}

Field	Type	Description
default	string	Name of the folder used when --folder is omitted
folders	object	Map of registered name → absolute directory path

---

Cross-Platform Support

Platform	Executable Detection	Notes
Windows	.exe, .cmd, .bat, .ps1, .sh	May require admin or Developer Mode for symlinks
Linux	Executable permission bit (chmod +x)	Works out of the box
macOS	Executable permission bit (chmod +x)	Works out of the box

---

Example Workflow

# One-time setup
sympath add-folder tools C:\tools\bin
# → then add C:\tools\bin to your system PATH

# Day-to-day usage
sympath link "C:\MinGW\bin\gcc.exe"
sympath link "C:\Program Files\Neovim\bin\nvim.exe"
sympath link "C:\Python313\python.exe" --name python.exe
sympath link-folder "C:\Program Files\Git\cmd" --force

# Maintenance
sympath list
sympath repair
sympath remove gcc.exe

Result: your PATH stays clean with a single entry, and all your tools are one sympath link away.

---

Project Structure

sympath/
├── pyproject.toml       # Package metadata & entry point
├── README.md            # This file
├── vision.md            # Full feature specification
└── sympath/               # Python package
    ├── __init__.py      # Package version
    ├── __main__.py      # python -m sympath support
    ├── cli.py           # Argument parsing & command dispatch
    ├── config.py        # ~/.sympath.json load / save
    ├── manager.py       # Core SymlinkManager class
    └── utils.py         # Executable detection helpers

---

Roadmap

• sympath migrate-path — convert existing PATH dirs into managed symlinks
• sympath scan — discover installed tools on the system
• sympath use <tool> <version> — version switching
• sympath profile <name> — environment profiles
• Plugin system for tool-specific managers

---

License

MIT