> ## Documentation Index > Fetch the complete documentation index at: https://toolkit.astralsolutions.tech/llms.txt > Use this file to discover all available pages before exploring further. # Port Inspection and Process Management with Toolkit > Inspect listening ports, identify processes by PID, detect conflicts, and safely terminate them — with safeguards for critical system ports. The Toolkit ports module gives you a real-time window into every network port your machine is listening on. You can identify which process owns a port, find conflicts before they cause headaches, and kill blocking processes — all from one command. A built-in safety barrier prevents you from accidentally terminating system-critical services like SSH (port 22) or DNS (port 53), so you can work with confidence. All port commands are also available in the **Web Dashboard** (`toolkit ui`), where you get a live, auto-refreshing table of ports alongside one-click process termination. *** ## `toolkit ports list` List every active listening port on your machine — including protocol (TCP/UDP), the owning process name and PID, local and remote addresses, connection state, and whether the port is known to a common service (e.g., `http`, `postgres`). ```bash theme={null} # List all listening ports toolkit ports list # Filter by process name or port number toolkit ports list --search node # Show only UDP ports toolkit ports list --protocol udp # Combine filters and output as JSON toolkit ports list --search postgres --protocol tcp --json ``` | Flag | Type | Default | Description | | ------------------------ | --------- | ------- | ---------------------------------------------------------- | | `-s, --search ` | `string` | — | Filter by port number, PID, process name, or service name. | | `-p, --protocol ` | `string` | — | Filter by protocol: `tcp` or `udp` (case-insensitive). | | `--json` | `boolean` | `false` | Emit structured JSON output. | **Example terminal output:** ``` PROTO LOCAL ADDRESS PORT PID PROCESS SERVICE ───────────────────────────────────────────────────────────────────────────────────── TCP 127.0.0.1 3000 18421 node - TCP 127.0.0.1 5432 902 postgres postgres TCP 0.0.0.0 22 1 sshd ssh UDP 0.0.0.0 53 533 systemd-resolve dns TCP 127.0.0.1 8080 21034 python3 http-alt ``` *** ## `toolkit ports kill ` Terminate the process bound to a specific port number or, with `--by-pid`, a specific process ID. Toolkit sends `SIGKILL` on Unix or invokes `taskkill /f` on Windows for an immediate, reliable termination. ```bash theme={null} # Kill the process listening on port 3000 toolkit ports kill 3000 # Kill a process directly by its PID toolkit ports kill 18421 --by-pid # Get a structured JSON response confirming the kill toolkit ports kill 8080 --json ``` | Flag | Type | Default | Description | | ---------- | --------- | ------- | ------------------------------------------------------ | | `--by-pid` | `boolean` | `false` | Treat `` as a PID instead of a port number. | | `--force` | `boolean` | `true` | Force immediate termination (SIGKILL / `taskkill /f`). | | `--json` | `boolean` | `false` | Emit the operation result as JSON. | **Safety barrier — protected system ports.** Toolkit refuses to kill processes bound to well-known system ports such as **22 (SSH)**, **53 (DNS)**, and **443 (HTTPS)**. These ports are marked `isProtected: true` in the port registry. Attempting to kill them returns an error rather than silently skipping — so you always know when a kill was blocked and why. This prevents accidental disruption of critical OS services. *** ## `toolkit ports analyze` Run a full diagnostic of your local network state. Toolkit scans every listening port, cross-references expected service mappings, and surfaces: * **Port conflicts** — multiple processes competing for the same port * **Port collisions** — a process bound to a port already claimed by another service type * **Misaligned standard services** — e.g., a non-HTTP process listening on port 80 Each finding is returned with a `severity` (`low` / `medium` / `high`) and a concrete `recommendation`. ```bash theme={null} # Run the network diagnostic toolkit ports analyze # Machine-readable output for CI/CD pipelines toolkit ports analyze --json ``` | Flag | Type | Default | Description | | -------- | --------- | ------- | ------------------------------------------------- | | `--json` | `boolean` | `false` | Emit the full analysis report as structured JSON. | *** ## `--json` Output Pass `--json` to any ports command to get machine-readable output suitable for scripting, CI pipelines, or AI agents. **`toolkit ports list --json`** emits a `total` count alongside the `ports` array: ```bash theme={null} toolkit ports list --json ``` ```json theme={null} { "total": 2, "ports": [ { "protocol": "TCP", "localAddress": "127.0.0.1", "localPort": 3000, "foreignAddress": "0.0.0.0", "foreignPort": 0, "state": "LISTEN", "pid": 18421, "process": { "pid": 18421, "name": "node", "commandLine": "node server.js", "user": "alice", "memoryMb": 112 }, "commonService": null, "isProtected": false }, { "protocol": "TCP", "localAddress": "0.0.0.0", "localPort": 22, "foreignAddress": "0.0.0.0", "foreignPort": 0, "state": "LISTEN", "pid": 1, "process": { "pid": 1, "name": "sshd", "commandLine": "/usr/sbin/sshd -D", "user": "root", "memoryMb": 4 }, "commonService": "ssh", "isProtected": true } ] } ``` **`toolkit ports kill --json`** emits an array of `KillResult` objects (one per matching process): ```bash theme={null} toolkit ports kill 3000 --json ``` ```json theme={null} [ { "success": true, "pid": 18421, "port": 3000, "message": "Process 18421 (node) on port 3000 terminated successfully." } ] ``` **`toolkit ports analyze --json`** emits a `totalConflicts` count alongside the `conflicts` array: ```bash theme={null} toolkit ports analyze --json ``` ```json theme={null} { "totalConflicts": 1, "conflicts": [ { "port": 80, "service": "http", "pids": [21034, 21100], "processNames": ["python3", "nginx"], "severity": "high", "recommendation": "Only one process should bind port 80. Stop the conflicting service or change its port." } ] } ```