Metadata-Version: 2.4
Name: port-doctor
Version: 0.2.0
Summary: A robust CLI tool to track, manage, and free up local development ports safely.
Author-email: Nazmul Hasan <nh2826239@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9.0
Dynamic: license-file

# 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

```bash
pip install port-doctor
```

Requires Python 3.7+ and [psutil](https://pypi.org/project/psutil/) (installed automatically). Works on Linux, macOS, and Windows.

## Usage

```bash
# 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
