development · Command reference

`qzx formatCode`

What it does

Formats source code files by auto-detecting language and invoking the right formatter

Canonical command: formatCode

Accepted aliases: fmtCode, codeFmt, formatSource

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

No documented network use

No inherent elevation requirement

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

Exact syntax

qzx formatCode <path> [language] [dry_run] --json

Parameters

Name	Type	Required	Default	Description
path	str	Yes	Not declared	File or directory to format
language	str	No	""	Force a specific language (python, javascript, typescript, rust, go, php, c, cpp). Auto-detected by default.
dry_run	str	No	"false"	Check if files would be changed without writing (true/false)

Input examples

qzx formatCode src/

Format all supported source files in src/

qzx formatCode src/main.py

Format a single Python file with black

qzx formatCode src/ python

Format only Python files in src/

qzx formatCode src/ "" true

Dry-run format to see which files would change

For the complete structured payload, add --json: qzx formatCode <path> [language] [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 formatCode src/ --json

{
    "success": true,
    "message": "Formats source code files by auto-detecting language and invoking the right formatter. In this illustrative example, the command completed successfully.",
    "all_succeeded": true,
    "dry_run": true,
    "failed": [
        "Example value"
    ],
    "failed_count": 3,
    "formatted": [
        "Example value"
    ],
    "formatted_count": 3,
    "path": "C:\\project\\example.txt",
    "skipped": [
        "Example value"
    ],
    "skipped_count": 3,
    "total_files": 3,
    "unavailable_tools": []
}

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"
        },
        "all_succeeded": {
            "type": "boolean"
        },
        "dry_run": [],
        "error": {
            "type": "string"
        },
        "failed": {
            "type": "array"
        },
        "failed_count": {
            "type": "integer"
        },
        "formatted": {
            "type": "array"
        },
        "formatted_count": {
            "type": "integer"
        },
        "path": [],
        "skipped": {
            "type": "array"
        },
        "skipped_count": {
            "type": "integer"
        },
        "total_files": {
            "type": "integer"
        },
        "unavailable_tools": {
            "type": "array"
        }
    },
    "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 isolated disposable target.

Evidence and provenance

Implementation: src/qzx/commands/development/format_code.py
Tests: tests/test_development_commands/test_format_code.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