On this page
Build the interpreter, create hello.zhex, and run it from your terminal. You need Git and Go 1.23 or newer — both come from your system’s package manager.
Install the tools
Linux — use your distribution’s package manager:
sudo apt install git golang-go # Debian, Ubuntu
sudo dnf install git golang # Fedora
sudo pacman -S git go # Arch
Check go version. If your distribution’s Go is older than 1.23, install the current release from go.dev/dl instead.
macOS — use Homebrew:
brew install git go
Windows — run PowerShell and use winget:
winget install Git.Git
winget install GoLang.Go
With Scoop or Chocolatey, scoop install git go or choco install git golang work too. Open a new terminal after installing so both tools are on your PATH. If you use WSL, follow the Linux steps unchanged inside a WSL shell.
Build and run
Clone the repository, build the interpreter once, and add it to this terminal’s PATH.
Linux and macOS:
git clone https://github.com/desireco/zhex.git
cd zhex
go build -o bin/zhex ./cmd/zhex
export PATH="$PWD/bin:$PATH"
Windows (PowerShell):
git clone https://github.com/desireco/zhex.git
cd zhex
go build -o bin\zhex.exe .\cmd\zhex
$env:Path = "$PWD\bin;$env:Path"
The PATH change applies to the current terminal only. In a new terminal, run the last line again after changing to the repository.
To make the command permanent, install the binary into a bin folder with just:
just install
The recipe builds bin/zhex and copies it to ~/.local/bin, creating the folder when missing; pass any bin directory you choose to change the destination — system paths like /usr/local/bin need sudo. ~/.local/bin must be on your PATH — if a new terminal cannot find zhex, add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc, ~/.zshrc, or your shell’s profile and open a new terminal. The plain build plus export PATH above keeps working without just.
Windows (PowerShell): just install needs a POSIX shell; build as shown above, copy the executable, and put its folder on Path:
New-Item -ItemType Directory -Force "$env:USERPROFILE\.local\bin" | Out-Null
Copy-Item bin\zhex.exe "$env:USERPROFILE\.local\bin\"
Add %USERPROFILE%\.local\bin to Path in “Edit the system environment variables” and open a new terminal.
Create and run a program
Create hello.zhex in the repository root with this line, using any text editor — Notepad works:
print("Hello, Zhex!")
Run it with zhex run — the command is the same on every platform:
zhex run hello.zhex
Hello, Zhex!
A program runs its top-level statements. A file whose top level has none may instead define word main with no parameters; zhex run and zhex compile invoke it automatically as the entry point.
Read the program
Replace the file with a word that reads a name and sends it through a flow:
word greet(name: String) -> String
"Hello, " + name + "!"
let name = read-line "Your name: " try
flow name
greet
print
Run zhex run hello.zhex again. Enter Ada at the prompt:
Your name: Ada
Hello, Ada!
greet accepts and returns a String. The word’s final expression is its result. read-line can fail, so try handles its Result; flow passes the name to greet, then passes the greeting to print. Zhex checks word names, parameter types, and each step of the flow before execution.
For a file you already have, run zhex run examples/hello.zhex. With piped input, the terminal does not echo the typed text:
printf 'Ada\n' | zhex run examples/hello.zhex
'Ada' | zhex run examples\hello.zhex
Your name: Hello, Ada!
Try the REPL
Start an interactive session. Parenthesized calls remain available; simple calls may also use comma-separated arguments at a complete expression boundary, so print 1 + 1 prints 2:
zhex repl
Define a word and send a value through it. The terminal editor inserts four spaces after each block header, including nested ones. A blank line submits the entry; the flow body is indented four spaces:
zhex> print(1 + 1)
2
zhex> word greet(name: String) -> String
....> "Hello, " + name + "!"
....>
zhex> flow "Ada"
....> greet
....> print
....>
Hello, Ada!
The spaces shown after ....> are editable. Tab inserts four spaces; Backspace removes one character; press it four times to dedent one level. An empty or spaces-only continuation line submits the entry. While editing, Ctrl-C cancels the current entry. Ctrl-D on an empty top-level line exits; in a pending entry, Ctrl-D on an empty or spaces-only continuation line discards it and exits.
An open (), [], or {} also continues an entry. Blank and comment-only lines inside it do not submit. A comment-only line outside a delimiter never completes an entry either: it joins the next line’s entry, so a ## doc block stays with the word it documents. Closing a top-level expression submits it; if it is inside a pending block, a blank line still submits the block. This works in source files and the REPL.
Auto-indentation applies to interactive terminal input. Piped REPL input keeps the existing source format, so include the leading four spaces yourself. Pasted code keeps its source indentation; tabs and non-ASCII whitespace outside strings or comments are still rejected by the language. A program’s read-line prompt reads input as data, without source auto-indentation or Tab expansion.
Words and values stay available in later entries. Ctrl-D exits with status 0; you can also call bye() to exit.
Common problems
zhex: command not found— this terminal’sPATHdoes not include the binary. Run theexport PATH(or$env:Path) line from Build and run again, or runjust installonce for a permanent install.gois not found or older than 1.23 — check withgo version, then follow the per-OS install steps in Install the tools.go buildfails — the two usual causes are an old Go (go versionmust report 1.23 or newer) and no network on the first build, which downloads the project’s small Go modules once. Update Go, or build once from a connected terminal.just testorjust sitereportsmissing-tool— the website build needs the free wasm-tools assembler; install it with the one-line command the diagnostic prints (cargo install wasm-tools,pacman -S wasm-tools, orbrew install wasm-tools); a release binary from the wasm-tools releases page also works.
When a run prints a coded diagnostic, its meaning is cataloged on the Errors page.
Where to go next
- Syntax: names, expressions, and indentation.
- Values: bindings, types, and operators.
- Words and flows: composition, parameters, and results.
- Control flow: conditions and loops.
- Examples: complete programs with source, input, and output.