port-doctor 0.1.5

A robust CLI tool to track, manage, and free up local development ports safely.

Port Doctor

A small CLI for tracking which local port is reserved for which dev task — and for freeing one up when something's squatting on it.

Features

• Reserve a port for a task, so you remember why it's taken
• List your reservations with live status (free, or in use and by what)
• Free a port by killing whatever's listening on it (asks for confirmation first)
• Scan every listening port on the system, not just the ones you've reserved

Installation

pip install port-doctor

Requires Python 3.7+ and psutil (installed automatically). Works on Linux, macOS, and Windows.

Usage

# Reserve a port for a task
port-doctor reserve 3000 "Claude Code"

# The shorter alias works too
pd reserve 3000 "Claude Code"

# List your reservations and their live status
port-doctor list
pd list

# Free a port — kills the listening process (prompts for confirmation)
port-doctor free 3000
pd free 3000

# Remove a reservation without touching any running process
port-doctor unreserve 3000
pd unreserve 3000

# See every listening port on the system, reserved or not
port-doctor active
pd active

Add -y/--yes to free or -f/--force to reserve to skip the confirmation prompt, e.g. for scripts.

Notes

• Reservations live in ~/.port-doctor.json.
• Inspecting or killing processes you don't own may require sudo/Administrator, depending on your OS.

License

MIT