development · Command reference

`qzx deployProject`

What it does

Handles local build, remote backup, synchronization, permission setup, service reload, health check, and automatic rollback on failure

Canonical command: deployProject

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

Documented dry-run parameter

May invoke native programs

May use the network

Outcome may depend on permissions

Applying a deployment sends local build artifacts to the operator-selected SSH target. It must create a remote backup before synchronization and roll back when the health check fails.

Before mutation, QZX creates a recovery archive; --dangerously-bypass-approvals-and-sandbox/--yolo explicitly skips it.

This command shares the documented data with an external service.

This safety classification was reviewed against implementation digest sha256:19b3f10d45060d4e618ce54120bbbe95f80374a4663a3b193b7e4ad4ff754173 on 2026-07-25.

Exact syntax

qzx deployProject <target_host> [path] <target_path> [port] [ssh_key] [health_url] [restart_cmd] [skip_build] [dry_run] --json

Parameters

Name	Type	Required	Default	Description
target_host	str	Yes	Not declared	Target SSH host (e.g. [email protected] or hostname)
path	str	No	"."	Path to local project root directory (default: '.')
target_path	str	Yes	Not declared	Target path on remote host (e.g. /var/www/html/)
port	int	No	22	SSH Port (default: 22)
ssh_key	str	No	Not declared	Path to SSH Private Key (optional)
health_url	str	No	Not declared	Health check URL (optional)
restart_cmd	str	No	Not declared	Remote command to restart service (e.g. nginx -s reload, pm2 restart all) (optional)
skip_build	bool	No	false	If True, skip running local build scripts (default: False)
dry_run	bool	No	true	If True, only show commands that would be executed without running them (default: True)

Input examples

qzx deployProject --target_host [email protected] --target_path /var/www/html/ --port 2237

Previews deployment of the current workspace

qzx deployProject --target_host deploy@host --target_path /var/www/html/ --health_url https://site.com --dry_run True

Simulates project deployment with health check

qzx deployProject --target_host deploy@host --target_path /var/www/html/ --dry_run false

Backs up the local project and executes deployment

For the complete structured payload, add --json: qzx deployProject <target_host> [path] <target_path> [port] [ssh_key] [health_url] [restart_cmd] [skip_build] [dry_run] --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 deployProject --target_host [email protected] --target_path /var/www/html/ --port 2237 --json

{
    "success": true,
    "message": "Handles local build, remote backup, synchronization, permission setup, service reload, health check, and automatic rollback on failure. In this illustrative example, the command completed successfully.",
    "details": {
        "summary": "Additional structured context is included here."
    }
}

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"
        },
        "details": [],
        "error": {
            "type": "string"
        }
    },
    "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 an authorized endpoint or reviewed fixture.

Evidence and provenance

Implementation: src/qzx/commands/development/deploy_project.py
Tests: tests/test_development_commands/test_deploy_project.py
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 development category. Compare them to choose the operation that best fits your task.

Explore all QZX commands