Command line
Without flags portop opens the table. Every other mode prints and exits, so it fits in scripts, cron jobs and CI.
Flags
| Flag | Meaning |
|---|
portop [WORDS] | Open the table filtered on the words: portop 8080, portop nginx 443 |
--listen | Listening sockets only: TCP LISTEN and bound UDP |
--json | Print one snapshot as JSON and exit |
--wait PORT[/udp] | Wait until something listens on the port (scripting) |
--free PORT[/udp] | Stop whatever listens on the port; --force, --yes |
--timeout DURATION | How long --wait (default 30s) or --free (default 5s) waits |
--save-baseline, --diff | Record the listening ports, or compare with the record (baseline drift) |
--compose DIR | Audit a Docker Compose project's published ports (Compose audit) |
--web | Serve the web dashboard |
--watch-new | Desktop notification when a new port starts listening |
--interval DURATION | Table refresh interval (default 2s) |
--no-dns, --no-systemd, --no-docker, --no-firewall, --no-traffic | Skip that information |
--config FILE, --init-config | Use another configuration file; write a commented one |
--baseline-path FILE | Use another baseline file |
--inspect-pid N | Print a process's details as JSON |
--signal-pid N --expected-start TIME | Signal a process only if its start time still matches; --force for SIGKILL |
--version | Print the version |
JSON output
portop --json --listen | jq '.[] | select(.scope == "all") | {port: .local_port, process, firewall}'
Each row is an object with these fields; fields marked optional are left out when unknown.
| Field | Type | Meaning |
|---|
protocol | string | TCP or UDP |
local_address, local_port | string, number | Bind address and port |
remote_address, remote_port, remote_host | optional | Peer and its reverse-DNS name |
state | string | TCP state, or UNCONN for a bound UDP socket |
ipv6 | boolean | Read from an IPv6 table |
scope | string | all, address or loopback |
pid, process, user | optional | Owner; names are raw, not sanitized |
workers | optional array | Other processes holding the socket |
systemd_unit, container | optional | Unit or Windows service, and container |
firewall | optional | allowed, restricted or blocked |
rx_bytes, tx_bytes | optional | Bytes received and sent by an established TCP connection |
rx_bytes_per_second, tx_bytes_per_second | optional | Rates; need two samples, so they appear in the dashboard's /api/ports |
cpu_percent | number | CPU use; also needs two samples |
Exit codes
| Code | Meaning |
|---|
0 | Success; --diff found no change; --compose found every fixed port as expected |
1 | Error; --wait timed out; --free could not free the port |
2 | Invalid flags |
3 | --diff found changes; --compose found an unused or conflicting port |
portop