toolkit ports — Inspect and Manage Local Network Ports

The toolkit ports command group lets you audit and control the network ports active on your local machine. It exposes three subcommands: list to display all currently listening ports with their associated process metadata, kill to terminate a blocking process by port number or PID, and analyze to run a diagnostic scan that surfaces port collisions and standard-service misconfigurations.

toolkit ports list

Display every network port that is currently listening, along with the protocol, local address, PID, process name, and resolved service name for each entry. Use the filter flags to narrow results by search term or protocol. Syntax

toolkit ports list [options]

Options

Option	Type	Default	Description
`-s, --search <term>`	`string`	—	Filter results by port number, PID, process name, or service name.
`-p, --protocol <proto>`	`string`	—	Filter by network protocol. Accepted values: `TCP` or `UDP`.
`--json`	`boolean`	`false`	Emit output as structured JSON for use in scripts and CI/CD pipelines.

Examples

# List all active listening ports
toolkit ports list

# Filter by process name — show only ports held by Node.js processes
toolkit ports list --search node

# Filter by service name — show only HTTP-related entries
toolkit ports list --search http

# Restrict output to UDP ports only
toolkit ports list --protocol UDP

# Emit structured JSON output for programmatic consumption
toolkit ports list --json

JSON output When you pass --json, the command writes a structured object to stdout:

toolkit ports list --json

{
  "total": 2,
  "ports": [
    {
      "protocol": "TCP",
      "localAddress": "0.0.0.0",
      "localPort": 3000,
      "pid": 18420,
      "process": { "name": "node" },
      "commonService": "http-alt",
      "isProtected": false
    },
    {
      "protocol": "TCP",
      "localAddress": "0.0.0.0",
      "localPort": 22,
      "pid": 1024,
      "process": { "name": "sshd" },
      "commonService": "ssh",
      "isProtected": true
    }
  ]
}

toolkit ports kill

Terminate the process that is listening on a given port number, or kill a process directly by its PID. By default the kill is immediate and forceful (SIGKILL on Unix, taskkill /f on Windows). Syntax

toolkit ports kill <target> [options]

Arguments

Argument	Type	Required	Description
`<target>`	`number`	Yes	The port number or PID of the process to terminate.

Options

Option	Type	Default	Description
`--by-pid`	`boolean`	`false`	Treat `<target>` as a process ID (PID) instead of a port number.
`--force`	`boolean`	`true`	Force immediate termination without a graceful shutdown attempt.
`--json`	`boolean`	`false`	Emit the operation result as JSON.

Examples

# Kill the process listening on port 3000
toolkit ports kill 3000

# Kill a process directly by its PID (16205)
toolkit ports kill 16205 --by-pid

# Kill port 8080 and receive a JSON response
toolkit ports kill 8080 --json

Toolkit will refuse to kill protected system ports (e.g., port 22/SSH, 53/DNS). This is intentional — terminating these ports can destabilize your system’s networking.

toolkit ports analyze

Run a full network diagnostic to detect port collisions (multiple processes competing for the same port), standard-service misconfigurations (a process occupying a well-known port it shouldn’t own), and other port-health issues. Each conflict is reported with a severity level and a recommended remediation step. Syntax

toolkit ports analyze [options]

Options

Option	Type	Default	Description
`--json`	`boolean`	`false`	Emit the full analysis report and recommendations as JSON.

Examples

# Run a port conflict and integrity diagnostic
toolkit ports analyze

# Output the full report as JSON for automated integrations
toolkit ports analyze --json

JSON output When you pass --json, the command writes a structured conflict report to stdout:

toolkit ports analyze --json

{
  "totalConflicts": 1,
  "conflicts": [
    {
      "port": 8080,
      "service": "http-alt",
      "severity": "high",
      "processNames": ["nginx", "node"],
      "pids": [2201, 18420],
      "recommendation": "Only one process should bind to port 8080. Stop or reconfigure one of the conflicting services."
    }
  ]
}

​toolkit ports list

​toolkit ports kill

​toolkit ports analyze

toolkit ports list

toolkit ports kill

toolkit ports analyze