GitHub - cmakafui/portdetective: A tiny, fast Rust CLI that replaces the lsof/netstat/ps incantation soup with one clear command.

🔎 Port Detective

What's running on this port, and how do I safely kill it?

Port Detective is a tiny, fast Rust CLI that replaces the lsof/netstat/ps incantation soup with one clear command.

Platform Support

Linux (x86_64 glibc and musl)
macOS (Intel and Apple Silicon)
~~Windows~~ (not yet supported due to Unix-only dependencies)

Installation

Using Cargo (Recommended)

cargo install portdetective

Download pre-built binaries

Download the latest release for your platform from the releases page:

# Linux (glibc)
curl -L https://github.com/cmakafui/portdetective/releases/latest/download/portdetective-linux-x86_64.tar.gz | tar xz
sudo mv portdetective /usr/local/bin/

# Linux (musl - static binary, no dependencies)
curl -L https://github.com/cmakafui/portdetective/releases/latest/download/portdetective-linux-x86_64-musl.tar.gz | tar xz
sudo mv portdetective /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/cmakafui/portdetective/releases/latest/download/portdetective-macos-x86_64.tar.gz | tar xz
sudo mv portdetective /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/cmakafui/portdetective/releases/latest/download/portdetective-macos-aarch64.tar.gz | tar xz
sudo mv portdetective /usr/local/bin/

Build from source

git clone https://github.com/cmakafui/portdetective.git
cd portdetective
cargo install --path .

Usage

Inspect a port

🔎 Port 3000 (tcp) is in use

Process:    node
PID:        42193
User:       makafui
Command:    node server.js --port=3000
CWD:        /Users/makafui/projects/my-app
Parent:     zsh (PID 41200)
Started:    2025-11-18 14:32:10

Suggested kill:
  kill 42193
  # or force if needed:
  kill -9 42193

Check if a port is free

✅ Port 55555 is free (no listening process found)

List all listening ports

PORT    PROTO  PID      PROCESS      USER       COMMAND
3000    tcp    42193    node         makafui    node server.js --port=3000
5432    tcp    550      postgres     postgres   /usr/local/bin/postgres -D ...
8000    tcp    43011    python       makafui    uvicorn main:app --port 8000

📊 3 listening port(s) found

Kill process on a port

Interactive confirmation:

🔎 Port 3000 (tcp) is in use by:
  node (PID 42193)
  Command: node server.js --port=3000
  CWD:     /Users/makafui/projects/my-app

Are you sure you want to kill PID 42193? [y/N]:

Commands & Aliases

Command	Aliases	Description
`portdetective <PORT>`	—	Inspect a port (shorthand)
`portdetective inspect <PORT>`	`i`	Inspect what's on a port
`portdetective list`	`l`, `ls`	List all listening ports
`portdetective kill <PORT>`	`k`	Kill process on a port

Flags

Flag	Short	Description
`--json`	`-j`	Output as JSON
`--tcp`	—	Only show TCP connections
`--udp`	—	Only show UDP connections
`--force`	`-f`	Send SIGKILL instead of SIGTERM (kill)
`--no-prompt`	`-y`	Skip confirmation prompt (kill)

JSON output

portdetective 3000 --json

{
  "port": 3000,
  "protocol": "tcp",
  "status": "in_use",
  "processes": [
    {
      "pid": 42193,
      "name": "node",
      "user": "makafui",
      "command": ["node", "server.js", "--port=3000"],
      "cwd": "/Users/makafui/projects/my-app",
      "parent_pid": 41200,
      "parent_name": "zsh",
      "started": "2025-11-18T14:32:10+02:00",
      "protocol": "tcp"
    }
  ]
}

Philosophy

Sharp, boring, dependable: Does one thing well
Instant startup: No async runtime, fast binary
Human-readable by default: JSON when you need it
Safe by default: Kill requires confirmation unless scripted

License

MIT