portpeek

A tiny Linux CLI for inspecting listening ports and the processes using them.

$ ./portpeek.sh

PORT    PROTO   PID       PROCESS              USER
22      tcp     842       sshd                 root
3000    tcp     9281      node                 nihitdev
5173    tcp     9342      vite                 nihitdev
8080    tcp     7132      docker-proxy         root

No giant framework. No daemon. Just a quick view of what's listening on your machine.

Features

• Show listening TCP and UDP ports
• Display the PID, process name, and owner when available
• Use - when process details are hidden by permissions
• Filter by a specific port
• Filter TCP or UDP sockets
• Always show numeric ports
• Clean terminal-friendly output with automatic color detection
• Report missing dependencies and socket-inspection failures clearly
• Uses standard Linux networking tools
• Zero installation required

Requirements

portpeek uses ss, which is provided by iproute2 on most Linux distributions.

Check whether it is available:

command -v ss

Arch Linux / CachyOS:

sudo pacman -S iproute2

Debian / Ubuntu:

sudo apt install iproute2

Fedora:

sudo dnf install iproute

Usage

./portpeek.sh [OPTIONS] [PORT]

PORT must be a number from 1 through 65535. Only one port may be supplied.

Show listening ports:

./portpeek.sh

Inspect a specific port:

./portpeek.sh 5173

Show TCP only:

./portpeek.sh --tcp

Show UDP only:

./portpeek.sh --udp

Disable terminal colors explicitly:

./portpeek.sh --no-color

Colors are also disabled automatically when output is redirected or piped, or when the NO_COLOR environment variable is set.

Show the version:

./portpeek.sh --version

Show help:

./portpeek.sh --help

Short forms -h and -v are also supported for help and version output.

--tcp and --udp are mutually exclusive. Invalid options, invalid ports, missing dependencies, and failures from ss return a non-zero exit status.

Zero-install usage

You can also run it directly:

curl -fsSL https://raw.githubusercontent.com/nihitdev/portpeek/main/portpeek.sh | bash

Filter a port through the zero-install version:

curl -fsSL https://raw.githubusercontent.com/nihitdev/portpeek/main/portpeek.sh | bash -s -- 5173

Piping a mutable remote script directly to a shell requires trusting the current contents of that URL. For a reviewable workflow, download the script first, inspect it, and then run the local copy.

Examples

./portpeek.sh
./portpeek.sh 22
./portpeek.sh 5173
./portpeek.sh --tcp
./portpeek.sh --udp
./portpeek.sh --no-color
./portpeek.sh --help
./portpeek.sh --version

Development

The test suite uses temporary directories and mock ss/ps commands, so it does not inspect or modify the host system:

bash -n portpeek.sh tests/test-portpeek.sh
./tests/test-portpeek.sh
git diff --check

GitHub Actions runs the same syntax, behavior, and whitespace checks on pushes and pull requests.

Why?

Sometimes you just want to know:

what is using port 5173?

without remembering a longer ss, lsof, or netstat command.

portpeek is meant to make that check quick.

License

MIT