sistema · Referencia de comando

`qzx inspectPort`

Qué hace

Comprueba si un puerto local está ocupado e informa qué proceso lo posee, sin terminarlo.

Madurez del comando: Alpha

Disponible para uso real y retroalimentación mientras su interfaz y comportamiento todavía pueden evolucionar. Esta es la evaluación actual del checkout de desarrollo. Cada futuro tag inmutable de release conservará la evaluación exacta incluida en esa versión. Disponible en PyPI 0.2.2.0.15. La documentación corresponde al checkout alpha 0.2.2.0.15.

Comportamiento y protecciones integradas

Inspecciona sin cambiar el estado

Ejecución directa para esta operación

Usa una herramienta nativa cuando hace falta

Funciona sin usar la red

Usa tus permisos actuales; el resultado puede variar

inspectPort es estrictamente de solo lectura y nunca cambia el estado de los procesos.

Esta clasificación de seguridad fue revisada por Claude Opus 5.5 (Anthropic) contra el digest de implementación sha256:1d5d6e4843aec55d11027a9630f683cf24297a269475e95b6963cbe99bc8e6be el 2026-10-08.

Sintaxis exacta

qzx inspectPort <port> --json

Parámetros

Desliza o usa la barra horizontal para ver todas las columnas.

Nombre	Tipo	Obligatorio	Predeterminado	Descripción
port	int	Sí	No declarado	Número de puerto que se inspeccionará

Ejemplos de entrada

qzx inspectPort 3000

Inspeccionar el proceso que escucha en el puerto 3000 y obtener su PID y hora de creación

qzx inspectPort 5432 --json

Devolver el resultado completo y estructurado de la inspección

Para obtener la carga estructurada completa, añade --json: qzx inspectPort <port> --json

Ejemplo de salida representativa

Este JSON ilustrativo deriva del contrato de resultado respaldado por la implementación actual. Muestra lo que el comando puede devolver sin afirmar que es una ejecución grabada; los valores varían según entradas, equipo, permisos y herramientas opcionales.

Comando del ejemplo: qzx inspectPort 3000 --json

{
    "success": true,
    "message": "Checks whether a local port is bound and reports the owning process without terminating it. In this illustrative example, the command completed successfully.",
    "meta": {
        "command": "inspectPort",
        "command_maturity": {
            "stage": "alpha",
            "label": "Alpha",
            "sequence": 2,
            "public_executable": true,
            "stability": "interface_may_change",
            "summary": "Available for real use and feedback while its interface and behavior can still evolve.",
            "promotion_review_required": false,
            "assessment_scope": "development_checkout"
        },
        "duration_ms": 0,
        "schema_version": 1
    },
    "errors": [],
    "in_use": true,
    "limitations": [
        "Example value"
    ],
    "observed_pids": [
        3
    ],
    "port": 3,
    "processes": [
        {
            "pid": 4210,
            "name": "python",
            "cpu_percent": 4.2,
            "memory_readable": "82.4 MiB"
        }
    ],
    "status": "free"
}

Ver el contrato de resultado JSON

{
    "type": "object",
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "error": {
            "type": "string"
        },
        "error_code": {
            "type": "string"
        },
        "status": {
            "type": "string",
            "enum": [
                "free",
                "in_use"
            ]
        },
        "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 65535
        },
        "in_use": {
            "type": [
                "boolean",
                "null"
            ]
        },
        "observed_pids": {
            "type": "array",
            "items": {
                "type": "integer"
            }
        },
        "processes": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": true
            }
        },
        "limitations": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "errors": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "meta": {
            "type": "object",
            "required": [
                "command",
                "command_maturity",
                "duration_ms",
                "schema_version"
            ],
            "properties": {
                "command": {
                    "type": "string"
                },
                "command_maturity": {
                    "type": "object",
                    "required": [
                        "stage",
                        "label",
                        "sequence",
                        "public_executable",
                        "stability",
                        "summary",
                        "promotion_review_required",
                        "assessment_scope"
                    ],
                    "properties": {
                        "stage": {
                            "type": "string"
                        },
                        "label": {
                            "type": "string"
                        },
                        "sequence": {
                            "type": "integer"
                        },
                        "public_executable": {
                            "type": "boolean"
                        },
                        "stability": {
                            "type": "string"
                        },
                        "summary": {
                            "type": "string"
                        },
                        "promotion_review_required": {
                            "type": "boolean"
                        },
                        "assessment_scope": {
                            "type": "string"
                        },
                        "note": {
                            "type": "string"
                        },
                        "review": {
                            "type": "object",
                            "required": [
                                "reviewed_on",
                                "rationale",
                                "evidence"
                            ],
                            "properties": {
                                "reviewed_on": {
                                    "type": "string",
                                    "format": "date"
                                },
                                "rationale": {
                                    "type": "string"
                                },
                                "evidence": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "replacement": {
                                    "type": "string"
                                }
                            },
                            "additionalProperties": false
                        }
                    },
                    "additionalProperties": true
                },
                "duration_ms": {
                    "type": "number"
                },
                "schema_version": {
                    "type": "integer"
                }
            },
            "additionalProperties": true
        }
    },
    "additionalProperties": true,
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "required": [
        "message",
        "meta",
        "success"
    ]
}

Errores y límites

El contrato público exige success=false y un message descriptivo en fallos. Este catálogo aún no declara una taxonomía de errores específica para cada comando; revisa el resultado y no infieras códigos inexistentes.

QZX está en alpha. Dependencias opcionales, permisos y capacidades del host pueden cambiar el resultado.

Flujo de evidencia: requiere un entorno privilegiado controlado.

Evidencia y procedencia

Implementación: src/qzx/commands/system/inspect_port.py
Pruebas: tests/test_system_commands/test_inspect_port.py
Canal de documentación: Documentación de desarrollo 0.2.2.0.15 · main · sha256:b91acee86268edb7cb018a94e089ff8e95835eda3f2cf08b39796c0ab9654693
Disponibilidad: 0.2.2.0.15 o anterior

Guía práctica

Aprende cuándo qzx inspectPort encaja en la tarea, cómo se compara con las herramientas nativas y qué detalles importan al automatizar.

9 min de lectura
Cómo averiguar qué proceso está usando un puerto en Windows, Linux y macOS
Si un servidor indica que un puerto ya está ocupado, identifica al listener antes de cambiar procesos. Compara herramientas nativas con un diagnóstico QZX estructurado.
Leer la guía práctica

Sigue explorando

Estos comandos también pertenecen a la categoría de sistema. Compáralos para elegir la operación que mejor resuelva tu tarea.

Explorar todos los comandos de QZX