.portkill

Free stuck TCP ports in one command — without memorizing lsof, fuser, and kill pipelines.

The name reads like .portkill — a small, local dev utility (think .env-style prefix). The CLI binary is still portkill.

Published on npm: @burakboduroglu/portkill — install with npm i -g @burakboduroglu/portkill or npx @burakboduroglu/portkill (see Install).

When Node or another stack prints EADDRINUSE, .portkill shows who owns the port, lets you preview (--dry-run), then stops only what you intend — or use the local web UI (--gui on loopback), same logic as the CLI.

Why .portkill

| Instead of… | You get… | | --- | --- | | Copy-pasting lsof / xargs / kill -9 | One tool, clear output, safe defaults | | Guessing PIDs | Process name + PID per port | | Accidentally nuking the wrong thing | --dry-run first; --gui with browser confirm | | Another Electron app | Node only; --gui is a tiny HTTP server on 127.0.0.1 / ::1 |

Install

Registry page: npmjs.com/package/@burakboduroglu/portkill.

npm i -g @burakboduroglu/portkill
portkill --version

No global install:

npx @burakboduroglu/portkill --list

From Source

git clone https://github.com/burakboduroglu/portkill.git && cd portkill
npm install && npm run build
npm link   # optional: puts `portkill` on PATH

GUI Demo

Introduction to portkill --gui (local web UI on loopback — list listeners, dry-run, kill with browser confirm).

Open on YouTube

Quick Start

# What is listening everywhere?
portkill --list

# See what would happen (no signals sent)
portkill 3000 8080 --dry-run

# Stop listeners on those ports (prompts unless --force)
portkill 3000 8080

# Range (inclusive, max 4096 ports per range token)
portkill 9000-9002

# Local web UI — same logic as the CLI
portkill --gui

Press Ctrl+C to stop the GUI server. The printed URL is loopback-only. Video: GUI Demo.

CLI Flags (Short)

| Flag | Meaning | | --- | --- | | -n, --dry-run | Show targets only; do not send signals | | -f, --force | Skip the terminal confirmation | | -s, --signal | Signal to send (default SIGTERM) | | -l, --list | List all TCP listeners | | --gui | Open the local web UI | | -v, --verbose | More detail on stderr |

Full reference: CLI reference · Exit codes and outcomes: same doc.

Requirements

• Node.js ≥ 18
• macOS or Linux — uses lsof (Linux may use fuser as fallback where applicable)

Docs & Product Spec

| Doc | What it is | | --- | --- | | AGENTS | Start here — doc map, rules, and links for contributors & AI agents | | PRD | Product requirements & shipped scope | | Implementation | Architecture & data flow | | Testing strategy | Vitest mocks, coverage, test file map | | Data dictionary | Types, GUI API shapes | | Security notes | GUI scope, npm audit, reporting | | Release | npm publish (2FA), tags, GitHub Release | | Contributing | Fork, branch, tests, PR expectations | | Code of Conduct | Community standards (Contributor Covenant 2.0) |

Development

npm run build
npm test
npm run test:coverage
npm run lint

Terminal colors use chalk; set NO_COLOR=1 to disable (no-color.org).

License

MIT — see LICENSE.