The design case
Why QZX exists
AI agents and automation benefit from explicit success, descriptive messages and predictable fields. QZX offers that interface for its documented operations while leaving unsupported or platform-specific work to native tools.
Fewer platform branches
For supported commands, the same QZX name and argument model can replace separate PowerShell, GNU/Linux and macOS shell branches. This reduces duplicated instructions; it does not erase host-level differences.
Two deliberate output modes
The default is human-readable. --json requests the complete structured object for programs and agents. Automation should not infer JSON from the default presentation.
Discoverable availability
The catalog labels commands included in PyPI 0.2.2.0.2 separately from development-only commands. Each reference also identifies platforms, parameters, aliases and safety characteristics from the inspected implementation.
Visible trust boundaries
QZX executes with the current user's permissions. Some operations mutate state or invoke native tools. The security page explains backups, previews, bypasses and telemetry rather than treating a unified interface as automatic safety.
A practical decision rule
Use QZX when a documented command covers the operation and a consistent CLI contract is useful. Prefer a native API, a typed integration or the shell when you need platform-specific capabilities, streaming, exact native semantics, or a stronger security boundary.