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. Get a useful diagnosis in the terminal, or add --json for structured evidence another program can consume.

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

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

Start with a problem, not a command catalog

After installing QZX, choose one useful job:

The project dot means the current directory. Replace the example hostname or URL with a safe, read-only destination you are authorized to inspect. A completed diagnostic is not a clean bill of health: inspect its findings and status fields, not only success.

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 · AI agent quickstart · Command documentation · Recorded output · 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. If you are choosing between QZX, shell composition, or a native API, use the technical decision guide.

Install the published package

If you already control the current Python environment, the shortest path remains:

python -m pip install --upgrade qzx
qzx version --json
qzx

For a standalone CLI, pipx keeps QZX and its Python dependencies isolated from your projects and other Python tools:

pipx install qzx
qzx version --json

Already have pipx and only want to try QZX without keeping it?

pipx run --spec qzx qzx version

If pip reports externally-managed-environment, do not force the system Python with sudo pip or --break-system-packages; install pipx using your platform's supported method and use the isolated route above. Use the browser-first QZX installation hub to choose a route and reach a first success, or the complete technical installation guide for PATH recovery, updates, and removal.

The no-argument welcome is deliberately fast and read-only. It gives every person or agent the same first-minute path without probing disks, memory, or CPU:

qzx getCurrentDateTime --output-format iso --json
qzx listCommands file
qzx help findFiles

The first command proves the JSON result contract with a bounded timestamp; the second filters the installed catalog; the third exposes parameters, examples, maturity, and safety before execution. Use qzx welcome true only when detailed host information is explicitly wanted.

Continue with Codex, Claude Code, Gemini CLI, or another coding agent

A terminal-capable agent can call QZX as a documented CLI; no dedicated QZX plugin is required. The measurable AI-agent quickstart shows a read-only project briefing workflow and a copyable instruction block for project mechanisms such as AGENTS.md, CLAUDE.md, and GEMINI.md. The installed QZX catalog remains the source of truth for available commands.

This source release is QZX 0.2.2.0.12 and requires Python >=3.11. The published QZX distribution uses pip's normal installation channel while the product itself remains Alpha software. PyPI is authoritative for the published package, and qzx version --json is authoritative for what is installed.

QZX supports standard CPython 3.11 or newer. The complete cross-platform certification matrix uses standard CPython 3.13.x; experimental free-threaded CPython builds, PyPy, and other implementations are not certified.

The 3.11 floor is intentional product policy, not a temporary compatibility accident. It was adopted after the QZX test suite passed on standard CPython 3.11, 3.12, 3.13, and 3.14, because requiring a newer interpreter without a technical need would add avoidable installation friction for existing projects, servers, CI runners, and automation. CPython 3.13 remains the certification runtime to keep the operating-system matrix deep without multiplying every OS by every supported Python series. Maintainers should not raise Requires-Python above 3.11 merely to use newer syntax or simplify development; see the Python compatibility policy.

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

Get a useful project briefing

From the root of a project you want to understand, run:

qzx diagnoseProject .
qzx diagnoseProject . --json

The terminal report prioritizes observed findings and remediation, summarizes technologies, dependencies and Git state, and lists discovered test, lint and build commands. The JSON mode keeps the full structured evidence for an agent or automation. Project-owned scripts are never executed by this inspection; success: true means the diagnosis completed, not that tests passed.

Use the project briefing workflow to combine this with a bounded directory tree and language inventory. No account, API key or paid feature is required.

Triage storage without deleting anything

When a disk is getting full, QZX can turn capacity, large-file, and verified duplicate evidence into one read-only diagnosis:

python -m pip install --upgrade qzx
qzx diagnoseStorage . --json

diagnoseStorage measures the filesystem containing the target path, returns a bounded largest-file view, confirms duplicate groups with size + SHA-256 + byte-for-byte comparison, and produces prioritized review guidance. It never counts a merely large file as reclaimable space and never deletes anything. Use --include-duplicates false for a faster first pass; getDiskSpace, findFiles, and findDuplicateFiles remain independently available when you want to compose the probes yourself.

Physical-disk health is intentionally separate. When smartctl is available and you know the disk identifier, use for example qzx getDiskHealth PhysicalDrive0 --json on Windows or qzx getDiskHealth sda --json on Linux.

See the complete storage-triage workflow for tuning, result semantics, the underlying probes, platform notes, and links to the public disk-space guide.

Read text in bounded pages (development preview)

The development checkout adds lossless Unicode reads, byte budgets, explicit continuation and file-change guards to readFile. This upgrade is not in the published 0.2.2.0.9 package. Try the self-checking example from this checkout:

python examples/read_file_pages.py --demo --page-bytes 32

It reads a generated multilingual UTF-16 document through real QZX CLI calls and verifies the exact text without using personal data or an external service. See the complete workflow in English or Spanish, including completion checks, strict encoding, active-log limitations, and an executable bounded-memory consumer.

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.

This transport-independent core is published as the open QZX Result Contract v1, with a downloadable JSON Schema. Other tools may implement the result envelope without adopting the QZX command vocabulary or runtime. Start with the 5-minute adoption quickstart; the full adoption guide includes revision-specific interoperability profiles for MCP 2025-06-18, 2025-11-25, and 2026-07-28. All three carry the QZX contract object in structuredContent, make its stable core visible through MCP outputSchema, and keep completed failures consistent with isError. Receipts record whether outputSchema embeds the canonical schema (canonical_ref, canonical_inline, or canonical_allof) or uses the weaker, SDK-portable structural_core mode whose submitted runtime evidence is validated against the complete Result Contract. The 2026-07-28 profile additionally requires resultType: "complete"; the two 2025 profiles do not invent that field because MCP did not require it yet. Compatibility describes the result contract; it does not imply endorsement, safe execution, or complete command parity.

