Command-line interface

gzim is the native runtime, checker, REPL, project bootstrapper, and compatibility exporter.

Run a program

gzim app.gzim [arguments...]
gzim run app.gzim [arguments...]

Both forms parse, semantically check, and execute the program in the current native process. Arguments are exposed through the global args stack.

Check a program

gzim check app.gzim

Runs the lexer, parser, and semantic analyzer without executing the program. A successful check exits with status 0. Caps exit nonzero and include file, line, and column information.

Start the REPL

gzim repl

Enter code at vibe>. A blank line executes the accumulated session. Ctrl+D exits.

Initialize a project

mkdir my-vibe && cd my-vibe
gzim init

Creates a starter main.gzim and gzim.toml without replacing existing files.

Manage packages

gzim add cool https://github.com/example/cool.git#v1.0.0
gzim install
gzim packages
gzim remove cool

Dependencies are project-local and may come from Git or a local directory. See Packages and projects.

Inspect the runtime

gzim doctor

Prints the installed version, confirms that the runtime is native and Python-free, and shows the compiled target OS and CPU.

Print the version

gzim --version

Convert source files (2.0.3 preview)

gzim convert main.gzim --to py
gzim convert main.py --to gzim
gzim convert main.py --to gzim -o converted.gzim
gzim convert main.gzim --to py --force
gzim convert --help

The source extension must be .gzim when targeting py, or .py when targeting gzim. By default, the result uses the source directory and basename with the target extension. -o (or --output) selects another path; its parent directory must exist.

Existing output files require --force. Conversion never overwrites its source, including aliases, and rejects symbolic-link outputs. The result is generated and checked before a temporary file is written beside the destination and moved into place. Conversion errors leave existing output untouched and exit with status 1. This command writes one source file; use emit-python when a Python source-map sidecar is needed.

Python-to-Genzimnify is a limited preview requiring Python 3.8+ on PATH. It parses Python without executing it, normalizes formatting, and rejects unsupported constructs with source locations. Exporting Python requires no Python installation. See source conversion support and limitations.

Optional Python export

gzim emit-python app.gzim

Writes app.py and a source map for interoperability with existing Python ecosystems. This command is optional: normal execution never invokes this backend. The legacy spelling gzim build remains as a compatibility alias in 2.0.

Exit codes

Compatibility executable

Release packages use gzim. Source builds also keep gzimc for existing integrations; it routes to the same native CLI.