archivos · Referencia de comando

`qzx findFiles`

Qué hace

Busca archivos por nombre, profundidad, tamaño y fecha de modificación, y devuelve metadatos estructurados.

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.8. La documentación corresponde al checkout alpha 0.2.2.0.8.

Comportamiento y protecciones integradas

Inspecciona sin cambiar el estado

Ejecución directa para esta operación

Funciona sin invocar programas nativos

Funciona sin usar la red

Diseñado para funcionar sin elevación

Esta clasificación de seguridad fue revisada por OpenAI GPT-5.6 Pro contra el digest de implementación sha256:12717a5382f7fc0b8b27847c67aaf89741ae65a55241683f7b293715ee2e279b el 2026-08-25.

Sintaxis exacta

qzx findFiles [search_path] [pattern] [recursive] [min_size] [max_size] [modified_after] [modified_before] [exclude] [exclude_dirs] [sort_by] [descending] [limit] --json

Parámetros

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

Nombre	Tipo	Obligatorio	Predeterminado	Descripción
search_path	str	No	"."	Directorio desde el que comienza la búsqueda
pattern	str	No	"*"	Patrón glob del nombre de archivo, como *.txt o data-???.csv; de forma predeterminada incluye todos los archivos
recursive	str	No	"-r"	Profundidad: -r sin límite, false sólo para el directorio actual o -rN hasta N niveles
min_size	str	No	No declarado	Tamaño mínimo, por ejemplo 500KB, 10MiB o una cantidad de bytes
max_size	str	No	No declarado	Tamaño máximo, por ejemplo 2GB, 20MiB o una cantidad de bytes
modified_after	str	No	No declarado	Incluye sólo archivos modificados en o después de YYYY-MM-DD, "today" o "yesterday"
modified_before	str	No	No declarado	Incluye sólo archivos modificados antes de YYYY-MM-DD, "today" o "yesterday"
exclude	str	No	No declarado	Patrones glob de nombres de archivo que se excluirán, separados por comas
exclude_dirs	str	No	No declarado	Patrones glob de nombres de directorio que se omitirán, separados por comas
sort_by	str	No	"path"	Ordena por path, name, size o modified
descending	bool	No	false	Invierte el orden seleccionado (true/false)
limit	str	No	No declarado	Número máximo de archivos que se devolverá después de ordenar

Ejemplos de entrada

qzx findFiles . "*.py" --exclude-dirs ".git,.venv"

Buscar archivos Python recursivamente y omitir directorios habituales de metadatos

qzx findFiles Downloads "*" --min-size 100MiB --sort-by size --descending true --limit 20

Devolver los 20 archivos coincidentes más grandes de al menos 100 MiB

qzx findFiles logs "*.log" --modified-after 2026-07-01 --recursive false

Buscar logs modificados recientemente sin recorrer subdirectorios

Para obtener la carga estructurada completa, añade --json: qzx findFiles [search_path] [pattern] [recursive] [min_size] [max_size] [modified_after] [modified_before] [exclude] [exclude_dirs] [sort_by] [descending] [limit] --json

Ejemplo de salida observada

Capturado con QZX 0.2.2.0.8 en Windows 11; código de salida 0. Los valores dependientes del host y la duración pueden variar.

Comando del ejemplo: qzx findFiles ../artifacts/qzx-evidence/find-files "*.txt" -r --json

{
    "success": true,
    "message": "Found 2 matching files in 'C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\find-files'. Returning 2 files totaling 13.00 B.",
    "search_path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\find-files",
    "pattern": "*.txt",
    "recursive": "unlimited",
    "filters": {
        "min_size_bytes": null,
        "max_size_bytes": null,
        "modified_after": null,
        "modified_before": null,
        "exclude": [],
        "exclude_dirs": []
    },
    "sort": {
        "by": "path",
        "descending": false
    },
    "matched_count": 2,
    "matched_size_bytes": 13,
    "matched_size_readable": "13.00 B",
    "count": 2,
    "total_size_bytes": 13,
    "total_size_readable": "13.00 B",
    "limit": null,
    "truncated": false,
    "skipped_unreadable": 0,
    "warnings": [],
    "results": [
        {
            "name": "alpha.txt",
            "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\find-files\\alpha.txt",
            "relative_path": "alpha.txt",
            "depth": 0,
            "size_bytes": 7,
            "size_readable": "7.00 B",
            "modified_timestamp": 1788913185.7912128,
            "modified_at": "2026-09-08T19:19:45-05:00"
        },
        {
            "name": "beta.txt",
            "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\find-files\\nested\\beta.txt",
            "relative_path": "nested\\beta.txt",
            "depth": 1,
            "size_bytes": 6,
            "size_readable": "6.00 B",
            "modified_timestamp": 1788913185.7912128,
            "modified_at": "2026-09-08T19:19:45-05:00"
        }
    ],
    "meta": {
        "command": "findFiles",
        "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": 3.926,
        "schema_version": 1
    }
}

Ver el contrato de resultado JSON

{
    "$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
        },
        "count": [],
        "filters": {
            "type": "object",
            "properties": {
                "min_size_bytes": [],
                "max_size_bytes": [],
                "modified_after": [],
                "modified_before": [],
                "exclude": [],
                "exclude_dirs": []
            },
            "additionalProperties": true
        },
        "limit": [],
        "matched_count": [],
        "matched_size_bytes": [],
        "matched_size_readable": [],
        "pattern": [],
        "recursive": [],
        "results": [],
        "search_path": [],
        "skipped_unreadable": [],
        "sort": {
            "type": "object",
            "properties": {
                "by": [],
                "descending": []
            },
            "additionalProperties": true
        },
        "total_size_bytes": [],
        "total_size_readable": [],
        "truncated": [],
        "warnings": []
    },
    "additionalProperties": true
}

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.

{
    "success": false,
    "message": "Search directory does not exist: C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\missing-golden-core-path",
    "error": "Search directory does not exist: C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\missing-golden-core-path",
    "error_code": "path_not_found",
    "details": {
        "search_path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\missing-golden-core-path"
    },
    "meta": {
        "command": "findFiles",
        "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": 10.015,
        "schema_version": 1
    }
}

Comando capturado: qzx findFiles ../artifacts/qzx-evidence/missing-golden-core-path "*.txt" -r --json

Flujo de evidencia: capturada y validada por digest.

Evidencia y procedencia

Implementación: src/qzx/commands/file/find_files.py
Pruebas: tests/test_file_commands/test_find_files.py
Canal de documentación: Documentación de desarrollo 0.2.2.0.8 · main · sha256:9aa902dfb6b006017e52972bf7871fef49b03ec24ff80741231d743d0354bfc2
Disponibilidad: 0.2.2.0.8 o anterior

Guía práctica

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

13 min de lectura
Cómo ver el espacio en disco en Windows, Linux y macOS
Windows, Linux y macOS exponen la capacidad de disco de formas diferentes. Aprende los comandos nativos, qué significan sus cifras y cómo QZX unifica la consulta.
Leer la guía práctica

Sigue explorando

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

Explorar todos los comandos de QZX