portsmith

A local port management CLI for macOS, Linux, and Windows.

Installation

pip install portsmith

Or install from source:

git clone <repo>
cd portsmith
pip install -e .

Commands

portsmith list

Show all listening ports with PID, process name, port, protocol, and status. System ports (<1024) are highlighted in yellow, user ports in green.

portsmith list

# Only show ports opened from this terminal session
portsmith list --mine

# Machine-readable JSON output
portsmith list --json

--mine note: this flag filters to processes running under your OS user account. It removes system services (svchost, lsass, etc.) but will still show other user-owned background apps that happen to listen on ports (e.g. Chrome, cloud sync clients). It correctly catches dev servers started in any shell or terminal window.

portsmith kill <port>

Kill the process listening on a given port. Asks for confirmation unless --force is passed.

portsmith kill 8080

# Skip confirmation
portsmith kill 8080 --force
portsmith kill 8080 -f

portsmith watch

Live-updating view of all active ports, refreshing every 2 seconds. New ports are highlighted green, closed ports red. Exit with Ctrl+C.

portsmith watch

# Only watch ports opened from this terminal session
portsmith watch --mine

portsmith save <name>

Save a snapshot of all currently active user ports (port ≥1024) to ~/.portsmith/profiles/<name>.json.

portsmith save myproject
portsmith save dev-stack

portsmith restore <name>

Check a saved profile against currently running ports. Shows which saved processes are still running and which are missing, along with hints for restarting them.

portsmith restore myproject

portsmith profiles

List all saved profiles with their creation timestamp and port count.

portsmith profiles

Requirements

• Python 3.10+
• macOS, Linux, or Windows

Notes

• Ports below 1024 are system ports and may require sudo to kill.
• portsmith restore does not restart processes — it only reports their status and suggests what needs to be restarted.
• Profiles are stored in ~/.portsmith/profiles/ as JSON files.