⚡ ports

Beautiful port manager CLI — because netstat -ano | findstr :3000 is a crime against developer experience.

See what's running. Kill by port. Scan ranges. Find free ports. All with colors and sanity.

Install

npm install -g @dprrwt/ports

Or use without installing:

npx @dprrwt/ports

Usage

List all listening ports

ports

  ⚡ ports — what's running on your machine

  Listening Ports
┌──────────────────────┬───────┬───────┬──────────┬───────────┬───────────┐
│ Port                 │ Proto │ PID   │ Process  │ State     │ Address   │
├──────────────────────┼───────┼───────┼──────────┼───────────┼───────────┤
│ 3000 (Dev Server)    │ TCP   │ 12345 │ node     │ LISTENING │ 0.0.0.0   │
├──────────────────────┼───────┼───────┼──────────┼───────────┼───────────┤
│ 5432 (PostgreSQL)    │ TCP   │ 6789  │ postgres │ LISTENING │ 127.0.0.1 │
├──────────────────────┼───────┼───────┼──────────┼───────────┼───────────┤
│ 8080 (HTTP Alt)      │ TCP   │ 4567  │ java     │ LISTENING │ 0.0.0.0   │
└──────────────────────┴───────┴───────┴──────────┴───────────┴───────────┘
  3 ports found

  Legend:
    ■ JS Runtime  ■ Python  ■ Java  ■ Container  ■ Database  ■ System  ■ Unknown

Check a specific port

ports 3000
# or
ports check 3000

  Port 3000 (Dev Server)

  Process:  node (PID 12345)
  Proto:    TCP
  State:    LISTENING
  Address:  0.0.0.0:3000

Kill a process by port

ports kill 3000           # asks for confirmation
ports kill 3000 --yes     # skip confirmation
ports kill 3000 -f --yes  # force kill (SIGKILL)

Scan a port range

ports scan 3000-4000

  Scanning ports 3000-4000
  2 in use  ·  999 free  ·  1001 total

┌──────┬───────┬──────┬─────────┬───────────┬─────────┐
│ Port │ Proto │ PID  │ Process │ State     │ Address │
├──────┼───────┼──────┼─────────┼───────────┼─────────┤
│ 3000 │ TCP   │ 1234 │ node    │ LISTENING │ 0.0.0.0 │
├──────┼───────┼──────┼─────────┼───────────┼─────────┤
│ 3306 │ TCP   │ 5678 │ mysqld  │ LISTENING │ 0.0.0.0 │
└──────┴───────┴──────┴─────────┴───────────┴─────────┘

Find next free port

ports free         # starts from 3000
ports free 8000    # starts from 8000

  ✓ Next free port: 3000

Features

• 🎨 Color-coded processes — JS runtimes (green), Python (blue), Java (yellow), databases (magenta), system (gray), unknown (red)
• 🏷️ Smart port labels — recognizes 30+ common ports (PostgreSQL, Redis, Vite, Django, etc.)
• 🛡️ Safety warnings — warns before killing critical processes
• 📊 JSON output — --json flag on any command for scripting
• 🖥️ Cross-platform — Windows (netstat) + macOS/Linux (ss/lsof)
• ⚡ Fast — process name caching, no unnecessary lookups

Options

| Flag | Description | |------|-------------| | --json | Output as JSON (works on all commands) | | --tcp | Show only TCP ports (list command) | | --udp | Show only UDP ports (list command) | | -a, --all | Show all states, not just LISTENING | | -f, --force | Force kill (SIGKILL / taskkill /F) | | -y, --yes | Skip confirmation prompts |

Programmatic API

import { getListeningPorts, isPortInUse, findFreePort, killProcess } from "@dprrwt/ports";

// Get all listening ports
const ports = getListeningPorts();

// Check if a port is in use
if (isPortInUse(3000)) {
  console.log("Port 3000 is taken!");
}

// Find next free port
const free = findFreePort(3000); // → 3001

// Kill a process
killProcess(12345, true); // force = true

Why?

Every developer has done this dance:

1. "Port 3000 is already in use"
2. Google "how to find what's using port 3000"
3. Copy-paste some arcane netstat or lsof incantation
4. Parse the output with your eyes
5. Find the PID
6. Google "how to kill process by PID"
7. Finally kill it
8. Repeat next week because you forgot the commands

ports makes this a one-liner. See what's running, kill what you need, move on with your life.

License

MIT © Deepankar Rawat