PortWho documentation · CLI

Command-line reference

Every argument and option of the portwho command line, with exact spellings and aliases, the --option=value form, mutually exclusive combinations and their error messages, output modes, exit codes and examples.

Product
PortWho
Section
CLI
Page
3 of 7

Synopsis

portwho [<port>] [options]

portwho --help prints this reference in short form. All diagnostics go to standard error; listings and JSON go to standard output.

Argument

Argument Meaning
<port> Only show endpoints bound to this local port (0–65535). A single-port lookup shows the detailed view by default.

Only one port can be given. The value must be a plain decimal number without sign or whitespace. Invalid values are usage errors:

Input Error
portwho 70000 or portwho http '<value>' is not a valid port (0-65535). (the value is echoed as typed)
portwho 80 443 Only one port can be specified.
portwho -1 Unknown option '-1'. (anything starting with - is read as an option)

Options

Option Aliases Meaning
--json -j Write a JSON document (schema version 1) instead of text.
--details -d One block per endpoint with path, services and signer.
--tcp Only TCP listeners.
--udp Only UDP bindings.
--ipv4 -4 Only IPv4 endpoints.
--ipv6 -6 Only IPv6 endpoints.
--pid <id> -p <id> Only endpoints owned by this process id.
--search <text> -s <text> Only endpoints whose process name, executable path, service names or signer contain <text>.
--no-signature --no-signatures Skip Authenticode verification (faster).
--help -h, -? Show the help text and exit with code 0. The parser also accepts /?, which the help text does not list.
--version Print portwho <version> and exit with code 0. The version is the assembly’s informational version.

Options and the port may appear in any order. Repeating a flag is harmless; repeating --pid or --search keeps the last value. --help takes precedence over --version, and both take precedence over everything else: nothing is enumerated.

Values: --option value and --option=value

Options that take a value accept it as the next argument or inline after =:

portwho --pid 1234
portwho --pid=1234
portwho -p 1234
portwho --search svchost
portwho --search="Remote Procedure"

The = form works only with long (--) options. -p=1234 is reported as Unknown option '-p=1234'.

Value errors:

Input Error
portwho --pid (no value) Option '--pid' requires a value. (the option is echoed as typed, so -p gives Option '-p' requires a value.)
portwho --pid abc 'abc' is not a valid process id.
portwho --search "" or --search " " The search text cannot be empty.

Search text is trimmed of surrounding whitespace before use.

Mutually exclusive combinations

Combination Error
--tcp with --udp --tcp and --udp cannot be combined.
--ipv4 with --ipv6 (or -4 with -6) --ipv4 and --ipv6 cannot be combined.

The messages always use the long spellings, whichever alias was typed.

Any other unrecognized argument that starts with -, or any --name=value whose name is unknown, is reported as Unknown option '<name>'.

Usage errors

Every usage error is written to standard error in this form and ends the run with exit code 2:

portwho: --tcp and --udp cannot be combined.
Run 'portwho --help' for usage.

How the output mode is chosen

  1. --json always wins.
  2. Otherwise, --details or a <port> argument selects the details view.
  3. Otherwise, the compact table is used.

So portwho 8080 is detailed, portwho --pid 1234 is a table, and portwho 8080 --json is JSON. When nothing matches, the table and details views print No endpoints matched.; the JSON view still writes a complete document with "endpointCount": 0.

Both text views end with a summary line, 1 endpoint or <n> endpoints.

How filters are applied

  • <port>, --tcp/--udp, --ipv4/--ipv6 and --pid are applied to the raw endpoint list before any process is inspected, so a narrow query inspects only the processes that matter.
  • --search needs process information and is applied afterwards. It is a case-insensitive substring match against the process name, the executable path, each service’s key name and display name, and the signer name (the common name on the signing certificate, not the organization). With --no-signature the signer is unknown, so a search can only match through the other fields.
  • Each process is inspected once per run no matter how many endpoints it owns.

Results are sorted by port, then protocol (TCP before UDP), then address family (IPv4 before IPv6), then address, then PID. The order is the same in every output mode.

Warnings

If the service control manager cannot be queried, PortWho continues with empty service lists and prints one warning to standard error:

portwho: warning: service names are unavailable: <Windows error text>

Exit codes

Code Meaning
0 At least one endpoint was listed.
1 No endpoint matched.
2 Invalid command line.
3 Enumeration failed (portwho: could not enumerate endpoints: ...), the run was cancelled with Ctrl+C (portwho: cancelled.), or PortWho is not running on Windows.

Examples

# Everything, as a table
portwho

# Who owns port 8080? (details view)
portwho 8080

# Same answer as JSON, for a script
portwho 8080 --json

# UDP over IPv4 only
portwho --udp -4

# Every endpoint of one process
portwho --pid 1234

# Endpoints whose process, path, service or signer mentions "svchost"
portwho --search svchost

# All TCP listeners with full details, without signature checks
portwho --tcp --details --no-signature

# Endpoints whose executable path contains "\node.exe"
portwho --tcp --search "\node.exe"

Related: JSON output, Troubleshooting.