uports
A CLI tool for displaying listening TCP ports grouped by user, together with the owning process ID and command.
uports uses gopsutil to inspect network connections and processes, Cobra for CLI argument handling, and Lip Gloss for terminal styling.
Features
-
Lists TCP ports currently in the
LISTENstate -
Groups listening ports by username
-
Displays the owning process ID (PID)
-
Displays the process command line
-
Counts sockets belonging to the same PID/port combination
-
Filter results by:
- Port
- PID
- Command
- Username or UID
-
Highlights values matching active filters
-
Supports full, unwrapped command output
-
Sorts ports numerically and users alphabetically
-
Colorized terminal output for easier scanning
Installation
From source
Requires a recent version of Go.
go install <your-module-path>/uports@latest
Replace <your-module-path> with the module path used by this project.
Build locally
git clone <repository-url>
cd uports
go build -o bin/uports .
or
git clone <repository-url>
cd uports
make build
Then run:
./bin/uports
You can optionally install it somewhere in your PATH:
install uports ~/.local/bin/uports
Usage
uports [flags]
Running uports without arguments displays all listening TCP ports that the current process can inspect.
Example:
uports
Example output:
root (0)
PORT PID N COMMAND
22 812 1 /usr/sbin/sshd -D
postgres (112)
PORT PID N COMMAND
5432 1247 1 /usr/lib/postgresql/.../postgres
The exact output depends on the processes and network connections available on the system.
Options
| Flag | Short | Description |
|---|---|---|
--port |
-p |
Filter by listening TCP port |
--pid |
-i |
Filter by process ID |
--cmd |
-c |
Filter by command using a substring match |
--user |
-u |
Filter by username or UID; accepts comma-separated values |
--unwrap |
-l |
Show the full command output |
--help |
Show help | |
--version |
Show the application version |
Filtering
Filter by port
Show only processes listening on TCP port 8080:
uports --port 8080
or:
uports -p 8080
Matching ports are highlighted in the output.
Filter by PID
Show listening sockets owned by a specific process:
uports --pid 1234
or:
uports -i 1234
Filter by command
Search for a substring in the process command line:
uports --cmd nginx
This is a substring search, so it can match commands containing nginx anywhere in their command line.
For example:
uports -c postgres
Filter by user
Filter by username:
uports --user postgres
Multiple users can be supplied as a comma-separated list:
uports --user root,postgres
You can also filter by UID:
uports --user 1000
Multiple UIDs are supported:
uports -u 0,1000,1001
Usernames and UIDs can be mixed:
uports -u root,1000,postgres
Combine filters
Filters can be combined to narrow the results.
For example:
uports --port 8080 --user alice
Or:
uports --cmd nginx --port 443
When multiple filters are specified, a connection must satisfy the applicable filters to remain in the displayed results.
Full Command Output
By default, long commands are constrained to keep the table readable.
Use --unwrap (-l) to display the full command without the normal command-column width limit:
uports --unwrap
This can be particularly useful when process command lines contain long argument lists.
Output Format
Each user is displayed as a separate section:
username (UID)
PORT PID N COMMAND
Where:
- PORT — Listening TCP port
- PID — Process ID owning the socket
- N — Number of matching sockets for the same PID and port
- COMMAND — Process command line
For example:
www-data (33)
PORT PID N COMMAND
80 1520 1 /usr/sbin/nginx -g daemon off;
443 1520 1 /usr/sbin/nginx -g daemon off;
Only TCP connections whose state is LISTEN are included.
Permissions
uports relies on operating-system process and network information exposed through gopsutil. Depending on the operating system and its security configuration, some processes or command lines may not be accessible to an unprivileged user.
If information is missing, try running it with elevated privileges:
sudo uports
Use elevated privileges only when necessary.