system · Command reference
qzx runDiagnosticCommand
What it does
Runs a strictly read-only native system diagnostic from a platform-specific allowlist
Canonical command: runDiagnosticCommand
Accepted aliases: None
Case-sensitive: no
Command maturity: Alpha
Available for real use and feedback while its interface and behavior can still evolve. This is the current development-checkout assessment. Every future immutable release tag preserves the exact assessment shipped by that version. Available in PyPI 0.2.2.0.6a8. This page documents the 0.2.2.0.6a8 alpha development checkout.
Safety and effects
Read-only under the current classification
No documented dry-run parameter
May invoke native programs
No documented network use
No inherent elevation requirement
Runs only a platform-specific allowlist of read-only operating-system diagnostics. It rejects executable paths, bypasses PATH when selecting the diagnostic executable, resolves trusted system locations, disables shell expansion, and validates command-specific arguments. netstat and ss require numeric output without process attribution; ss also blocks Unix-domain socket paths. The child runs from the executable directory with a minimal non-secret environment, drains stdout and stderr concurrently within separate memory budgets, and has a 20-second timeout.
This safety classification was reviewed by Codex against implementation digest sha256:994f9d24b7880a4db32667b69295fa01d5fb2f92b5f4810a9a27554bd9a5d833 on 2026-07-30.
Exact syntax
qzx runDiagnosticCommand <command> [args] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| command | str | Yes | Not declared | Read-only diagnostic. Windows: hostname, ipconfig, netstat, whoami. Unix: cal, date, free, hostname, netstat, ss, uname, uptime, whoami |
| args | list[str] | No | [] | Arguments accepted by QZX's command-specific read-only grammar |
Input examples
qzx runDiagnosticCommand hostnameRead the local system host name
qzx runDiagnosticCommand whoamiRead the current operating-system user
qzx runDiagnosticCommand uname -aRead Unix kernel and architecture details
qzx runDiagnosticCommand ipconfig /allRead the complete Windows network configuration
qzx runDiagnosticCommand netstat -anList connections numerically without name resolution
For the complete structured payload, add --json: qzx runDiagnosticCommand <command> [args] --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 runDiagnosticCommand hostname --json
{
"success": true,
"message": "Runs a strictly read-only native system diagnostic from a platform-specific allowlist. In this illustrative example, the command completed successfully.",
"meta": {
"command": "runDiagnosticCommand",
"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
},
"details": {
"summary": "Additional structured context is included here."
},
"stdout": "Command completed successfully."
}View the JSON result contract
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"error": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_code": {
"type": "string"
},
"stdout": {
"type": "string"
},
"stderr": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
},
"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"
]
}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: captured and digest-validated.
Evidence and provenance
- Implementation
- src/qzx/commands/system/run_diagnostic_command.py
- Documentation channel
- Development documentation 0.2.2.0.6a8 · main · sha256:040df8bbcb6b707bb4cdb7c2c1ad4cc6956ab647a451dc215ea78cdbb4c8ad96
- Availability
- 0.2.2.0.6a8 or earlier
Keep exploring
Related commands
These commands also belong to the system category. Compare them to choose the operation that best fits your task.