file · Command reference

`qzx findText`

What it does

Searches for text patterns in files with advanced filtering options

Canonical command: findText

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:243c99bae0fd534a75882e1061c23105b4c14603ada49a4f42eb36d0bbd3c2e1 on 2026-07-24.

Exact syntax

qzx findText <pattern> <target> [recursive] [regex] [case_sensitive] [file_pattern] [context_lines] [invert_match] [count_only] [max_matches] [colored] --json

Parameters

Name	Type	Required	Default	Description
pattern	str	Yes	Not declared	Text pattern to search for (supports regular expressions)
target	str	Yes	Not declared	File or directory (or space-separated list of files/directories) to search in
recursive	str	No	Not declared	Recursion level: -r/--recursive for unlimited depth, -rN/--recursiveN for N levels deep
regex	bool	No	false	Use regular expressions for pattern matching (true/false)
case_sensitive	bool	No	true	Perform case-sensitive search (true/false)
file_pattern	str	No	"*"	Only search in files matching this pattern (e.g., ".py" or ".{py,js}")
context_lines	int	No	0	Number of lines to show before and after each match
invert_match	bool	No	false	Show lines that do NOT match the pattern (true/false)
count_only	bool	No	false	Only show count of matches per file (true/false)
max_matches	int	No	0	Maximum number of matches to display (0 for unlimited)
colored	bool	No	true	Highlight matches with color (true/false)

Input examples

qzx findText "function" "script.js"

Find all occurrences of "function" in a JavaScript file

qzx findText "error" "logs" true

Find all occurrences of "error" in all files under logs directory

qzx findText "def\s+\w+" "src" true true

Find all function definitions in Python files using regex

qzx findText "WARNING|ERROR" "logs" true true false "*.log"

Find warnings or errors in log files

qzx findText "TODO" "src" true false true "*.{py,js,ts}" 2

Find TODOs in source files with 2 lines of context

qzx findText "function" "file1.js file2.js lib/utils.js"

Find all occurrences of "function" in multiple specific files

For the complete structured payload, add --json: qzx findText <pattern> <target> [recursive] [regex] [case_sensitive] [file_pattern] [context_lines] [invert_match] [count_only] [max_matches] [colored] --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 findText "function" "script.js" --json

{
    "success": true,
    "message": "Searches for text patterns in files with advanced filtering options. In this illustrative example, the command completed successfully.",
    "case_sensitive": "Example value",
    "context_lines": [
        {
            "name": "example",
            "status": "ok"
        }
    ],
    "file_pattern": "C:\\project\\example.txt",
    "files_searched": "C:\\project\\example.txt",
    "files_with_matches": "C:\\project\\example.txt",
    "invert_match": "Example value",
    "pattern": "Example value",
    "recursive": "Example value",
    "regex": "Example value",
    "results": [
        {
            "path": "src/example.py",
            "size_readable": "4.2 KiB"
        }
    ],
    "target": "Example value",
    "total_matches": 3
}

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"
        },
        "case_sensitive": [],
        "context_lines": [],
        "error": {
            "type": "string"
        },
        "file_pattern": [],
        "files_searched": [],
        "files_with_matches": [],
        "invert_match": [],
        "pattern": [],
        "recursive": {
            "type": "string"
        },
        "regex": [],
        "results": [],
        "target": [],
        "total_matches": []
    },
    "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/file/find_text.py
Tests: tests/test_file_commands/test_find_text.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