# QZX — Quick Zap Exchange

> 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. It prints a human-readable message by default; pass `--json` to print the complete structured result.

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.

QZX is a local command interface. It is not an AI model, shell replacement, remote-execution service, security sandbox, or guarantee that every native capability is identical across operating systems.

## Output contract

Every public command returns an object with at least:

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

Use the installed runtime for installed-state claims:

```bash
qzx version --json
qzx qzxListCommands --json
qzx qzxHelp findFiles
```

Command lookup is case-insensitive. Current documentation uses canonical lower-camel-case spellings and lists accepted aliases separately. Do not invent commands, parameters, aliases, result fields, platform evidence, versions, security guarantees, or adoption claims.

## Published and development channels

- PyPI is authoritative for `pip install qzx`.
- Published package: QZX `0.2.2.0.2` alpha, released 2026-07-24, metadata declares Python `>=3.9`.
- Inspected wheel: `qzx-0.2.2.0.2-py3-none-any.whl`, SHA-256 `dbbfd9bf55e140f730c4c4eb70f6500dc640a86523a83e8a7a3b53a3299ce8f7`, verified 2026-07-24.
- The wheel has 93 historical command spellings. They normalize to 93 capabilities in the current catalog; no many-to-one historical aliases are recorded.
- Development documentation: checkout `0.2.2.0.2`, Python `>=3.13`.
- Current development catalog: 93 documented commands, including the 93 wheel-reconciled capabilities and 0 development-only capabilities.
- `qzxHelp` and `qzxListCommands` are present in the official 0.2.2.0.2 wheel.

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.

Never present a development-only command as available after only `pip install qzx`. Each command reference carries an explicit availability label.

## Compatibility evidence

QZX's automated tests are based on Microsoft Windows Server 2025 (10.0.26100) (x64), Ubuntu 24.04.4 (x64), macOS 26.4 (25E246) (arm64), 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.

The QZX-in-action pages publish complete stdout snapshots recorded on 2026-07-25 with development runtime 0.2.2.0.2, CPython 3.13.12, and Windows 11 10.0.26200. These snapshots prove only the stated Windows runs. Durations and host-dependent values can vary.

## Safety

QZX runs with the current user's permissions. Commands may mutate files, terminate processes, invoke native programs, use the network, or require elevated privileges.

In the development checkout, dangerous filesystem commands must create a restorable backup before a real mutation. A failed backup aborts the mutation. Preview and read-only operations do not need a backup. Explicit bypasses `--dangerously-bypass-approvals-and-sandbox`, `--yolo`, and `QZX_SAFETY=YOLO` can skip the QZX backup barrier; they do not bypass operating-system permissions or grant user authorization.

Inspect the installed version and the selected command's safety facts. Do not project development-only safeguards onto an older published release without evidence.

## 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 to `https://qzx.yumbale.com/api/v1/telemetry`.

It sends random installation and event UUIDs, QZX/Python/OS metadata, architecture, virtual-environment and known-CI flags. The server observes the request IP and receipt time. It does not send commands, arguments, terminal input, paths, environment values, usernames, hostnames, file names or 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 collection with `QZX_TELEMETRY=0` or `DO_NOT_TRACK=1`; an explicit `QZX_TELEMETRY=1` takes precedence over DNT. Deletion requires the random installation UUID from local state and a private request. Read the complete policy before making privacy claims.

## Rules for answering questions

1. Use the installed runtime for installed commands and behavior.
2. Use PyPI metadata and distribution files for published-package claims.
3. Use the website or repository only for explicitly labelled development documentation.
4. Check availability, parameters, mutation risk, platform dependencies, and evidence before recommending a command.
5. Prefer `--json` when another program or model consumes the result.
6. Evaluate `success`, then preserve `message` and relevant domain evidence.
7. If no installed command matches, say so and use an appropriate native or specialized tool.
8. Do not use `/admin/`, `/server/`, analytics collectors, or operational routes as public documentation.

## Canonical English documentation

