portmanager-tui

A simple TUI to view open ports on Linux, macOS, and Windows with their processes, search them, and kill processes straight from the terminal.

Usage (local, before publishing to npm)

cd portmanager-tui
npm install
npm link          # registers the "portmanager-tui" bin globally (symlink)
npx portmanager-tui

npm link only needs to run once. After that, npx portmanager-tui will call this local version from any directory. To publish it later so npx portmanager-tui works without cloning, just npm publish (make sure the package name isn't taken).

Alternative without linking, run directly:

node bin/index.js

Controls

| Key | Action | |---|---| | ↑ / ↓ or j / k | Navigate rows | | / | Open search — type then Enter to filter (matches port, process name, PID, owner, or address), Esc to cancel | | o | Toggle: only show ports owned by your user / show all | | d | Kill selected process (SIGTERM) | | D | Force kill selected process (SIGKILL) | | r | Manual refresh | | q / Ctrl+C | Quit |

Data auto-refreshes every 4 seconds (except while typing a search).

By default only ports whose process is owned by the user running the tool are shown (compared via uid). Press o to see all ports.

Notes

• Platform support:
  • Linux — uses ss -tulnp (part of iproute2, usually installed by default on modern distros). The Owner column is read from /proc/<pid> (no ps spawn per row) and mapped to a username via /etc/passwd, so it stays cheap even with many ports.
  • macOS — uses lsof -i -P -n (preinstalled on macOS). The Owner column comes straight from lsof's USER field; the uid is resolved once per unique username via id -u and cached.
  • Windows — uses netstat -ano for the port list and Get-Process (via PowerShell) for the process name and session ID. Only listening TCP ports and UDP ports are shown (established/close-wait connections are filtered out to keep the table focused). The own-only filter identifies your processes by matching the Windows session ID (same session as the tool itself) — no admin required. Kill uses taskkill /T (tree kill), with /F for force kill.
• To see all processes (including other users / root), run with sudo (Linux/macOS) or an elevated terminal (Windows):

  sudo npx portmanager-tui

  Without elevated privileges, ports owned by other processes show PID/Process as -.

Structure

portmanager-tui/
├── bin/index.js     # entry point — UI + keybindings
├── lib/
│   ├── linux.js     # Linux data layer (ss + /proc)
│   ├── macos.js     # macOS data layer (lsof)
│   └── windows.js   # Windows data layer (netstat + Get-Process)
├── package.json
└── README.md