# port-killer

A safe, cross-platform port killer for developers.

When a local dev server leaves a port occupied, `port-killer` shows the process first and asks before terminating it.

```bash
port-killer 3000
```

Example output:

```text
Port 3000 is occupied:

PID      Process              Port     Command
12345    node                 3000     npm run dev

Kill this process? [y/N]
```

## Features

- Find processes listening on one or more ports.
- Show PID, process name, port, and command line.
- Ask for confirmation before killing by default.
- Skip confirmation with `--yes` / `-y`.
- Preview with `--dry-run`.
- List without killing with `--list` / `-l`.
- Emit JSON with `--json`.
- Scan common development ports with `--dev`.
- Supports macOS, Linux, and Windows using native system commands.

## Install

From this repository:

```bash
cargo install --path .
```

On Windows, install Rust with `rustup` and make sure the Visual Studio C++ Build Tools workload is available so the default MSVC toolchain can link binaries.

After publishing:

```bash
cargo install dev-port-killer
```

## Usage

Inspect a single port and confirm before killing:

```bash
port-killer 3000
```

Kill without confirmation:

```bash
port-killer 3000 --yes
```

Preview what would be killed:

```bash
port-killer 3000 --dry-run
```

Only list occupied processes:

```bash
port-killer 3000 --list
```

Inspect several ports:

```bash
port-killer 3000 5173 8080
```

Scan common development ports:

```bash
port-killer --dev
```

Output JSON:

```bash
port-killer 3000 --json
```

## Platform Backends

- macOS/Linux: `lsof`, with Linux fallbacks to `ss` and `netstat`.
- Windows: `netstat` for lookup, PowerShell for process details, and `taskkill` for termination.

If a required command is missing or the process cannot be terminated because of permissions, the tool exits with a non-zero status and prints a clear error.

## Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | Success, cancellation, or port is free |
| `1` | General error |
| `2` | Invalid arguments |
| `3` | Process was found but could not be killed |
| `4` | Unsupported platform |
| `5` | Permission denied |

## Development

```bash
cargo fmt --check
cargo clippy -- -D warnings
cargo test
cargo build --release
```

For platform smoke tests, see [scripts/manual-test.md](scripts/manual-test.md).