The CLI validates its final envelope before printing it. Validate a saved or piped document from a source checkout without a third-party dependency:

python scripts/validate_result_contract.py result.json
qzx getCurrentDateTime --output-format iso --json \
  | python scripts/validate_result_contract.py -

Run the positive and negative reference fixtures with:

python scripts/run_result_contract_conformance.py

Validate a completed MCP tool result and its tool definition with the dependency-free MCP profile validator. It defaults to the newest supported revision; use --spec-version when the evidence comes from an older MCP server:

python scripts/validate_mcp_result_contract.py mcp-result.json \
  --tool-definition mcp-tool-definition.json

python scripts/validate_mcp_result_contract.py mcp-result.json \
  --spec-version 2025-11-25 \
  --tool-definition mcp-tool-definition.json

For a reviewable implementation or pilot, validate one real success and one real failure together and generate a deterministic receipt containing the input SHA-256 digests plus fingerprints of the exact QZX contract schema, receipt schema, core validator, MCP validator, and evidence validator used for the verdict:

python scripts/validate_result_contract_evidence.py \
  --profile mcp-2026-07-28 \
  --success result-contract-evidence/success.json \
  --failure result-contract-evidence/failure.json \
  --tool-definition result-contract-evidence/tool-definition.json \
  --report result-contract-evidence/qzx-conformance.json

The generated receipt self-identifies the public QZX Result Contract Conformance Receipt v1 schema, so its structure can be checked independently with JSON Schema 2020-12. Its validation_materials fingerprints let reviewers tie the verdict to byte-identical source artifacts from a pinned QZX revision. A schema-valid receipt can still record failed conformance.

The same check is available as the reusable repository-root QZX Result Contract conformance Composite Action for external GitHub repositories, so callers can use the normal owner/repository@sha form; the Action also exposes the exact contract schema digest as contract_schema_sha256. Locked, executable reference integrations cover the official MCP TypeScript, Python, Go, C#, and Java SDKs without counting QZX-maintained examples as independent adoption. Independent implementations and bounded pilots can follow the adoption guide. If an experiment is not ready for a formal adoption report, use the short Result Contract pilot or integration help form to start with one real tool without claiming adoption. Organizations may also fund a bounded public interoperability pilot under the sponsorship and independence policy. Funding a pilot never counts as adoption or certification: only public, reviewable, authorized independent evidence is listed in ADOPTERS.md. QZX itself is the reference implementation and is not counted as independent adoption.

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.

Golden Core is a focus cohort, not a maturity claim

The QZX Golden Core selects 15 high-frequency read-only commands for deeper tests, contract review, captured evidence, and platform validation. All selected commands remain Alpha until their individual evidence supports promotion. Verify the packaged registry with:

python scripts/verify_golden_core.py

The repository's existing Windows, Linux, and macOS matrix also captures one sanitized 15-command evidence record per runner and validates a combined cross-platform summary. The capturer uses only disposable fixtures and an authorized loopback HTTP endpoint; it does not request secrets or private project data. Independent contributors can use the Golden Core platform evidence form after manually reviewing the generated JSON for private data.

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 getSystemInfo --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 diagnoseStorage . --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.

Develop QZX from source

The published package and the development checkout may differ while a new release is being prepared. Ask the installed runtime for its actual command catalog instead of assuming a command is present:

qzx version --json
qzx listCommands --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 accept standard CPython 3.11 or newer and prefer the cross-platform certification runtime, CPython 3.13, when multiple managed runtimes are available. QZX_PYTHON or an active compatible environment can select another supported standard runtime explicitly. 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 --upgrade "qzx[filetype]" or python -m pip install --upgrade "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 uses two deliberately low-frequency signals: at most one version_first_run event per QZX version and random local installation identifier, plus closed 10-day usage_window summaries. Usage is aggregated locally before transmission. A closed window contains canonical command names with invocation counts and accumulated/max execution time, plus coarse counts/days for TTY, foreground-terminal and recent-OS-input evidence. The server also observes the request IP and receipt time.

QZX never sends command arguments, terminal input or output, paths, environment values, usernames, hostnames, file contents, key values, pointer coordinates, trajectories, clicks, raw HID events, 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. Read the technical telemetry and deletion policy and the public security model.

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. Submit a canonical cohort capture through the Golden Core evidence form, or use the general platform-evidence form for any other command or bounded observation.

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, support, funding, issue, and CI configuration.

Support and professional work

If a workflow is useful, support continued QZX development or discuss an integration or automation with Alejandro Sánchez. The open-source CLI remains free; professional scope and acceptance criteria are agreed separately.

Professional-service requests return a QZX reference and stay in a private intake queue. The canonical intake route remains https://qzx.yumbale.com/en/professional-services#request; the README CTA adds only first-party qzx_ref attribution. Operational alerts contain only that reference and the private-admin link, never requester contact details or request content.

Contributing

Start with the contribution guide and project philosophy. Preserve the structured output contract, add proportional tests, and keep published and development availability explicit. For usage help and the right route for questions, bugs, or private reports, see the support guide.

License: Apache-2.0. The attribution notice is in NOTICE. See how to contribute, how to cite QZX, machine-readable CodeMeta 3.1, 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.