qzx 0.2.2.0.6a13

Predictable cross-platform commands and structured JSON for AI agents and automation

QZX — Quick Zap Exchange

QZX — Quick Zap Exchange, created and maintained by Alejandro Sánchez.

About Alejandro Sánchez · Contact QZX · Support the project

QZX is an open-source Python CLI that gives AI agents, automation, and people one documented command vocabulary for supported operations on Windows, Linux, and macOS.

QZX is completely free to use. There are no paid plans or paid features. Donations are welcome because they support ongoing development, but they are optional and never unlock features or change the product experience.

Website · Command documentation · Recorded output · Compatibility · Security and telemetry · Documentación en español

QZX is a local command interface, not a shell replacement, remote execution service, or security sandbox. It reduces platform-specific branches only for operations present in the installed command catalog.

Install the published package

python -m pip install --pre qzx
qzx listCommands
qzx help findFiles
qzx getCurrentDateTime
qzx getCurrentDateTime --output-format iso --json

This source release is QZX 0.2.2.0.6a13 and requires Python >=3.13. A normal python -m pip install qzx selects the latest final release; add --pre to opt into the newest pre-release. PyPI is authoritative for which version those commands currently select.

QZX supports the standard CPython 3.13.x build. Other Python versions or implementations may work, but experimental free-threaded CPython builds, PyPy, and other implementations are not certified.

Source	Version	Python	Command surface
Source release described here	0.2.2.0.6a13	>=3.13; standard CPython 3.13.x is certified	87 canonical commands in the generated command index

PyPI is authoritative for what pip install qzx installs. The installed runtime is authoritative for its own command list.

Output contract

Every public command returns an object with at least:

• success: an explicit boolean outcome;
• message: a descriptive human-readable summary;
• command-specific evidence such as paths, counts, units, versions, diagnostics, causes, or remediation when available.

The CLI prints message by default. Pass --json to print the complete structured result:

qzx findFiles examples/qzx_in_action "*.txt" -r
qzx findFiles examples/qzx_in_action "*.txt" -r --json

Command lookup is case-insensitive. Documentation uses each command's canonical lower-camel-case spelling.

Command maturity is explicit

Every installed command has an independent lifecycle assessment. help, listCommands, direct --json output, and the public catalog expose whether its contract is Alpha, Beta, Release Candidate, Stable, or Deprecated. Planning and proof-of-concept work remains outside the executable command loader, so an AI agent cannot mistake a roadmap intention for an installed capability.

The initial assessment is deliberately conservative: existing public commands start at Alpha until command-specific evidence supports promotion. Immutable future release tags preserve the exact command-to-stage map shipped by that version. See the command lifecycle policy.

Good starting commands in this release

These names belong to this release's generated command index:

qzx version --json
qzx listCommands --json
qzx help findFiles
qzx systemInfo --json
qzx getCurrentDateTime --output-format iso --json
qzx findFiles . "*.py" -r --json
qzx findText "TODO" src -r --json
qzx getRamInfo --json
qzx getDiskSpace --json
qzx listProcesses "python" --json

Before a consequential operation, inspect the installed help and the command reference for parameters, platform availability, native dependencies, mutation classification, backup requirements, and preview support.

Development-only commands

The following examples require the development checkout and must not be recommended after only pip install qzx:

qzx projectDoctor . --json
qzx systemDoctor --json
qzx auditRepository . --json

Install the checkout for development:

python -m pip install -e .
python -m pytest -q

The repository launchers (qzx.bat and qzx.sh) can also run the checkout directly. They prefer the standard CPython 3.13 runtime selected explicitly with QZX_PYTHON, an active compatible environment, or an existing uv installation. Ordinary invocations use a validated packaged command index and import only the requested command; full discovery remains a development and CI integrity check. The basic qzx Welcome path avoids system, memory, and storage probes; request those details explicitly with qzx Welcome true.

Optional command groups can be installed with python -m pip install "qzx[filetype]" or python -m pip install "qzx[ai]". Some operations also depend on host tools such as Git, smartmontools, formatters, or language toolchains.

