🛠️ port-fix-cli

A Node.js CLI & library to detect busy ports and terminate processes by port number.

Designed for real-world development environments, port-fix-cli prioritizes correctness, transparency, and safety over shortcuts.

---

📚 Table of Contents

- 🛠️ port-fix-cli
- 📚 Table of Contents
- ✨ Features
- 🖥️ Platform Support
- Linux ✅ (Recommended)
- Windows ⚠️
- macOS ⚠️
- 📦 Installation
- Global installation (recommended for CLI usage)
- Local / one-time usage
- 🚀 Usage
- CLI
- List all busy ports
- Kill the process running on a specific port
- Linux + sudo (important)
- 📦 Using as a Module
- 🧠 How it works
- Busy port detection
- Process detection
- 🧑‍💻 Developer Note: Port killed but still appears busy
- Why this happens
- ⚠️ Limitations \& Notes
- 🔐 Sudo + nvm Note (Linux)
- 💬 Feedback, Issues \& Discussions
- 🗺️ Roadmap (Planned)
- 📄 License
- ✨ Author

---

✨ Features

* 🔍 Safely scan and list busy ports (no OS overload)
* 🔪 Kill processes running on a specific port
* 🧠 Intelligent PID detection

* Node.js process lookup
* Linux OS-level socket inspection fallback (ss)
* 💻 Works across Linux, macOS, and Windows
(Linux has the most complete support)
* 🧱 Usable as:

* a global CLI tool
* a local CLI via npx
* a Node.js module

---

🖥️ Platform Support

$3

* Full support
* Handles sudo
* OS-level PID detection
* Threaded runtimes (MainThread)
* Docker & IPv6 edge cases
* TCP TIME_WAIT awareness

$3

* Supported for common development use cases
* Works well with npx
* Handles typical Node.js / React / local servers
* OS-level fallback (netstat + taskkill) planned

$3

* Supported for common development use cases
* Uses Node.js process detection
* OS-level fallback (lsof) planned

---

📦 Installation

$3

``bash
npm install -g port-fix-cli
`

💡 Linux note

`bash
sudo npm install -g port-fix-cli
`

---

$3

`bash
npx port-fix-cli --list
`

⚠️ Important
npx cannot be used with sudo on systems where Node.js is installed using nvm.

---

🚀 Usage

$3

#### List all busy ports

`bash
port-check --list
`

#### Kill the process running on a specific port

`bash
port-check --kill 3000
`

---

$3

`bash
sudo env "PATH=$PATH" port-check --kill 3000
`

Required when:

* Node.js is installed via nvm
* The process is not owned by your user
* The port is bound by a system-level service

---

📦 Using as a Module

`js
const { listBusyPorts, killPort } = require("port-fix-cli");

(async () => {
await listBusyPorts([3000, 3010]);
await killPort(3000);
})();
`

---

🧠 How it works

$3

Ports are checked safely by attempting a temporary bind, avoiding massive parallel socket creation.

$3

1. Tries Node.js process lookup
2. Falls back to Linux OS socket inspection (ss)

* Detects MainThread
* Detects Docker proxy ports
* Detects IPv6 listeners

---

🧑‍💻 Developer Note: Port killed but still appears busy

`bash
sudo env "PATH=$PATH" port-check --kill 3000
🔪 Killed PID 51918 on port 3000

sudo env "PATH=$PATH" port-check --kill 3000
⚠️ Port 3000 is busy but no killable PID found.
`

$3

After a process is terminated, the OS may keep the TCP socket in TIME_WAIT state.

* The port may appear busy
* No process owns the port
* There is no PID to kill
* The kernel is safely cleaning up the socket

Verify manually (Linux):

`bash
sudo ss -tan | grep :3000
`

---

⚠️ Limitations & Notes

A port may appear busy but not killable if:

* It is exposed by Docker
* It is managed by systemd or OS services
* It requires elevated permissions
* The socket is in TIME_WAIT

port-fix-cli reports this honestly instead of failing silently.

---

🔐 Sudo + nvm Note (Linux)

If Node.js is installed using nvm, sudo will not detect node automatically.

`bash
sudo env "PATH=$PATH" port-check --kill
`

This is expected Linux behavior.

---

💬 Feedback, Issues & Discussions

This project is actively evolving, and feedback is very welcome 🙌

* 🐞 Bug reports
* 💡 Feature ideas
* 🖥️ OS-specific edge cases
* 📣 Documentation improvements

👉 Open an issue here:
https://github.com/sachinabs/port-fix-cli/issues

I’m happy to discuss design decisions, edge cases, and improvements with fellow developers.

---

🗺️ Roadmap (Planned)

* Windows OS-level fallback (netstat + taskkill)
* macOS fallback (lsof)
* port-check doctor command
* Improved UX for TIME_WAIT` detection

---

📄 License

MIT License

---

✨ Author

Created with ❤️ by
Anish Bala Sachin
👉 https://github.com/sachinabs