system · Command reference

`qzx inspectPort`

What it does

Checks if a port is in use, lists details of the process using it, and can optionally terminate it

Canonical command: inspectPort

Accepted aliases: None

Case-sensitive: no

Included in the published package

Available in PyPI 0.2.2.0.2. This page documents the 0.2.2.0.2 alpha development checkout.

Safety and effects

Can mutate state

No documented dry-run parameter

May invoke native programs

No documented network use

Outcome may depend on permissions

Read-only inspection needs no approval. Terminating a process requires --dangerously-bypass-approvals-and-sandbox or --yolo.

High-risk execution requires --dangerously-bypass-approvals-and-sandbox or --yolo.

This safety classification was reviewed against implementation digest sha256:114b9802f7996537b3b1d181388a1489007fc86f7f78cb8bb4753a09cdc5349c on 2026-07-25.

Exact syntax

qzx inspectPort <port> [kill] --json

Parameters

Name	Type	Required	Default	Description
port	int	Yes	Not declared	Port number to inspect
kill	bool	No	false	Whether to terminate the process utilizing this port (true/false)

Input examples

qzx inspectPort 3000

Check what is listening on port 3000

qzx inspectPort 3000 true --yolo

Terminate the process when no restorable filesystem target exists

For the complete structured payload, add --json: qzx inspectPort <port> [kill] --json

Representative output example

This illustrative JSON is derived from the current implementation-backed result contract. It shows what the command can return without claiming a recorded execution; values vary with inputs, host, permissions, and optional tools.

Example command: qzx inspectPort 3000 --json

{
    "success": true,
    "message": "Checks if a port is in use, lists details of the process using it, and can optionally terminate it. In this illustrative example, the command completed successfully.",
    "errors": [],
    "in_use": true,
    "killed": true,
    "killed_pids": [
        {
            "name": "example",
            "status": "ok"
        }
    ],
    "port": 443,
    "processes": [
        {
            "pid": 4210,
            "name": "python",
            "cpu_percent": 4.2,
            "memory_readable": "82.4 MiB"
        }
    ]
}

View the JSON result contract

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "error": {
            "type": "string"
        },
        "errors": [],
        "in_use": {
            "type": "boolean"
        },
        "killed": {
            "type": "boolean"
        },
        "killed_pids": [],
        "port": [],
        "processes": []
    },
    "additionalProperties": true
}

Errors and limits

The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.

QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.

Evidence workflow: requires a controlled privileged environment.

Evidence and provenance

Implementation: src/qzx/commands/system/inspect_port.py
Tests: tests/test_system_commands/test_inspect_port.py
Documentation channel: Development documentation 0.2.2.0.2 · main · sha256:319b16857a87636ebc3b89734cc040a737bb56194464fca33ce73bdae2043096
Availability: 0.2.2.0.2 or earlier

Keep exploring

These commands also belong to the system category. Compare them to choose the operation that best fits your task.

Explore all QZX commands