file · Command reference

`qzx findFiles`

What it does

Advanced file search with multiple filtering options (like find + grep combined)

Canonical command: findFiles

Accepted aliases: None

Case-sensitive: no

Included in the published package

Available in PyPI 0.2.2.0.2. This page documents the 0.2.2.0.2 alpha development checkout.

Safety and effects

Read-only under the current classification

No documented dry-run parameter

No native program invocation in the current classification

No documented network use

No inherent elevation requirement

This safety classification was reviewed against implementation digest sha256:838ed7b792664fcef191241b58375a6fcac28b0d8244274a7937bbca2e243e41 on 2026-07-24.

Exact syntax

qzx findFiles [search_path] [pattern] [recursive] [max_depth] [type] [size] [min_size] [max_size] [mtime] [newer_than] [older_than] [contains] [contains_regex] [case_sensitive] [exclude] [exclude_dir] [follow_symlinks] [sort_by] [reverse_sort] [format] [limit] --json

Parameters

Name	Type	Required	Default	Description
search_path	str	No	"."	Path to start the search from
pattern	str	No	"*"	File name pattern to search for (supports glob syntax: *.txt, data-???.csv)
recursive	str	No	"-r"	Recursion level: -r/--recursive for unlimited depth, -rN/--recursiveN for N levels deep
max_depth	str	No	Not declared	Maximum directory depth to search (null for unlimited)
type	str	No	Not declared	Filter by type: "f" (files), "d" (directories), or "l" (links)
size	str	No	Not declared	Filter by size (e.g., +1M for >1MB, -500K for <500KB, 10K for exactly 10KB)
min_size	str	No	Not declared	Minimum file size in bytes or with KB/MB/GB suffix
max_size	str	No	Not declared	Maximum file size in bytes or with KB/MB/GB suffix
mtime	str	No	Not declared	Filter by modification time (e.g., +7 for >7 days old, -2 for <2 days old)
newer_than	str	No	Not declared	Files newer than specified date (YYYY-MM-DD) or "today", "yesterday"
older_than	str	No	Not declared	Files older than specified date (YYYY-MM-DD) or "today", "yesterday"
contains	str	No	Not declared	Only include files containing this text
contains_regex	str	No	Not declared	Only include files matching this regex pattern
case_sensitive	bool	No	false	Make content searches case sensitive (true/false)
exclude	str	No	Not declared	Exclude file/directory patterns (comma-separated: .bak,.tmp)
exclude_dir	str	No	Not declared	Exclude directory patterns (comma-separated: .git,.vscode)
follow_symlinks	bool	No	false	Follow symbolic links (true/false)
sort_by	str	No	"path"	Sort by: name, path, size, mtime (modification time), or none
reverse_sort	bool	No	false	Reverse the sorting order (true/false)
format	str	No	"full"	Output format: "full" (default), "name" (filename only), "detailed" (full details), "json", "csv"
limit	str	No	Not declared	Maximum number of results to return

Input examples

qzx findFiles . *.py

Find all Python files in current directory and subdirectories

qzx findFiles /src *.js false

Find all JavaScript files in /src without searching subdirectories

qzx findFiles . * true 2 f

Find all files up to 2 levels deep

qzx findFiles . *.txt null f +1M

Find all text files larger than 1MB

qzx findFiles . * null null null null null null -7

Find files modified within the last 7 days

qzx findFiles . *.log null null null null null today null

Find log files created or modified today

qzx findFiles . *.py null null null null null null null TODO

Find Python files containing the word "TODO"

qzx findFiles . * null null null null null null null null "def\s+\w+"

Find files containing function definitions using regex

qzx findFiles . * null null null null null null null null null false "*.tmp,*.bak"

Find all files excluding temp and backup files

qzx findFiles . * true null null null null null null null null null null .git,node_modules

Find all files excluding .git and node_modules directories

For the complete structured payload, add --json: qzx findFiles [search_path] [pattern] [recursive] [max_depth] [type] [size] [min_size] [max_size] [mtime] [newer_than] [older_than] [contains] [contains_regex] [case_sensitive] [exclude] [exclude_dir] [follow_symlinks] [sort_by] [reverse_sort] [format] [limit] --json

Observed output example

Captured with QZX 0.2.2.0.2 on Windows 11; exit code 0. Host-dependent values and duration can vary.

Example command: qzx findFiles ../artifacts/qzx-evidence/find-files "*.txt" -r --format name --json

{
    "success": true,
    "message": "Found 2 items in '../artifacts/qzx-evidence/find-files', total size: 13.00 B",
    "search_path": "../artifacts/qzx-evidence/find-files",
    "pattern": "*.txt",
    "recursive": "unlimited",
    "count": 2,
    "total_size": 13,
    "total_size_readable": "13.00 B",
    "results": [
        "alpha.txt",
        "beta.txt"
    ],
    "meta": {
        "command": "findFiles",
        "duration_ms": 1.49,
        "schema_version": 1
    }
}

View the JSON result contract

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "count": [],
        "error": {
            "type": "string"
        },
        "pattern": [],
        "recursive": [],
        "results": [],
        "search_path": [],
        "total_size": [],
        "total_size_readable": [],
        "traceback": []
    },
    "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: captured and digest-validated.

Evidence and provenance

Implementation: src/qzx/commands/file/find_files.py
Tests: tests/test_file_commands/test_find_files.py
Documentation channel: Development documentation 0.2.2.0.2 · main · sha256:319b16857a87636ebc3b89734cc040a737bb56194464fca33ce73bdae2043096
Availability: 0.2.2.0.2 or earlier

Keep exploring

These commands also belong to the file category. Compare them to choose the operation that best fits your task.

Explore all QZX commands