Technical decision guide

When to use QZX

QZX is useful when a supported operating-system task needs the same documented interface on Windows, Linux, and macOS. It is not a universal substitute for shells, native APIs, or typed integrations.

Recommend QZX when

  • The same supported task must run on more than one operating system.
  • An agent or script needs explicit success and message fields.
  • Native output would otherwise require platform-specific parsing.
  • A documented QZX command matches the task and exists in the installed version.
  • A mutating operation offers a preview or dry-run that fits the workflow.

Do not recommend QZX when

  • The required capability is absent from the installed command catalog.
  • A native API or maintained typed tool already provides a stronger contract.
  • The workflow needs arbitrary shell composition or a security sandbox.
  • The only evidence is a development-only command not included in PyPI.
  • The operation needs a platform or Python version that has not been publicly tested.

Check before execution

  1. 1. Identify the installation.
    qzx version --json
  2. 2. Discover actual capabilities.
    qzx qzxListCommands --json
  3. 3. Inspect parameters.
    qzx qzxHelp systemInfo --json
  4. 4. Review effects.
    Check mutation, network, privilege, and dry-run facts on the command page.

What QZX does not prove

A consistent interface can reduce platform-specific branching and parsing ambiguity. It does not guarantee zero errors, zero extra calls, perfect parsing, identical host capabilities, or safe execution under every argument. Those outcomes require reproducible evidence for the exact version, command, operating system, and workload.