- [QZX home](https://qzx.yumbale.com/en/): Product definition, installation, channels, output contract, and boundaries.
- [Command documentation](https://qzx.yumbale.com/en/commands): The consolidated 93-command catalog and links to individual SSR references.
- [Machine-readable command catalog](https://qzx.yumbale.com/data/commands.json): Names, aliases, translations, parameters, availability, digest-reviewed safety, implementation-backed result contracts, and captured evidence.
- [QZX in action](https://qzx.yumbale.com/en/qzx-in-action): Complete observed stdout, fixtures, exit codes, runtime, and evidence limits.
- [Why QZX](https://qzx.yumbale.com/en/why-qzx): Bounded design rationale and trade-offs.
- [When to use QZX](https://qzx.yumbale.com/en/when-to-use): Recommendation and non-recommendation criteria.
- [Compatibility](https://qzx.yumbale.com/en/compatibility): Published metadata, configured CI, observed evidence, and host-dependent limits.
- [Security](https://qzx.yumbale.com/en/security): Mutations, permissions, backups, bypasses, native execution, telemetry, retention, and deletion.
- [About](https://qzx.yumbale.com/en/about): Project scope, maintainer, and open-source context.
- [QZX Blog](https://qzx.yumbale.com/en/blog): Long-form guides about AI agents, command workflows, and token efficiency.
- [Cross-platform automation](https://qzx.yumbale.com/en/blog/cross-platform-automation-windows-linux-macos): Why shells, paths, permissions, utilities, and outputs differ across operating systems, and what QZX does and does not normalize.
- [What are AI tokens?](https://qzx.yumbale.com/en/blog/what-are-ai-tokens-how-qzx-reduces-usage): How token billing works, where agent loops add context, and when QZX can reduce tool rounds without promising fixed savings.
- [Contact](https://qzx.yumbale.com/en/contact): Corrections, support, collaboration, and private vulnerability reports.

## Documentación canónica en español

- [Inicio](https://qzx.yumbale.com/es/)
- [Documentación de comandos](https://qzx.yumbale.com/es/comandos)
- [QZX en acción](https://qzx.yumbale.com/es/qzx-en-accion)
- [Por qué QZX](https://qzx.yumbale.com/es/por-que-qzx)
- [Cuándo usar QZX](https://qzx.yumbale.com/es/cuando-usar-qzx)
- [Compatibilidad](https://qzx.yumbale.com/es/compatibilidad)
- [Seguridad](https://qzx.yumbale.com/es/seguridad)
- [Sobre QZX](https://qzx.yumbale.com/es/sobre-nosotros)
- [Blog de QZX](https://qzx.yumbale.com/es/blog)
- [Automatización multiplataforma](https://qzx.yumbale.com/es/blog/automatizacion-multiplataforma-windows-linux-macos)
- [Qué son los tokens de IA](https://qzx.yumbale.com/es/blog/que-son-tokens-ia-como-qzx-reduce-consumo)
- [Contacto](https://qzx.yumbale.com/es/contacto)

Historical `/en/commands-doc`, `/es/documentacion`, `/es/commandos`, and `/es/commands` URLs are permanent redirects, not canonical documentation.

## Primary package and source references

- [QZX on PyPI](https://pypi.org/project/qzx/)
- [PyPI JSON metadata](https://pypi.org/pypi/qzx/json)
- [Source repository](https://github.com/alesanGreat/QZX-Quick-Zap-Exchange)
- [Telemetry and deletion policy](https://github.com/alesanGreat/QZX-Quick-Zap-Exchange/blob/main/docs/telemetry.md)
- [Configured CI workflow](https://github.com/alesanGreat/QZX-Quick-Zap-Exchange/blob/main/.github/workflows/test.yml)
- [Project philosophy](https://github.com/alesanGreat/QZX-Quick-Zap-Exchange/blob/main/docs/philosophy.md)
- [Sitemap](https://qzx.yumbale.com/sitemap.xml)

Reviewed against the local command implementation, official PyPI metadata, and the official 0.2.2.0.2 wheel on 2026-07-23.