Safety model

QZX executes with the permissions of the current user. Commands may mutate or delete files, terminate processes, invoke native programs, access the network, or require elevated privileges.

In the development checkout, commands marked dangerous must create a restorable backup before a real filesystem mutation and abort when the backup fails. Preview and read-only modes do not require a backup. Explicit bypasses --dangerously-bypass-approvals-and-sandbox, --yolo, and QZX_SAFETY=YOLO can skip that QZX backup barrier; they do not bypass operating-system permissions or grant user authorization.

Review the security model before delegating mutating commands.

Pseudonymous CLI telemetry

Telemetry is enabled by default and schedules at most one version_first_run event per QZX version and random local installation identifier. It sends random installation and event UUIDs, QZX/Python/OS metadata, architecture, virtual-environment and known-CI flags. The server also observes the request IP and receipt time.

It does not send command names, arguments, terminal input, paths, environment values, usernames, hostnames, file contents, process lists, or hardware serial numbers. Raw IPs are retained for 1,825 days. Network or storage failures never change a command result.

Disable telemetry with either:

QZX_TELEMETRY=0 qzx Welcome
DO_NOT_TRACK=1 qzx Welcome

An explicit QZX_TELEMETRY=1 takes precedence over DO_NOT_TRACK=1. See the complete telemetry and deletion policy.

Compatibility evidence

QZX's automated tests are based on Microsoft Windows Server 2025 (10.0.26100) (x64), Microsoft Windows Server 2025 (10.0.26100) (x64 host / x86 CPython), Microsoft Windows Server 2022 (10.0.20348) (x64), Microsoft Windows 11 Enterprise (10.0.26200) (arm64), Ubuntu 24.04.4 (x64), Ubuntu 24.04.4 (arm64), Ubuntu 22.04.5 (x64), macOS 26.4 (25E246) (arm64), macOS 15.7.7 (24G720) (arm64), macOS 15.7.7 (24G720) (x64 (Intel)), Debian 13.6 (amd64), Alpine Linux 3.24.1 (x86_64), FreeBSD 15.1-RELEASE (amd64), OpenBSD 7.9 (amd64), OmniOS r151054 LTS (x86_64), and Oracle Solaris 11.4 CBE (x86_64), using the standard CPython 3.13 build.

QZX is Alpha software. This list identifies the environments used by the test matrix; it does not report run outcomes or guarantee compatibility.

Mocked unit tests are not compatibility evidence. Platform claims require real-system tests that exercise the installed native dependencies and QZX's public interface; the distinction and review rules are documented in the test evidence policy.

Complete local stdout snapshots identify their QZX version, Python version, operating system, date, fixture, and exit code on the QZX in action page.

Repository structure

• src/qzx/resources/product-manifest.json is the canonical product, release, output, Python-policy, and telemetry manifest.
• src/qzx/resources/test-environments.json is the result-neutral source for the operating systems, versions, architectures, and runtime used by the automated test matrix.
• src/qzx/resources/command-index.json is a generated, validated projection of the discovered command classes. It lets each invocation import only the requested command module; scripts/sync_command_index.py regenerates or verifies it.
• src/qzx/_build_info.py is the generated lightweight startup projection of the canonical product and lifecycle manifests; scripts/sync_runtime_metadata.py regenerates or verifies it.
• src/qzx/commands/ contains command implementations.
• tests/ contains the public automated Python test suite.
• examples/ contains standalone usage examples.
• docs/ contains public product philosophy and generated command references.
• .github/ contains the public contribution, funding, issue, and CI configuration.

Contributing

Start with the contribution guide and project philosophy. Preserve the structured output contract, add proportional tests, and keep published and development availability explicit.

License: Apache-2.0. The attribution notice is in NOTICE. See how to contribute, how to cite QZX, the security policy, QZX Core Guarantee, sponsorship independence policy, and name and trademark policy. Project participation and direction are documented in the code of conduct, governance, authors and credits, and public roadmap.