development · Command reference
qzx deployProject
What it does
Previews or deploys one explicit artifact over SSH using a verified remote backup, SHA-256 validation, atomic promotion, health checks, and automatic rollback
Command maturity: Alpha
Available for real use and feedback while its interface and behavior can still evolve. This is the current development-checkout assessment. Every future immutable release tag preserves the exact assessment shipped by that version. Available in PyPI 0.2.2.0.8. This page documents the 0.2.2.0.8 alpha development checkout.
Behavior and built-in protections
Live mode applies the changes you request
Preview mode available
Uses a native tool when needed
Uses network access for the documented task
Uses your current permissions; results can vary
Preview-only by default and limited to one explicit artifact. SSH uses strict host-key checking and can consume an explicit known_hosts file. A live deployment creates fail-closed local and verified remote backups, uploads to an isolated stage, checks every regular file with SHA-256, promotes on the same filesystem, requires an HTTP(S) health URL without credentials, query, or fragment, and automatically restores the previous remote state on failure. Health expectation text is never echoed. It never builds, changes permissions, executes caller-provided remote commands, restarts services, uses delete synchronization, or automatically prunes returned recovery paths.
QZX creates a recovery archive before live changes; use --dangerously-bypass-approvals-and-sandbox/--yolo only when you deliberately choose to skip it.
Uses the documented external service and shares only the data described below.
This safety classification was reviewed by OpenAI GPT-5.6 Pro against implementation digest sha256:240e73f477e23633addd75a0fcc9da0ec756665594164338a747bec91d09d58d on 2026-08-25.
Exact syntax
qzx deployProject <target_host> [path] <target_path> [port] [ssh_key] [known_hosts] [health_url] [health_expect] [health_attempts] [health_interval] [health_timeout] [deployment_id] [dry_run] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| target_host | str | Yes | Not declared | SSH destination in host or user@host form |
| path | str | No | "." | Explicit local artifact directory to deploy; QZX never builds it or falls back to the project root |
| target_path | str | Yes | Not declared | Absolute remote directory that will become the active release |
| port | int | No | 22 | SSH port |
| ssh_key | str | No | Not declared | Optional local SSH private-key file |
| known_hosts | str | No | Not declared | Optional explicit OpenSSH known_hosts file used to verify the remote server identity |
| health_url | str | No | Not declared | HTTP(S) endpoint without credentials, query, or fragment; required for a live deployment and checked after promotion |
| health_expect | str | No | Not declared | Optional text that the health response body must contain |
| health_attempts | int | No | 5 | Health-check attempts from 1 to 20 |
| health_interval | float | No | 2 | Seconds between health attempts, from 0 to 30 |
| health_timeout | float | No | 5 | Timeout per health attempt, from 0.1 to 30 seconds |
| deployment_id | str | No | Not declared | Optional stable identifier for audit and recovery paths |
| dry_run | bool | No | true | Preview the exact artifact and remote paths without connecting |
Input examples
qzx deployProject --target-host [email protected] --path ./dist --target-path /srv/example/currentInspects the artifact and previews every remote recovery path
qzx deployProject --target-host [email protected] --path ./dist --target-path /srv/example/current --health-url https://example.test/health --health-expect "ready" --dry-run falseBacks up the artifact, then performs a verified deployment
For the complete structured payload, add --json: qzx deployProject <target_host> [path] <target_path> [port] [ssh_key] [known_hosts] [health_url] [health_expect] [health_attempts] [health_interval] [health_timeout] [deployment_id] [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] --path ./dist --target-path /srv/example/current --json
{
"success": true,
"message": "Previews or deploys one explicit artifact over SSH using a verified remote backup, SHA-256 validation, atomic promotion, health checks, and automatic rollback. In this illustrative example, the command completed successfully.",
"meta": {
"command": "deployProject",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 0,
"schema_version": 1
},
"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",
"meta"
],
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"meta": {
"type": "object",
"required": [
"command",
"command_maturity",
"duration_ms",
"schema_version"
],
"properties": {
"command": {
"type": "string"
},
"command_maturity": {
"type": "object",
"required": [
"stage",
"label",
"sequence",
"public_executable",
"stability",
"summary",
"promotion_review_required",
"assessment_scope"
],
"properties": {
"stage": {
"type": "string"
},
"label": {
"type": "string"
},
"sequence": {
"type": "integer"
},
"public_executable": {
"type": "boolean"
},
"stability": {
"type": "string"
},
"summary": {
"type": "string"
},
"promotion_review_required": {
"type": "boolean"
},
"assessment_scope": {
"type": "string"
},
"note": {
"type": "string"
},
"review": {
"type": "object",
"required": [
"reviewed_on",
"rationale",
"evidence"
],
"properties": {
"reviewed_on": {
"type": "string",
"format": "date"
},
"rationale": {
"type": "string"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"replacement": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"duration_ms": {
"type": "number"
},
"schema_version": {
"type": "integer"
}
},
"additionalProperties": true
},
"details": []
},
"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
- Documentation channel
- Development documentation 0.2.2.0.8 · main · sha256:9aa902dfb6b006017e52972bf7871fef49b03ec24ff80741231d743d0354bfc2
- Availability
- 0.2.2.0.8 or earlier
Keep exploring
Related commands
These commands also belong to the development category. Compare them to choose the operation that best fits your task.
qzx compareFilesCompares text files line by line and binary files by exact bytes and SHA-256qzx diagnoseProjectInspects project technologies, dependencies, validation workflows, Git state, source quality, and large files without executing project scriptsqzx cleanDevelopmentArtifactsFinds development caches, dependency directories, and generated build artifacts; preview is the defaultqzx findUnusedCodeFinds functions, classes, and exports with no statically visible references so they can be reviewed for removal