Metadata-Version: 2.4
Name: qzx
Version: 0.2.2.0.6a7
Summary: Predictable cross-platform commands and structured JSON for AI agents and automation
Home-page: https://qzx.yumbale.com/
Author: Alejandro Sánchez
Author-email: qzx@yumbale.com
Maintainer: Alejandro Sánchez
Maintainer-email: qzx@yumbale.com
License-Expression: Apache-2.0
Project-URL: Documentation, https://qzx.yumbale.com/en/
Project-URL: Spanish Documentation, https://qzx.yumbale.com/es/
Project-URL: Command Catalog, https://qzx.yumbale.com/en/commands
Project-URL: Compatibility, https://qzx.yumbale.com/en/compatibility
Project-URL: Security, https://qzx.yumbale.com/en/security
Project-URL: Telemetry Policy, https://qzx.yumbale.com/en/security
Project-URL: Source, https://github.com/alesanGreat/QZX-Quick-Zap-Exchange
Project-URL: Issues, https://github.com/alesanGreat/QZX-Quick-Zap-Exchange/issues
Project-URL: Changelog, https://github.com/alesanGreat/QZX-Quick-Zap-Exchange/blob/main/CHANGELOG.md
Project-URL: Funding, https://qzx.yumbale.com/en/donate
Keywords: ai-agents,automation,cli,cross-platform,devops,structured-json,system-administration
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: psutil
Requires-Dist: chardet
Requires-Dist: colorama
Requires-Dist: Pygments<3,>=2.20
Requires-Dist: pathspec<2,>=1.1
Requires-Dist: packaging<27,>=24
Requires-Dist: dnspython<3,>=2.8
Requires-Dist: pyreadline3; platform_system == "Windows"
Provides-Extra: win
Requires-Dist: python-magic-bin; extra == "win"
Provides-Extra: unix
Requires-Dist: python-magic; extra == "unix"
Provides-Extra: filetype
Requires-Dist: python-magic-bin; platform_system == "Windows" and extra == "filetype"
Requires-Dist: python-magic; platform_system != "Windows" and extra == "filetype"
Provides-Extra: ai
Requires-Dist: requests; extra == "ai"
Requires-Dist: python-dotenv; extra == "ai"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: license-expression
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# QZX — Quick Zap Exchange

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

[About Alejandro Sánchez](https://qzx.yumbale.com/en/alejandro-sanchez) ·
[Contact QZX](mailto:qzx@yumbale.com) ·
[Support the project](https://qzx.yumbale.com/en/donate)

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](https://qzx.yumbale.com/en/) ·
[Command documentation](https://qzx.yumbale.com/en/commands) ·
[Recorded output](https://qzx.yumbale.com/en/qzx-in-action) ·
[Compatibility](https://qzx.yumbale.com/en/compatibility) ·
[Security and telemetry](https://qzx.yumbale.com/en/security) ·
[Documentación en español](https://qzx.yumbale.com/es/)

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

```bash
python -m pip install qzx
qzx qzxListCommands
qzx qzxHelp findFiles
qzx getCurrentDate
qzx getCurrentDate --json
```

PyPI hosts the QZX `0.2.2.0.6a5` pre-release with Python `>=3.13`
metadata. A normal `python -m pip install qzx` selects the latest final
release; add `--pre` to opt into the newest pre-release. The current checkout
follows the same Python minimum.

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 |
|---|---:|---:|---|
| Published pre-release | `0.2.2.0.6a5` | `>=3.13`; standard CPython 3.13.x is certified | 96 commands reconciled with the official wheel |
| Current checkout | `0.2.2.0.6a7` | `>=3.13`; standard CPython 3.13.x is certified | See the generated command catalog |

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:

```bash
qzx findFiles examples/qzx_in_action "*.txt" -r --format name
qzx findFiles examples/qzx_in_action "*.txt" -r --format name --json
```

Command lookup is case-insensitive. Documentation uses the current canonical
lower-camel-case spelling and lists accepted aliases separately.

### Command maturity is explicit

Every installed command has an independent lifecycle assessment. `qzxHelp`,
`qzxListCommands`, 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](docs/command-lifecycle.md).

## Good starting commands in PyPI pre-release 0.2.2.0.6a5

These names were verified in the official wheel:

```bash
qzx version --json
qzx qzxListCommands --json
qzx qzxHelp findFiles
qzx systemInfo --json
qzx getCurrentDate --json
qzx findFiles . "*.py" -r --json
qzx findText "TODO" src -r --json
qzx getRAMInfo --json
qzx getDiskInfo --json
qzx listProcesses "python" --json
```

Before a consequential operation, inspect the installed help and the
[command reference](https://qzx.yumbale.com/en/commands) 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`:

```bash
qzx scanProject . --json
qzx projectDoctor . --json
qzx systemDoctor --json
qzx auditRepository . --json
```

Install the checkout for development:

```bash
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](https://qzx.yumbale.com/en/security) 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:

```bash
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](https://qzx.yumbale.com/en/security).

## Compatibility evidence

<!-- BEGIN GENERATED TEST ENVIRONMENTS -->

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.

<!-- END GENERATED TEST ENVIRONMENTS -->

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](tests/README.md).

Complete local stdout snapshots identify their QZX version, Python version,
operating system, date, fixture, and exit code on the
[QZX in action](https://qzx.yumbale.com/en/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](CONTRIBUTING.md) and
[project philosophy](docs/philosophy.md). Preserve the structured output
contract, add proportional tests, and keep published and development
availability explicit.

License: [Apache-2.0](LICENSE). The attribution notice is in [NOTICE](NOTICE).
See [how to contribute](CONTRIBUTING.md), [how to cite QZX](CITATION.cff),
the [security policy](SECURITY.md), [QZX Core Guarantee](QZX_CORE_GUARANTEE.md),
[sponsorship independence policy](SPONSORSHIP.md), and
[name and trademark policy](TRADEMARKS.md). Project participation and direction
are documented in the [code of conduct](CODE_OF_CONDUCT.md),
[governance](GOVERNANCE.md), [authors and credits](AUTHORS.md), and
[public roadmap](ROADMAP.md).
