Metadata-Version: 2.4
Name: port-doctor
Version: 0.1.5
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** 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

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

# 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
