Reference

CLI reference

Every command is rayzor <command>, and --help lists the available flags. Start with installation, then use the command reference below.

Install

curl -fsSL https://rayzor.tech/install.sh | sh     # macOS, Linux, WSL
irm https://rayzor.tech/install.ps1 | iex          # Windows

rayzor info                                        # confirm the install

Installs to ~/.rayzor/bin. The download includes everything needed to run Rayzor.

Create a project and run it:

rayzor init --name my-app      # src/Main.hx + rayzor.toml
cd my-app
rayzor run                     # entry point from the manifest

Compilation modes

Choose a command based on what you need: run source code, check types, or produce a build artifact.

You want to
Command
What happens

Run code while developing

rayzor run main.hx

Starts executing immediately, then compiles and optimizes frequently called functions

Type-check only

rayzor check main.hx

Parse and type-check, no codegen

Ship a native binary

rayzor aot main.hx -o app

Whole program compiled ahead of time, linked against the runtime

Ship one portable artifact

rayzor bundle main.hx -o app.rzb

Serialized MIR in a single file, run later with rayzor run

Target the browser or WASI

rayzor build --target wasm

WebAssembly module; --browser also emits an HTML harness

Start a project

rayzor init --name my-app

Scaffolds src/Main.hx and rayzor.toml

Tier presets

Presets control when functions move between execution tiers: script never promotes, embedded stays interpreted, benchmark starts compiling immediately.

script CLI tools and short scripts. Instant startup, no tier promotion

application Desktop apps and web servers. Balanced (default)

server Long-running services. Optimizes aggressively

benchmark Performance testing. Compiles immediately and finishes optimizing during warm-up

development Debugging. Verbose logging

embedded Constrained environments. Interpreter only

Threshold tuning, stage inspection and the RAYZOR_* variables live in CONTRIBUTING.

Commands

rayzor run

execute with the tiered JIT

FILE may be a .hx source file or a prebuilt .rzb bundle. Omit it and the entry point comes from rayzor.toml. Arguments after -- go to the Haxe program, not the compiler.

rayzor run [FILE] [OPTIONS] [-- PROGRAM_ARGS...]

--preset <NAME> Tier policy. Default application

--no-cache, --cache-dir <DIR> Control the module cache (on by default)

--release Use target/release paths

--rpkg <FILE> Load an .rpkg package (repeatable)

--native-lib <FILE> Load a native plugin dylib directly, without a manifest

--wasm Compile to WASM and run it in the embedded wasmtime sandbox

-i, --interactive Open the TUI after execution (scroll, search)

--stats, -v Compilation statistics, verbose output

rayzor aot

native executable

Compiles the whole program ahead of time and links it against the runtime.

rayzor aot [FILES...] -o app

--emit <FORMAT> exe (default), obj, asm. --help lists the rest

-O, --opt-level <0-3> Optimization level. Default 2

--target <TRIPLE> --sysroot <DIR>, --linker <PATH> Cross-compilation

--strip Tree-shake unreachable code

--strip-symbols Strip debug symbols from the binary

--no-cache, --cache-dir <DIR> BLADE cache control

rayzor bundle

single-file .rzb

Saves every compiled module in one file, so startup skips compilation. Run the bundle with rayzor run app.rzb.

rayzor bundle [FILES...] -o app.rzb

-O, --opt-level <0-3> Optimization level. Default 2

--strip Tree-shake unreachable code

--no-compress Disable zstd compression

--no-cache, --cache-dir <DIR> BLADE cache control

rayzor build

build from a manifest or HXML

Pass an .hxml file directly, or run this command in a directory with rayzor.toml. The manifest can also point to an existing HXML build.

rayzor build [FILE]

--target native|wasm|wasm-wasi Output target. Default native

--browser Also emit a browser HTML harness (with --target wasm)

--opt-level <0-3> MIR optimization level. Default 2

-o <PATH>, --strip --dry-run, -v Output path, symbol stripping, plan-only, verbose

rayzor check

type-check, no codegen

Parses and type-checks the program and reports diagnostics in text, JSON or pretty form.

rayzor check main.hx [--show-types] [--format text|json|pretty]

rayzor cache

BLADE module cache

warm pre-compiles the standard library for reuse in later builds.

rayzor cache stats | list | warm | clear

rayzor init

scaffold a project

Templates for an app, a library, a benchmark or an empty project, plus workspaces and adoption of an existing HXML build.

rayzor init --name my-app [--template app|lib|benchmark|empty]
rayzor init --name my-workspace --workspace --members a,b
rayzor init --from-hxml build.hxml

rayzor rpkg

packages

.rpkg packages contain Haxe sources and optional native libraries. Use strip to keep only the native library for a selected platform.

rayzor rpkg pack | inspect | install | add | remove | list | strip

others

REPL and editor integration

rayzor jit main.hx     # JIT with an interactive REPL
rayzor lsp             # Language Server, for editor integration
rayzor info [--features] [--tiers]

Project manifest

A rayzor.toml file at the project root stores build settings. A workspace lists its members there. To reuse an HXML build, set the hxml field as shown below.

rayzor.toml

[project]
name = "my-app"
version = "0.1.0"
entry = "src/Main.hx"

[build]
class-paths = ["src"]
opt-level = 2
preset = "application"
output = "build/my-app"

[cache]
enabled = true

workspace

[workspace]
members = ["game", "engine", "tools/level-editor"]

[workspace.cache]
dir = ".rayzor/cache"

delegate to HXML

[project]
name = "legacy-app"
hxml = "build.hxml"

For native plugins, declare both the class paths and the native libraries. Rayzor needs both to resolve the plugin at runtime.

Compiler internals

The IR levels, pass ordering, the tier ladder and the runtime ABI.

Architecture →