@ropean/ports

A beautiful CLI tool to see what's running on your ports.

Stop guessing which process is hogging port 3000. @ropean/ports gives you a color-coded table of every dev server, database, and background process listening on your machine -- with framework detection, Docker container identification, and interactive process management.

What it looks like

$ ports

 ┌─────────────────────────────────────┐
 │  @ropean/ports                      │
 │  listening to your ports...         │
 └─────────────────────────────────────┘

┌───────┬─────────┬───────┬──────────────────────┬────────────┬────────┬───────────┐
│ PORT  │ PROCESS │ PID   │ PROJECT              │ FRAMEWORK  │ UPTIME │ STATUS    │
├───────┼─────────┼───────┼──────────────────────┼────────────┼────────┼───────────┤
│ :3000 │ node    │ 42872 │ frontend             │ Next.js    │ 1d 9h  │ ● healthy │
├───────┼─────────┼───────┼──────────────────────┼────────────┼────────┼───────────┤
│ :3001 │ node    │ 95380 │ preview-app          │ Next.js    │ 2h 40m │ ● healthy │
├───────┼─────────┼───────┼──────────────────────┼────────────┼────────┼───────────┤
│ :4566 │ docker  │ 58351 │ backend-localstack-1 │ LocalStack │ 10d 3h │ ● healthy │
├───────┼─────────┼───────┼──────────────────────┼────────────┼────────┼───────────┤
│ :5432 │ docker  │ 58351 │ backend-postgres-1   │ PostgreSQL │ 10d 3h │ ● healthy │
├───────┼─────────┼───────┼──────────────────────┼────────────┼────────┼───────────┤
│ :6379 │ docker  │ 58351 │ backend-redis-1      │ Redis      │ 10d 3h │ ● healthy │
└───────┴─────────┴───────┴──────────────────────┴────────────┴────────┴───────────┘

  5 ports active  ·  Run ports <number> for details  ·  --all to show everything

Colors: green = healthy, yellow = orphaned, red = zombie.

Install

npm install -g @ropean/ports

Or run it directly without installing:

npx @ropean/ports

Or let Claude Code install it for you

If you use Claude Code, you can ask it to npm install -g @ropean/ports and start using ports right away -- no setup steps needed.

Usage

Show dev server ports

ports

Shows dev servers, Docker containers, and databases. System apps (Spotify, Raycast, etc.) are filtered out by default.

Show all listening ports

ports --all

Includes system services, desktop apps, and everything else listening on your machine.

Inspect a specific port

ports 3000

Detailed view: full process tree, repository path, current git branch, memory usage, and an interactive prompt to kill the process.

Kill a process

ports kill 3000                # kill by port
ports kill 3000 5173 8080      # kill multiple
ports kill 3000-3010           # kill a port range
ports kill 42872               # kill by PID
ports kill node                # kill all listening processes named "node"
ports kill node bun            # kill all listeners matching any of these names
ports kill node 3000 42872     # mix names, ports, and PIDs
ports kill -f 3000             # force kill (SIGKILL)
ports kill -y node             # skip confirmation prompt

Resolves port to process automatically. Falls back to PID if no listener matches. Use -f when a process won't die gracefully.

Name matching is case-insensitive and exact against the process name as reported by the OS (e.g. node, bun, python3, deno). Only listening processes are considered -- non-listening processes with the same name are not touched. When more than one process is targeted, you'll be shown the list and asked to confirm. Pass -y/--yes to skip the prompt.

$ ports kill node

  About to kill 3 processes (SIGTERM):
  • :3000 — node (PID 42872)
  • :5173 — node (PID 95380)
  • :8080 — node (PID 17422)

  Proceed? [y/N] y

  ✓ Sent SIGTERM to :3000 — node (PID 42872)
  ✓ Sent SIGTERM to :5173 — node (PID 95380)
  ✓ Sent SIGTERM to :8080 — node (PID 17422)

  Summary: 3 killed

Port ranges expand into individual kills -- empty ports are silently skipped and shown as a summary:

$ ports kill -y 3000-3005

  ✓ Sent SIGTERM to :3000 — node (PID 42872)
  ✓ Sent SIGTERM to :3001 — node (PID 95380)

  Summary: 2 killed, 4 empty

