Metadata-Version: 2.3
Name: portwho
Version: 1.0
Summary: Small CLI utility to find which process is using a TCP or UDP port
Keywords: port,network,cli,process,tcp,udp,diagnostics
Author: DasKaroWow
Author-email: DasKaroWow <daskarowow@gmail.com>
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Dist: psutil>=6.1.1
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/DasKaroWow/portwho
Project-URL: Repository, https://github.com/DasKaroWow/portwho
Project-URL: Issues, https://github.com/DasKaroWow/portwho/issues
Description-Content-Type: text/markdown

# portwho

Small CLI utility to find which process is using a port and optionally stop it.

## What it does

`portwho` helps you:

- inspect a TCP or UDP port
- see which process is bound to that port
- view basic process information
- optionally terminate that process
- optionally force kill it if graceful termination does not work

This is useful when a local server fails to start because a port is already occupied.

## Features

- supports TCP and UDP
- shows PID, process name, executable path, command line, and status
- groups listeners by process
- can terminate processes on the target port
- supports graceful stop with optional force kill fallback
- simple terminal output

## Installation

Clone the repository and install it in a virtual environment.

```bash
git clone <your-repo-url>
cd portwho
pip install -e .
```

## Requirements

- Python 3.10+
- `psutil`

## Usage

Basic form:

```bash
portwho <port>
```

Examples:

```bash
portwho 8000
portwho 8000 --protocol tcp
portwho 53 --protocol udp
portwho 8000 --kill
portwho 8000 --force
```

## Command line arguments

### `port`

Target port number.

Example:

```bash
portwho 8000
```

### `--protocol {tcp,udp}`

Choose which protocol to inspect.

Default:

```text
tcp
```

Examples:

```bash
portwho 8000 --protocol tcp
portwho 53 --protocol udp
```

### `--kill`

Try to stop processes using the port.

Example:

```bash
portwho 8000 --kill
```

### `--force`

If normal termination times out, force kill the process.

Example:

```bash
portwho 8000 --force
```

## Notes

- process termination may fail due to insufficient permissions
- some system or protected processes may not expose full metadata

## License

MIT License.