.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 stillportkill.
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 opens a calm local web UI on loopback.
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
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
# Optional local UI — same logic as the CLI
portkill --gui
Press Ctrl+C to stop the GUI server. The printed URL is loopback-only.
GUI walkthrough (video)
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 usefuseras fallback where applicable)
Docs & product spec
| Doc | What it is |
|---|---|
| PRD | Product requirements, roadmap |
| Implementation | Architecture & data flow |
| Data dictionary | Types, GUI API shapes |
| Security notes | GUI scope, npm audit, reporting |
| Release |
npm publish (2FA), tags, GitHub Release |
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).
npm vs GitHub README
This file is the npm package readme for @burakboduroglu/portkill (included via package.json "files"). Distribution is npm only (npm i -g / npx). Full source, docs/, and the PRD are on GitHub; in-repo links use GitHub URLs so they work from the npm package page too.
License
MIT — see LICENSE.
Top comments (0)