View process logs

ports logs 3000               # show last 50 lines and exit
ports logs 3000 -f            # follow (stream new lines)
ports logs 3000 --lines 10    # show last 10 lines
ports logs 3000 --lines 10 -f # show last 10 then follow
ports logs 3000 --err         # stderr only

Discovers log files automatically using lsof file descriptor detection. If stdout/stderr is redirected to a file, it finds and tails it. Falls back to system log (log show on macOS, journalctl on Linux) when no log files are found.

$ ports logs 3000 --lines 5

  @ropean/ports — logs for :3000 (node, PID 42872)

  ▸ Tailing stdout: /tmp/next-dev.output

  ▲ Next.js 16.2.3 (Turbopack)
  - Local: http://localhost:3000
  ✓ Ready in 195ms
   GET / 200 in 990ms
   GET /api/auth/session 200 in 6ms

Show all dev processes

ports ps

A beautiful ps aux for developers. Shows all running dev processes (not just port-bound ones) with CPU%, memory, framework detection, and a smart description column. Docker processes are collapsed into a single summary row.

$ ports ps

┌───────┬─────────┬──────┬──────────┬──────────┬───────────┬─────────┬────────────────────────────────┐
│ PID   │ PROCESS │ CPU% │ MEM      │ PROJECT  │ FRAMEWORK │ UPTIME  │ WHAT                           │
├───────┼─────────┼──────┼──────────┼──────────┼───────────┼─────────┼────────────────────────────────┤
│ 592   │ Docker  │ 1.3  │ 735.5 MB │ —        │ Docker    │ 13d 12h │ 14 processes                   │
├───────┼─────────┼──────┼──────────┼──────────┼───────────┼─────────┼────────────────────────────────┤
│ 36664 │ python3 │ 0.2  │ 17.6 MB  │ —        │ Python    │ 6d 10h  │ browser_use.skill_cli.daemon   │
├───────┼─────────┼──────┼──────────┼──────────┼───────────┼─────────┼────────────────────────────────┤
│ 26408 │ node    │ 0.1  │ 9.2 MB   │ —        │ Node.js   │ 10d 13h │ jest jest_runner_cloud.js      │
├───────┼─────────┼──────┼──────────┼──────────┼───────────┼─────────┼────────────────────────────────┤
│ 25752 │ node    │ 0.0  │ 17.3 MB  │ —        │ Node.js   │ 10d 13h │ server.js                      │
├───────┼─────────┼──────┼──────────┼──────────┼───────────┼─────────┼────────────────────────────────┤
│ 66921 │ Python  │ 0.0  │ 4.1 MB   │ —        │ Python    │ 2h 25m  │ src.server                     │
└───────┴─────────┴──────┴──────────┴──────────┴───────────┴─────────┴────────────────────────────────┘

  5 processes  ·  --all to show everything

ports ps --all    # show all processes, not just dev

Clean up orphaned processes

ports clean

Finds and kills orphaned or zombie dev server processes. Only targets dev runtimes (node, python, etc.) -- won't touch your desktop apps.

Watch for port changes

ports watch

Real-time monitoring that notifies you whenever a port starts or stops listening.

How it works

Three shell calls, runs in ~0.2s:

1. lsof -iTCP -sTCP:LISTEN -- finds all processes listening on TCP ports
2. ps (single batched call) -- retrieves process details for all PIDs at once: command line, uptime, memory, parent PID, status
3. lsof -d cwd (single batched call) -- resolves the working directory of each process to detect the project and framework

For Docker ports, a single docker ps call maps host ports to container names and images.

Framework detection reads package.json dependencies and inspects process command lines. Recognizes Next.js, Vite, Express, Angular, Remix, Astro, Django, Rails, FastAPI, and many others. Docker images are identified as PostgreSQL, Redis, MongoDB, LocalStack, nginx, etc.

Platform support

| Platform | Status | |----------|--------| | macOS | Supported | | Linux | Supported | | Windows | Supported |

License

MIT

Credits

Forked from LarsenCundric/port-whisperer. Thanks to the original author for the foundation.