Metadata-Version: 2.4
Name: portvac
Version: 0.1.0
Summary: See what's listening on a TCP port and free it - cross-platform, zero dependencies.
Author: yyfjj
License: MIT
Project-URL: Homepage, https://github.com/jjdoor/portvac-py
Project-URL: Repository, https://github.com/jjdoor/portvac-py
Project-URL: Issues, https://github.com/jjdoor/portvac-py/issues
Keywords: port,kill-port,process,lsof,cli,devtools,cross-platform,debugging,sysadmin,zero-dependencies
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# portvac

**See what's listening on a TCP port - and free it.** The "port already in use"
error costs every developer a minute of `lsof` / `netstat` / `taskkill`
archaeology. `portvac` lists who's on a port in one command, then vacates it on
confirm. Cross-platform, **zero dependencies**.

```bash
pip install portvac
portvac             # list every listening TCP port
portvac 3000        # show what's on 3000, then kill it (asks first)
portvac 3000 -k     # kill without asking (scripts / CI)
portvac 3000 -s KILL   # SIGKILL instead of the default SIGTERM
```

Node shop? `npx portvac 3000 -k` works too - same tool, same behaviour.

## Why

> "Port 3000 is already in use" - and now you're pasting `lsof -i :3000` into
> Stack Overflow for the fourth time this week.

`lsof` flags differ from `netstat` which differs from Windows `taskkill`. You
remember none of them under pressure. `portvac` is the one command that works
the same on macOS, Linux, and Windows: **look first, kill second**, never
silent.

## How it works

1. **List** - shells out to the platform's own tool (`lsof` / `ss` / `netstat`)
   to read listening sockets. No daemon, no network.
2. **Show** - prints a clean table: port, pid, process name, address, family.
3. **Vacate** - on a port argument, asks `y/N`, then sends a signal (default
   `TERM`) to the owning pid(s). `-k` skips the prompt.

Nothing is installed system-wide and no data leaves your machine.

## Usage

```
portvac                       List every TCP port currently listening
portvac <port>                Show what's on <port>, then kill it (asks first)
portvac <port> --list         Show only, don't kill
portvac <port> -k             Kill without confirmation
portvac <port> -s KILL        Send KILL instead of TERM
portvac --json [<port>]       Machine-readable output (great for piping)

  -k, --force         Kill without confirmation
  -l, --list          List only; never kill
  -s, --signal <SIG>  TERM (default), KILL, INT, QUIT, HUP
      --json          Emit JSON; suppresses colors and prompts
  -v, --version
```

### JSON

```bash
$ portvac --json 3000
{
  "port": 3000,
  "listeners": [
    { "port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4" }
  ]
}
```

## Platform notes

| Platform | Lookup | Kill |
|----------|--------|------|
| macOS / BSD | `lsof -iTCP -sTCP:LISTEN -P -n` | `os.kill(pid, sig)` |
| Linux | `ss -tlnp` (falls back to `netstat -tlnp`) | `os.kill(pid, sig)` |
| Windows | `netstat -ano` + `tasklist` | `taskkill /PID <pid> /F /T` |

On Windows there's no POSIX signal hierarchy, so `portvac` force-terminates
(`taskkill /F`). To see another user's processes you may need elevated
privileges, same as the underlying tools.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | listed, or killed successfully |
| `1` | nothing listening / port not in use / aborted |
| `2` | error (bad args, tool missing, kill failed) |

## License

MIT
