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])' helloRuns a native program directly from the command line. Following arguments are available through args.
Start the REPL
gzim replEnter code at vibe>. A blank line executes the accumulated session. Ctrl+D exits.
Initialize a project
mkdir my-vibe && cd my-vibe
gzim initCreates 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 coolDependencies are project-local and may come from Git or a local directory. See Packages and projects.
Inspect the runtime
gzim doctorPrints 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 --offlineThe 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 --helpThe 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-mapWrites 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.
Running the generated file requires Python. Running gzim app.gzim uses the native Genzimnify runtime.
Exit codes
| Code | Meaning |
|---|---|
0 | Program or command completed successfully. |
1 | Syntax, semantic, runtime, file, or CLI error. |
| Custom | system.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.