file · Command reference
qzx listFiles
What it does
Lists files in a directory with support for wildcards and recursive searching
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.8. This page documents the 0.2.2.0.8 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
This safety classification was reviewed by OpenAI GPT-5.6 Pro against implementation digest sha256:9ed75febb115f7e7e659a5047df5f47a43e95d5c7e32d3f5b1c96e4f85b27eff on 2026-08-25.
Exact syntax
qzx listFiles [directory_path] [pattern] [recursive] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| directory_path | str | No | "." | Path to the directory to list files from |
| pattern | str | No | "*" | File pattern to filter by (e.g., "*.txt", "doc*.pdf") |
| recursive | str | No | Not declared | Recursion level: none by default, -r/--recursive for unlimited depth, -rN/--recursiveN for N levels deep |
Input examples
qzx listFilesList all files in the current directory
qzx listFiles C:\DocumentsList all files in the C:\Documents directory (Windows)
qzx listFiles /home/user/documentsList all files in the /home/user/documents directory (Linux/Mac)
qzx listFiles . "*.py"List all Python files in the current directory
qzx listFiles src "*.js" -rList all JavaScript files in the src directory and all its subdirectories
qzx listFiles src "*.js" -r2List all JavaScript files in the src directory and up to 2 levels of subdirectories
For the complete structured payload, add --json: qzx listFiles [directory_path] [pattern] [recursive] --json
Observed output example
Captured with QZX 0.2.2.0.8 on Windows 11; exit code 0. Host-dependent values and duration can vary.
Example command: qzx listFiles ../artifacts/qzx-evidence/golden-core-files "*.txt" -r --json
{
"success": true,
"directory": "../artifacts/qzx-evidence/golden-core-files",
"pattern": "*.txt",
"recursive": true,
"recursion_depth": null,
"files": [
{
"name": "alpha.txt",
"path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\golden-core-files\\alpha.txt",
"size": 33,
"size_formatted": "33.0 B",
"modified": 1788913187.3232598,
"modified_formatted": "2026-09-08 19:19:47",
"is_directory": false
},
{
"name": "gamma.txt",
"path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\golden-core-files\\nested\\gamma.txt",
"size": 19,
"size_formatted": "19.0 B",
"modified": 1788913187.3252766,
"modified_formatted": "2026-09-08 19:19:47",
"is_directory": false
}
],
"message": "Found 2 files matching '*.txt' in '../artifacts/qzx-evidence/golden-core-files' (including subdirectories)",
"meta": {
"command": "listFiles",
"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": 7.276,
"schema_version": 1
}
}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
},
"details": {
"type": "object",
"properties": {
"directory": [],
"pattern": []
},
"additionalProperties": true
},
"directory": [],
"error": [],
"error_code": {
"type": "string"
},
"files": {
"type": "array"
},
"pattern": [],
"recursion_depth": [],
"recursive": []
},
"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.
{
"success": false,
"error": "Directory '../artifacts/qzx-evidence/missing-golden-core-path' not found.",
"error_code": "path_not_found",
"message": "Directory '../artifacts/qzx-evidence/missing-golden-core-path' not found.",
"details": {
"directory": "../artifacts/qzx-evidence/missing-golden-core-path",
"pattern": "*"
},
"meta": {
"command": "listFiles",
"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": 2.403,
"schema_version": 1
}
}Captured command: qzx listFiles ../artifacts/qzx-evidence/missing-golden-core-path --json
Evidence workflow: captured and digest-validated.
Evidence and provenance
- Implementation
- src/qzx/commands/file/list_files.py
- Documentation channel
- Development documentation 0.2.2.0.8 · main · sha256:9aa902dfb6b006017e52972bf7871fef49b03ec24ff80741231d743d0354bfc2
- Availability
- 0.2.2.0.8 or earlier
Keep exploring
Related commands
These commands also belong to the file category. Compare them to choose the operation that best fits your task.
qzx isFileEmptyChecks zero-byte or whitespace-only file emptiness with streaming text decoding and no symbolic-link traversal by defaultqzx movePathMoves or renames one file, symbolic link, or complete directory; partial directory moves are rejectedqzx isFileBinaryDetermines whether a regular file is binary or text using bounded start/middle/end content samplingqzx readFileReads and displays the content of a file