> ## 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.

# toolkit ports — Inspect and Manage Local Network Ports

> toolkit ports list, kill, and analyze commands — inspect listening ports by protocol or process, terminate blocking processes, and detect port conflicts.

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**

```bash theme={null}
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**

```bash theme={null}
# 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:

```bash theme={null}
toolkit ports list --json
```

```json theme={null}
{
  "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**

```bash theme={null}
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**

```bash theme={null}
# 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
```

<Warning>
  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.
</Warning>

***

### 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**

```bash theme={null}
toolkit ports analyze [options]
```

**Options**

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

**Examples**

```bash theme={null}
# 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:

```bash theme={null}
toolkit ports analyze --json
```

```json theme={null}
{
  "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."
    }
  ]
}
```