system · Command reference
qzx diagnoseStorage
What it does
Diagnoses storage pressure by combining disk capacity, large-file discovery, and byte-verified duplicate analysis without deleting anything
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.7a9. This page documents the 0.2.2.0.7a9 alpha development checkout.
Behavior and built-in protections
Inspects without changing state
Direct execution for this operation
Works without invoking native programs
Works without network access
No elevation required by design
Combines local capacity, bounded large-file discovery, and optional duplicate verification by size, SHA-256, and byte-for-byte comparison. It never deletes or modifies files. Large files are review evidence only; potential reclaim is reported only for verified duplicate groups. S.M.A.R.T. hardware health remains a separate getDiskHealth workflow.
This safety classification was reviewed by OpenAI GPT-5.6 Sol against implementation digest sha256:3f388a34b22a9b59259ba7c46dfec7a8ff570030f038c1a0aeba9b8f8a936bb9 on 2026-09-04.
Exact syntax
qzx diagnoseStorage [path] [min_file_size] [max_files] [duplicate_min_size_kb] [max_depth] [include_duplicates] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| path | str | No | "." | Directory to diagnose (defaults to the current directory) |
| min_file_size | str | No | "100MiB" | Minimum size for the large-file view, for example 100MiB or 1GB |
| max_files | int | No | 20 | Maximum number of largest files returned (1-1000) |
| duplicate_min_size_kb | int | No | 10240 | Minimum file size in KB considered by the duplicate scan (defaults to 10240 = 10 MiB) |
| max_depth | int | No | 6 | Maximum directory depth scanned for large and duplicate files (0-64; defaults to 6) |
| include_duplicates | bool | No | true | Run the byte-verified duplicate scan in the same workflow (true/false; defaults to true) |
Input examples
qzx diagnoseStorageDiagnose storage pressure in the current directory with bounded scans
qzx diagnoseStorage C:/ --max-depth 4 --max-files 30Inspect a Windows volume with a shallower scan and a larger top-file list
qzx diagnoseStorage /home --include-duplicates false --min-file-size 500MiBRun a faster capacity and large-file diagnosis without hashing duplicates
For the complete structured payload, add --json: qzx diagnoseStorage [path] [min_file_size] [max_files] [duplicate_min_size_kb] [max_depth] [include_duplicates] --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 diagnoseStorage --json
{
"success": true,
"message": "Diagnoses storage pressure by combining disk capacity, large-file discovery, and byte-verified duplicate analysis without deleting anything. In this illustrative example, the command completed successfully.",
"meta": {
"command": "diagnoseStorage",
"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
},
"assessment": "Example value",
"capacity": "Example value",
"duplicates": [
{
"name": "example",
"status": "ok"
}
],
"large_files": "C:\\project\\example.txt",
"partial": "Example value",
"path": "C:\\project\\example.txt",
"probe_status": {
"capacity": "Example value",
"large_files": "C:\\project\\example.txt",
"duplicates": [
{
"name": "example",
"status": "ok"
}
]
},
"read_only": true,
"recommendations": [
{
"name": "example",
"status": "ok"
}
],
"related_commands": [
{
"name": "example",
"status": "ok"
}
],
"report": "Analysis complete.\nNo blocking issues were found.",
"scan_scope": {
"max_depth": "Example value",
"large_file_min_size": "C:\\project\\example.txt",
"max_large_files_returned": "C:\\project\\example.txt",
"duplicate_scan_requested": "Example value",
"duplicate_min_size_kb": "Example value"
},
"warnings": [
{
"name": "example",
"status": "ok"
}
]
}View the JSON result contract
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"success",
"message",
"meta"
],
"properties": {
"success": {
"type": "boolean"
},
"message": {
"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
},
"assessment": [],
"capacity": [],
"duplicates": [],
"large_files": [],
"partial": [],
"path": [],
"probe_status": {
"type": "object",
"properties": {
"capacity": {
"type": "string"
},
"large_files": {
"type": "string"
},
"duplicates": []
},
"additionalProperties": true
},
"read_only": {
"type": "boolean"
},
"recommendations": [],
"related_commands": {
"type": "array"
},
"report": [],
"scan_scope": {
"type": "object",
"properties": {
"max_depth": [],
"large_file_min_size": [],
"max_large_files_returned": [],
"duplicate_scan_requested": [],
"duplicate_min_size_kb": []
},
"additionalProperties": true
},
"warnings": []
},
"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: ready for deterministic automated capture.
Evidence and provenance
- Implementation
- src/qzx/commands/system/diagnose_storage.py
- Documentation channel
- Development documentation 0.2.2.0.7a9 · main · sha256:e8fb90f76dc2e944e25bface47f96c7979a569f40bf1f8f6cbd1bd291441369e
- Availability
- 0.2.2.0.7a9 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.
qzx clearScreenClears an interactive terminal directly without spawning cls, clear, or a command shellqzx explainFileWithGeminiPreviews and optionally sends bounded file samples to Google Gemini for explanationqzx checkSystemPathDiagnoses the system PATH variable, lists broken or duplicate folders, and locates all instances of a binaryqzx getCpuLoadGets information about current CPU usage