peekport

See what's using a port — instantly.

peekport is a small, cross-platform CLI that answers a question developers ask every day:

What's using port 3000?

npx peekport 3000

peekport

Port 3000
────────────────────────────────────────────

● IN USE

PID          18472
Process      node
Command      next dev
Directory    ~/projects/my-app
User         burak

Network
────────────────────────────────────────────

Address      127.0.0.1:3000
Protocol     TCP
State        LISTENING

Actions
────────────────────────────────────────────

Kill process:
  peekport 3000 --kill

Inspect process:
  peekport 3000 --details

If nothing is listening:

peekport

Port 3000
────────────────────────────────────────────

✓ AVAILABLE

Nothing is listening on port 3000.

Why it exists

lsof, ss, netstat, and PowerShell all answer this question — if you remember the flags, the output format, and the right tool for the OS you are on.

peekport is the same lookup with a consistent interface on Windows, macOS, and Linux.

Installation

npm install -g peekport

Or run it without installing:

npx peekport 3000

Requires Node.js 18 or newer.

Quick start

peekport 3000
peekport 3000 --details
peekport 3000 --json
peekport 3000 --kill

Multiple ports

peekport 3000 5173 8080

PORT     STATUS       PROCESS    PID
────────────────────────────────────────
3000     IN USE       node       18472
5173     IN USE       vite       21842
8080     AVAILABLE    —          —

Port ranges

peekport 3000-3010

Ranges are expanded locally. The OS is queried once, not once per port.

--kill

peekport 3000 --kill

peekport never kills a process unless you ask it to. Before terminating, it shows the PID, process name, and command line and asks:

Continue? [y/N]

For scripts:

peekport 3000 --kill --yes

Graceful termination is attempted first. If the process does not exit:

peekport 3000 --kill --force

Force termination can cause data loss. Only the exact PID discovered from the port lookup is targeted.

--details

peekport 3000 --details

Shows expanded process and socket information when the operating system exposes it: executable, command line, working directory, user, local/remote addresses, and TCP state.

Fields that are not available are shown as Unknown or omitted.

--json

peekport 3000 --json

Machine-readable JSON with no colors and no ANSI escape codes.

{
  "port": 3000,
  "protocol": "tcp",
  "status": "listening",
  "processes": [
    {
      "pid": 18472,
      "name": "node",
      "command": "next dev",
      "workingDirectory": "/projects/app"
    }
  ]
}

Multiple ports produce a JSON array.

--check and --ci

peekport 3000 --check
peekport 3000 --ci

--check prints a one-line availability result. --ci prints a script-friendly report and ends with PASS or FAIL.

Both exit with a non-zero status when the port is occupied, so they work in shell scripts and CI jobs.

peekport 3000 --check && npm start

--tree

peekport 3000 --tree

When parent process information is available:

node (18472)
└─ npm (18451)
   └─ shell (18442)

Relationships are never invented. If the parent chain cannot be read, that part is omitted.

Cross-platform behavior

| Platform | Lookup | Process details | | --- | --- | --- | | Linux | ss, then lsof, then netstat | /proc | | macOS | lsof, then netstat | ps / lsof | | Windows | netstat -ano, then Get-NetTCPConnection | Get-CimInstance / tasklist |

Platform-specific commands are isolated behind a single inspector abstraction. Missing optional tools degrade the amount of detail — they do not crash the lookup.

IPv4 and IPv6 listeners are both reported (127.0.0.1, 0.0.0.0, ::1, ::).

Permissions

Some operating systems hide process ownership for sockets you do not own. peekport still reports that the port is in use and explains when details are unavailable.

It does not tell you to re-run the entire tool as administrator or root unless that is actually required.

Security

peekport is local-only. It does not send system information, process information, or telemetry anywhere.

• No network requests
• No file modifications
• No automatic process termination
• Process names, paths, and command lines are treated as untrusted strings and are never executed

See SECURITY.md.

Development

npm install
npm run typecheck
npm run lint
npm test
npm run build

Testing

Unit tests parse representative ss, lsof, and netstat fixtures from Linux, macOS, and Windows so the suite is not tied to one developer machine.

Live tests bind a temporary TCP server (server.listen(0)) and verify that peekport detects it. Kill tests spawn a dedicated child process and terminate only that PID.

Contributing

See CONTRIBUTING.md.

License

MIT