port-doctor 0.2.0

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 one or more ports by killing whatever's listening on them (asks for confirmation first)
• Scan every listening port on the system, or just your dev-oriented ports
• Inspect likely framework/container labels for running processes
• Tail best-effort logs for the process behind a port

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

# Free multiple ports or a range, and preview first
pd free 3000 8000 5432 --dry-run
pd free 3000-3005

# 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

# Focus on dev-like ports and labels only
pd active --dev

# Best-effort tail of a process's redirected logs
pd logs 8000

Add -y/--yes to free, --dry-run to preview kills, -f/--force to reserve, or --dev to active to focus on likely development servers.

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