[maui-labs docs] Document new `maui port check` CLI command

[MauiBot]

Source PR

PR: dotnet/maui-labs#200 — feat: add maui port check command
Author: @rmarinho
Merged: 2026-06-16

---

Summary of Changes

PR #200 adds a new top-level maui port check (port) CLI subcommand to the maui global tool. The command is a cross-platform TCP port diagnostic utility that reports which process is listening on a given port number. It works on Windows (via P/Invoke GetExtendedTcpTable) and Unix/macOS (via lsof/ss/netstat fallback chain).

User-facing additions:

• New command group: maui port
• New command: maui port check (port)
• New JSON output model with --json support
• New error code E1008 (PortEnumerationFailed)

---

Documentation Pages Affected

File	Change needed
docs/developer-tools/cli/index.md (or equivalent command reference)	Add maui port command group and maui port check subcommand
docs/TOC.yml	Add entry for port command if CLI commands are individually listed

---

Suggested Changes

New section: maui port check

Add the following content to the CLI command reference under a new ## Port diagnostics section (or alongside the maui doctor / diagnostics commands):

## `maui port check`

Check which process is listening on a TCP port.

**Syntax**

```
maui port check (port) [--json]
```

**Arguments**

| Argument | Description |
|----------|-------------|
| `port`   | TCP port number to check (1–65535). |

**Options**

| Option   | Description |
|----------|-------------|
| `--json` | Output result as JSON. |

**Exit codes**

| Code | Meaning |
|------|---------|
| `0`  | Port is free — no process is listening. |
| `1`  | Port is in use — at least one process is listening. |
| `2`  | Error (invalid argument or failed to enumerate ports). |

**Text output example — port free**

```
✔ Port 8080 is free.
```

**Text output example — port in use**

```
Port 8080 is in use:
  PID 12345 (dotnet) 0.0.0.0 [ipv4]
```

**JSON output example — port in use**

```json
{
  "port": 8080,
  "in_use": true,
  "listeners": [
    {
      "pid": 12345,
      "process_name": "dotnet",
      "address": "0.0.0.0",
      "family": "ipv4",
      "state": "listen"
    }
  ]
}
```

**JSON output example — port free**

```json
{
  "port": 8080,
  "in_use": false,
  "listeners": []
}
```

**Platforms**: Windows, macOS, Linux.

**Tip**: Use the `--json` flag together with an exit-code check in scripts to detect port conflicts before starting a DevFlow agent or development server:

```bash
maui port check 19223 --json
if [ $? -eq 1 ]; then echo "Port 19223 is already taken"; fi
```

JSON schema reference (if the docs include API/output schemas)

Add PortCheckResult to any JSON output schema reference table:

Model	Properties
PortCheckResult	port (int), in_use (bool), listeners (array of PortListenerResult)
PortListenerResult	pid (int), process_name (string), address (string), family ("ipv4"|"ipv6"), state (string, default "listen")

Generated by PR Documentation Check for issue #200 · ◷