system · Command reference

`qzx runScript`

What it does

Executes a script with parameters

Canonical command: runScript

Accepted aliases: None

Case-sensitive: no

Included in the published package

Available in PyPI 0.2.2.0.2. This page documents the 0.2.2.0.2 alpha development checkout.

Safety and effects

Can mutate state

No documented dry-run parameter

May invoke native programs

No documented network use

Outcome may depend on permissions

Has no restorable filesystem target, so it executes a user-selected local script only with --dangerously-bypass-approvals-and-sandbox/--yolo. Review that script and its arguments first.

High-risk execution requires --dangerously-bypass-approvals-and-sandbox or --yolo.

This safety classification was reviewed against implementation digest sha256:560a80439d7634abdd782dbc629686e9835e9faeb8d5e66483c6312d19f22bbf on 2026-07-24.

Exact syntax

qzx runScript <script_path> [args] --json

Parameters

Name	Type	Required	Default	Description
script_path	str	Yes	Not declared	Path to the script to execute
args	list	No	[]	Arguments to pass to the script

Input examples

qzx runScript myscript.py --yolo

Execute a Python script when its mutation targets cannot be determined

qzx runScript myscript.py arg1 arg2 --yolo

Execute with arguments when mutation targets cannot be determined

qzx runScript script.sh --dangerously-bypass-approvals-and-sandbox

Execute a shell script without a safety backup

For the complete structured payload, add --json: qzx runScript <script_path> [args] --json

Representative output example

This illustrative JSON is derived from the current implementation-backed result contract. It shows what the command can return without claiming a recorded execution; values vary with inputs, host, permissions, and optional tools.

Example command: qzx runScript myscript.py --yolo --json

{
    "success": true,
    "message": "Executes a script with parameters. In this illustrative example, the command completed successfully.",
    "args": [
        "--check"
    ],
    "execution": {
        "command": "qzx example --json",
        "exit_code": "Example value"
    },
    "output": "Command completed successfully with structured details.",
    "script": "Example value",
    "script_info": {
        "name": "Example value",
        "directory": "C:\\project\\example.txt",
        "size_bytes": 4096,
        "type": "file"
    },
    "script_type": "file",
    "summary": {
        "status": "healthy",
        "items_checked": 4
    }
}

View the JSON result contract

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "args": [],
        "error": {
            "oneOf": [
                {
                    "type": "null"
                },
                {
                    "type": "string"
                }
            ]
        },
        "execution": {
            "type": "object",
            "properties": {
                "command": [],
                "exit_code": []
            },
            "additionalProperties": true
        },
        "output": [],
        "script": [],
        "script_info": {
            "type": "object",
            "properties": {
                "name": [],
                "directory": [],
                "size_bytes": [],
                "type": []
            },
            "additionalProperties": true
        },
        "script_type": [],
        "summary": []
    },
    "additionalProperties": true
}

Errors and limits

The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.

QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.

Evidence workflow: requires a controlled privileged environment.

Evidence and provenance

Implementation: src/qzx/commands/system/run_script.py
Tests: No command-specific test file with the same module name was found; this does not prove that all coverage is absent.
Documentation channel: Development documentation 0.2.2.0.2 · main · sha256:319b16857a87636ebc3b89734cc040a737bb56194464fca33ce73bdae2043096
Availability: 0.2.2.0.2 or earlier

Keep exploring

These commands also belong to the system category. Compare them to choose the operation that best fits your task.

Explore all QZX commands