portsmith 0.1.0

Local port management CLI — list, kill, watch, and snapshot listening ports

portman

A local port management CLI for macOS and Linux.

Installation

pip install portman

Or install from source:

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

Commands

portman list

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

portman list

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

# Machine-readable JSON output
portman 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.

portman kill <port>

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

portman kill 8080

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

portman watch

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

portman watch

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

portman save <name>

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

portman save myproject
portman save dev-stack

portman 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.

portman restore myproject

portman profiles

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

portman profiles

Requirements

• Python 3.10+
• macOS or Linux (Windows is not supported)

Notes

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