oriel is a single static program (no GTK, no Node.js) that creates apps, runs their builds and manages the tools they need. Most commands are thin wrappers: oriel dev is zig build dev run in the project root with the right Zig, Node.js and WebView2 loader found or installed first. Anything the CLI does, zig build <step> in the project does too; the CLI adds discovery, defaults and tool management.

Use the CLI day to day. Call zig build directly in CI scripts that pin their own tools, or for the project’s own steps (zig build --help lists them).

Availability

Install it with the script in Getting started; oriel update keeps it current. oriel doctor reports what the host is missing. oriel desktop-entry does something only on Linux.

Quick start

oriel doctor                   # what this machine needs
oriel init notes --template svelte --id com.example.Notes
cd notes
oriel dev                      # develop with hot reload
oriel permission add microphone "Dictation turns your speech into text"
oriel build                    # production build in zig-out/bin
oriel package                  # deb, rpm, AppImage / setup.exe / .app, .dmg

How it works

flowchart LR
  User["oriel dev -Dnative_ui"] --> Root["find the project root<br/>(nearest build.zig.zon)"]
  Root --> Zig["resolve Zig:<br/>ORIEL_ZIG, PATH, ~/.oriel/zig,<br/>else install"]
  Zig --> Tools["Node.js (PATH or ~/.oriel/node),<br/>WebView2Loader.dll for Windows,<br/>NSIS for setup.exe"]
  Tools --> Defaults["defaults: -Doptimize=ReleaseSafe,<br/>-Dcpu (production steps)"]
  Defaults -->|"exec"| ZB["zig build dev -Dnative_ui"]

The build wrappers (dev, build, run, package, types, check) are project.Wrapper commands (cli/project.zig). Each one finds the project root, resolves the project’s Zig, and runs zig build <step> [args...] there, passing every argument on. Before that it:

• adds -Dwebview2-loader=<cached dll> when the build targets Windows and no loader was given, downloading it first if needed (oriel webview2);
• for build, run and package, adds -Doptimize=ReleaseSafe unless -Doptimize is given, and -Dcpu=x86_64_v3 (x86-64), apple_m1 (macOS ARM64) or baseline (other ARM64) unless -Dtarget or -Dcpu is given, so a binary built on a new CI machine runs on older CPUs;
• puts a managed Node.js (~/.oriel/node) on PATH when the system has none, or stops with run: oriel setup node when the project needs it;
• for a Windows package, finds NSIS (ORIEL_MAKENSIS, ~/.oriel/nsis, makensis on PATH);
• for dev, checks that the app has a dev server and forwards Zig’s own --fork=<path> flags to the rebuilds (ORIEL_DEV_ZIG_ARGS).

The other commands are implemented in cli/<name>.zig. Options are parsed from each command’s struct (cli/args.zig): oriel <command> --help prints its usage, and oriel --help the list. A usage error exits with code 2, a failure with 1.

Examples

A new app on a machine with nothing installed

oriel setup all --yes      # Zig, Node.js LTS, WebView2Loader.dll, NSIS on Windows
oriel init hello --yes     # --yes also installs Node.js if init needs it

Windows packages from Linux

oriel build -Dtarget=x86_64-windows
oriel package -Dtarget=x86_64-windows   # zig-out/package/<app>-<version>-setup.exe

The loader is fetched and passed automatically; makensis must be installed (oriel setup nsis prints the package manager command).

A web app as a desktop app

oriel wrap https://music.example.com --name music --title "Music" --user-agent chrome --run

See Wrap.

Phones

oriel android init
oriel android dev --abi arm64            # run the frontend dev server yourself
oriel android build --aab -Dnative_ui
oriel ios dev --simulator
oriel ios build --ipa

Pin the toolchain in CI

export ORIEL_NO_ZIG_INSTALL=1 ORIEL_ZIG=/opt/zig-0.16.0/zig
oriel build -Doptimize=ReleaseFast -Dcpu=baseline

Reference

Global

Usage: oriel <command> [options]

Options:
  -h, --help     Show help (also: oriel <command> --help)
  -V, --version  Show the version

oriel --version prints the CLI’s version and the Oriel commit that oriel init and oriel wrap depend on by default.

oriel init

Usage: oriel init <name> [options]

react, vue and svelte use Vite (Node.js and npm); vanilla is a static page with no build step and no dev server. The target directory must not exist or must be empty. init writes the project (build.zig, build.zig.zon, src/main.zig, frontend/, isolation/hook.js, icon.png), adds the Oriel dependency (zig fetch --save=oriel), runs zig build --fetch and npm install, and caches WebView2Loader.dll.

oriel wrap

Usage: oriel wrap <url> [options]

