Skip to content

cli.md

Latest commit

 

History

History
209 lines (141 loc) · 4.99 KB

cli.md

File metadata and controls

209 lines (141 loc) · 4.99 KB
Raw

CLI reference

Important

Alpha Status: This project is currently under active development. This document is intended for alpha users, contributors, and early adopters.

Prerequisites

Before building or running the toolchain, ensure JDK 25 (Eclipse Temurin or any compatible OpenJDK distribution) is installed.

To run the CLI on your machine, you must currently build it from source. In the future, a more convenient installation method will be available.

You will also need a terminal or console (such as bash, zsh, or PowerShell) open inside the project's main folder so you can run the commands below.

Build

As the first step, build the CLI from the root directory:

./gradlew ":cli:installDist"

After running this command, the zigocracy launcher should appear in the cli/build/install/zigocracy/bin/ folder.

Now that the build step is complete, we can prepare the execution environment.

Configure the command shortcut

We would love to just run the short zigocracy command directly, but our terminal environment does not know where to find the new executable yet.

Let’s fix this by temporarily registering the zigocracy command for your current terminal window. Don't worry, this change is strictly temporary and won't affect any other terminal windows or your global system settings.

If you are on Windows inside PowerShell, run this command:

Set-Alias -Name zigocracy -Value "${PWD}\cli\build\install\zigocracy\bin\zigocracy.bat"

If you are on Linux or macOS, run this command:

alias zigocracy="${PWD}/cli/build/install/zigocracy/bin/zigocracy"

Now that the shortcut is active, you are ready to run the toolchain.

Commands

check-zon

This command checks whether your ZON files are well-formed and highlights any syntax errors.

Syntax

zigocracy check-zon <paths>...

Examples

Check a single file:

zigocracy check-zon build.zon

Check an entire folder recursively:

zigocracy check-zon ./src

Check multiple files and folders at once:

zigocracy check-zon package.zon build.zon ./internal/config

File validation

Here is how a successful syntax check looks:

─── build.zon ───
  ✓ Valid ZON

If the parser encounters a syntax error, it points directly to the issue:

─── libs/zap/build.zon ───
  ✗ Expected '}', got ''
    at line 12, column 5
    author = "zig-team"
    ^── here

Multi-file summaries

If the command evaluates more than one file, it appends a brief summary at the bottom to show the overall results.

─── Summary ───
  ✓ 2 files: 1 passed, 1 failed

Exit codes

  • 0 — Success. The tool validated all files, and found no syntax errors.
  • 1 — Syntax error. One or more files contain broken or invalid ZON syntax.
  • 2 — No files found. Scanned paths contain no .zon files to validate.

highlight-syntax

Print Zig source files with full syntax highlighting like a cat tool.

Syntax

zigocracy highlight-syntax [OPTIONS] <paths>...

Options

  • --theme — Specify terminal visual scheme preference (light or dark). Default: dark.

Examples

Highlight a single file:

zigocracy highlight-syntax main.zig

Highlight multiple files and directories at once:

zigocracy highlight-syntax src/ math.zig build.zig

Force a specific theme configuration:

zigocracy highlight-syntax --theme=light main.zig

Exit codes

  • 0 — Success. The tool processed and printed all specified Zig files.
  • 2 — No files found. Scanned paths contain no .zig files to process.

check-syntax

Check Zig source files for syntax errors and report them.

Syntax

zigocracy check-syntax [OPTIONS] <paths>...

Options

  • --theme — Specify terminal visual scheme preference (light or dark). Default: dark.
  • --error-style — Format for reporting syntax errors (gnu, rich, or rich-<N> where <N> is the context line count). Default: rich (evaluates to 3 lines of context).

Examples

Check a single file with default reporting options:

zigocracy check-syntax main.zig

Scan an entire directory recursively:

zigocracy check-syntax src/

Print compiler diagnostics in the standard single-line GNU format:

zigocracy check-syntax --error-style=gnu src/

Change the number of surrounding code lines displayed for each error:

zigocracy check-syntax --error-style=rich-5 src/

Exit codes

  • 0 — Success. All analyzed files are syntactically correct.
  • 1 — Syntax error. One or more files contain invalid syntax or failed processing.
  • 2 — No files found. Scanned paths contain no .zig files to process.