Port Inspector

Interactive cross-platform CLI to inspect every open/listening port, the process behind it, and which Node.js project each one belongs to.

Türkçe açıklama aşağıda — Türkçe.

Find out what is running on which port, jump straight to the owning process and project, and kill it — all from an interactive terminal UI. Works on Windows, macOS and Linux.

Features

• 🔎 Lists all listening (and optionally established) TCP/UDP ports with the owning PID, executable and command line.
• 🟢 Detects Node / Bun / Deno processes and resolves the real project (package.json name + directory), skipping node_modules.
• 🛠 Labels 40+ common dev servers/tools: Vite, Next.js, NestJS, Nuxt, Angular, SvelteKit, Astro, Remix, Gatsby, Expo, Electron, Hardhat, Prisma, Drizzle, Strapi, Supabase, Fastify, Apollo, Storybook, Vitest, Jest, nodemon, tsx…
• ⌨️ Interactive TUI: navigate, view details, live search, sort, and act on a process by its port.
• 🛑 Graceful kill: SIGTERM first, auto-escalate to SIGKILL if it doesn't exit — or force-kill on demand.
• 🚀 Quick actions: open the project folder, open it in your editor, or copy the command line to the clipboard.
• 🔁 Live auto-refresh.
• 🤖 --json output for scripting.

How it works

No fragile netstat text parsing — it reads structured data per platform:

| OS | Source | |----|--------| | Windows | Get-NetTCPConnection / Get-NetUDPEndpoint + Get-CimInstance Win32_Process (via PowerShell, JSON) | | macOS | lsof + ps + lsof -d cwd | | Linux | lsof + /proc/<pid>/{cmdline,exe,cwd} (real working directory) |

Requirements

• Node.js 20+
• Windows: PowerShell (pwsh 7+ preferred, falls back to built-in powershell.exe)
• macOS: works out of the box (lsof is preinstalled)
• Linux: lsof (sudo apt install lsof / sudo dnf install lsof)

Install

Run without installing

npx port-inspector            # once published to npm

From source (any machine)

git clone https://github.com/mertokan/port-inspector.git
cd port-inspector
npm install
npm link                      # makes the global `ports` command available

After npm link you can run ports from any terminal, any directory. (Run npm unlink -g port-inspector to remove it.)

Tip: instead of npm link you can also npm install -g . from the project folder.

Usage

ports                  # interactive live panel (default)
ports -n               # only Node/Bun/Deno projects
ports --once -p 3000   # who is holding port 3000? (print once and exit)
ports --once -a        # include established connections, not just listeners
ports --json > ports.json

If you didn't run npm link, use node bin/ports.mjs … instead of ports ….

Options

| Option | Description | |---|---| | (none) | Interactive live TUI (default when run in a terminal) | | -o, --once | Print the table once and exit | | --json | Print result as JSON (for scripting) | | -a, --all | Include Established connections, not only listeners | | -n, --node | Show only Node/Bun/Deno processes | | -p, --port <n> | Filter by a specific port | | -i, --interval <s> | Refresh interval in interactive mode (default: 3) | | -h, --help | Help |

Interactive shortcuts

| Key | Action | |---|---| | ↑/↓ or j/k | Move selection | | Enter / d | Toggle detail panel | | x / Del | Kill selected process → e graceful (TERM→KILL) · f force · h cancel | | / | Live search | | s | Cycle sort (port → pid → project → process → proto) | | o | Open the project folder | | e | Open the project in your editor (code / $EDITOR) | | c | Copy the command line to the clipboard | | a | Toggle all connections | | n | Toggle Node-only | | r | Refresh now | | q | Quit |

Clipboard on Linux needs xclip or wl-copy; open folder needs xdg-open.

Development

npm test     # run the unit tests (node:test, no extra deps)

License

MIT — use it however you like.

Türkçe

Port Inspector, bilgisayardaki açık/dinlenen tüm portları, her portun arkasındaki süreci ve özellikle hangi Node.js projesine ait olduğunu gösteren, çapraz platform (Windows, macOS, Linux) interaktif bir terminal aracıdır.

Öne çıkanlar

• Tüm dinlenen (ve istenirse kurulu) TCP/UDP portları; PID, çalıştırılabilir ve komut satırı ile.
• Node / Bun / Deno süreçlerini tanır, node_modules'ü atlayıp gerçek projeyi (package.json adı + dizini) bulur.
• 40+ bilinen dev sunucusunu/aracını etiketler (Vite, Next.js, NestJS, SvelteKit, Hardhat, Prisma, Strapi, Supabase, Fastify, Expo, Electron, nodemon…).
• İnteraktif arayüz: ok tuşlarıyla gezin, detay gör, canlı ara, sırala ve süreç üzerinde eylem yap.
• Nazik kapatma: önce SIGTERM, kapanmazsa otomatik SIGKILL — ya da istersen doğrudan zorla.
• Hızlı eylemler: proje klasörünü aç, editörde aç, komut satırını panoya kopyala.
• Canlı otomatik yenileme + script için --json.

Kurulum (her makinede)

git clone https://github.com/mertokan/port-inspector.git
cd port-inspector
npm install
npm link        # global `ports` komutu

Artık herhangi bir terminalden ports yazman yeterli.

Gereksinimler

• Node.js 20+
• Windows: PowerShell (pwsh 7+ tercih edilir) · macOS: hazır gelir · Linux: lsof

Kullanım

ports                  # interaktif panel
ports -n               # sadece Node projeleri
ports --once -p 3000   # 3000 portunu kim tutuyor?

Kısayollar: ↑/↓ seç · Enter/d detay · x kill (e nazik · f zorla) · / ara · s sırala · o klasör · e editör · c kopyala · a tümü · n node · r yenile · q çık.

Linux'ta panoya kopyalama xclip/wl-copy, klasör açma xdg-open gerektirir.

Geliştirme

npm test     # birim testleri (node:test, ek bağımlılık yok)

Lisans: MIT — dilediğin gibi kullan.