Tools

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. Unhandled runtime errors show a call stack with function names and source file locations, followed by the error category and message.

Check a program

gzim check app.gzim
gzim check .

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.

Directory checks recursively visit .gzim files in sorted order, report all failures, and skip directory symlinks, .git, .gzim, build, dist, target, node_modules, .venv, and venv. An empty directory exits with status 1.

Run inline code

gzim eval 'yap(1 + 2)'
gzim eval 'yap(args[0])' hello

Runs a native program directly from the command line. Following arguments are available through args.

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 install --locked
gzim update cool
gzim update
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, executable path, current directory, and optional Python executable location.

Print the version

gzim --version
gzim --version --offline

The local version stays on stdout. A newer stable GitHub release triggers platform-specific update instructions on stderr. Checks use curl with a two-second transfer timeout; unavailable curl, network errors, and rate limits do not fail the command. No installer is run automatically. Use --offline or set GZIM_NO_UPDATE_CHECK=1 to disable network access. Custom installations should set GZIM_INSTALL_ROOT when rerunning the installer; use gzim doctor afterward to verify the executable path.

Convert source files

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 main.py --to gzim --check
gzim convert main.gzim --to py --source-map
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. Add --source-map with --to py to write an additional .py.gzmap sidecar. Both destinations are checked before writing; replacement is atomic per file, not across the pair. --check validates conversion without touching output files and cannot be combined with -o, --force, or --source-map.

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 convert app.gzim --to py --source-map

Writes app.py and a source map for interoperability with existing Python ecosystems. This command is optional: normal execution never invokes this backend. The duplicate gzim build and gzim emit-python commands were removed in 2.0.4 and now report the replacement command.

Export runtime requirement

Running the generated file requires Python. Running gzim app.gzim uses the native Genzimnify runtime.

Exit codes

CodeMeaning
0Program or command completed successfully.
1Syntax, semantic, runtime, file, or CLI error.
Customsystem.exit(code) exits with the requested status.

Compatibility executable

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