The app may only navigate to, and grant capabilities to, the URL’s exact origin (https://<host>). --allow-subdomains also allows https://*.<host> (a leading www. dropped); pages on other domains open in the browser. Details: Wrap.

oriel doctor

Usage: oriel doctor [options]

Required everywhere: Zig 0.16.x (on PATH, or $ORIEL_ZIG), Node.js (20.19+ or 22.12+) and npm for the Vite templates. Linux: pkg-config and the GTK 4 and WebKitGTK 6.0 development packages; optional packaging tools and plugin libraries; the tray host and the GlobalShortcuts portal are reported for information only. macOS: the Xcode command-line tools (Apple SDK). Windows: the WebView2 runtime; NSIS (makensis) for installers. Exits with 1 when something required is missing.

oriel fmt

Usage: oriel fmt [--check] [--stdin] [paths...]

Formats .oriel views in place, as zig fmt does Zig: one element per line, indented two spaces, attributes as written. A <text> keeps its content exactly as written, on its open element’s line (the spaces in it are text). A directory means every .oriel file under it, skipping hidden directories, zig-out*, zig-pkg and node_modules. Prints the files it changed; a view that doesn’t parse is reported as path:line:column and left alone (exit 1).

Apps get the same command as a build step, over the project’s directory: zig build fmt-views, and zig build fmt-views -- --check in CI.

oriel setup

Usage: oriel setup <tool> <version> [options]

Zig and the WebView2 loader have their own commands: oriel zig install, oriel webview2.

oriel update

Usage: oriel update [options]

Downloads the signed release manifest for this architecture from Oriel’s GitHub releases, verifies the Ed25519 signature against the release key built into the CLI, and atomically replaces the running binary (on Windows the old one is renamed to oriel.exe.old and removed on the next run).

oriel webview2

Usage: oriel webview2 [options]

Downloads Microsoft.Web.WebView2 from NuGet, verifies its SHA-512 package hash against the NuGet registration catalog, extracts runtimes/win-<arch>/native/WebView2Loader.dll, and caches it in ~/.oriel/webview2. The build wrappers pass the newest cached loader as -Dwebview2-loader=<path> to Windows builds; an explicit -Dwebview2-loader wins.

oriel deep-link

Usage: oriel deep-link <command> [args...]

Run oriel deep-link without arguments for this usage. Packages declare their schemes themselves; see Deep links.

oriel permission

Usage: oriel permission <command>

Kinds: microphone, camera, screen_capture, accessibility, location, notifications, system_audio, bluetooth, local_network. The app requests them at runtime with oriel.permissions.request(kind) (Zig) or oriel.permissions.request("kind") (JavaScript); undeclared ones are denied. Run oriel permission without arguments for this usage. See Permissions.

oriel signing

Usage: oriel signing <action> <file> [options]

Then sign with oriel package -Dmacos-sign-identity=<SHA-1>. See Signing.

oriel desktop-entry

Usage: oriel desktop-entry [--release | --remove] [zig build args...]

Installs $XDG_DATA_HOME/applications/<id>.desktop and the app’s icons for the build in zig-out, so the desktop knows the app when it runs from there: global hotkeys (the GlobalShortcuts portal needs it on Wayland), the app menu, notifications. Installed packages ship their own. On macOS and Windows it prints that it isn’t needed.

oriel zig

Usage: oriel zig <action> <version>

<version> defaults to the project’s minimum_zig_version (e.g. 0.16.0).

How the Zig is chosen

The commands that run Zig (dev, build, run, package, types, check, init, wrap, android, ios) use, in order:

1. $ORIEL_ZIG; a version other than the project’s is an error;
2. zig on PATH, when it matches the project’s build.zig.zon .minimum_zig_version (same major.minor, not older);
3. ~/.oriel/zig/<version>/zig (%USERPROFILE%\.oriel\zig\<version>\zig.exe on Windows);
4. otherwise that version is downloaded and installed there, unless ORIEL_NO_ZIG_INSTALL=1.

Downloads come from a randomly ordered community mirror, with ziglang.org as the last fallback; a tarball is used only when its minisign signature verifies against the Zig Software Foundation’s key and names the requested file. Extraction refuses absolute paths, .., drive letters, backslashes and symlinks.

oriel android

Usage: oriel android [args...]

dev and build forward Zig -D options (-Dnative_ui, -Dggml_vulkan). Needs the Android SDK (adb, Gradle 8.11.1+ or android/gradlew, a JDK) and the NDK ($ANDROID_NDK_HOME or $ANDROID_HOME/ndk/<version>). See Android.

oriel ios

Usage: oriel ios [args...]

-y/--yes accepts the offers to download or set up what’s missing. Needs the iOS SDK ($APPLE_SDK, Xcode’s on a Mac, xtool setup on Linux) and xtool (a device) or Xcode’s simctl (the simulator). See iOS.

Build wrappers

Every argument is passed on: -D options (-Dnative_ui, -Doptimize=ReleaseFast, -Dtarget=x86_64-windows), and -- <app args> for run and dev. They run in the project root, the nearest directory above with a build.zig.zon.

Environment

Troubleshooting

Related

• Getting started: installing the CLI and a first app.
• Development: what oriel dev runs.
• Building and Packaging: the steps the wrappers call.
• Android and iOS: the phone commands in context.
• Wrap: oriel wrap in detail.