Skip to main content

Technical decision guide

When to use QZX instead of shell or native APIs

QZX is useful when an AI agent or automation needs the same documented operating-system task 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 listCommands --json
  3. 3. Inspect parameters.
    qzx help getSystemInfo --json
  4. 4. Review effects.
    Check mutation, network, privilege, and dry-run facts on the command page.

From decision to value

Try a read-only workflow now

You do not need to design a new automation to see whether QZX helps. Start with an existing diagnostic workflow, inspect the JSON, and keep every cleanup decision outside the command sequence.

Storage triage

Measure capacity, surface large files, and confirm duplicates in one read-only request. Large files are never treated as automatically reclaimable.

qzx diagnoseStorage . --json
Open the complete disk-space workflow →

AI-agent project briefing

Give an agent structured project evidence before asking it to change code.

qzx diagnoseProject . --json
Open the AI-agent quickstart →

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.