🛠️ 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

Linux ✅ (Recommended)

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

Windows ⚠️

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

macOS ⚠️

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

📦 Installation

Global installation (recommended for CLI usage)

npm install -g port-fix-cli

💡 Linux note

sudo npm install -g port-fix-cli

Local / one-time usage

npx port-fix-cli --list

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

🚀 Usage

CLI

List all busy ports

port-check --list

Kill the process running on a specific port

port-check --kill 3000

Linux + sudo (important)

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

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

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

🧠 How it works

Busy port detection

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

Process detection

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

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.

Why this happens

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):

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.

sudo env "PATH=$PATH" port-check --kill <port>

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