Getting Started

Getting Started

2026-09 note, read this before the commands below: the tree-walking interpreter (nirdosha <file.nir> to just run one, and nirdosha serve) was removed entirely in a compiler-hardening pass. There is no interpreted fallback left — a construct not yet reachable from native codegen is a named compile error from nirdosha build/emit-llvm, not something that still runs interpreted. This page describes what's real and runnable today; see Honest Scope & Roadmap for the full shipped-vs-not-yet picture, and PUBLIC_ROADMAP.md for what's landed since.

Don't want to learn the syntax first? Paste agent-skills/nirdosha/paste-anywhere-prompt.md into any LLM chat (ChatGPT, Claude.ai, Gemini, ...), describe what you want in plain English, and it writes the .nir code for you — no install needed for that step. See LLM Integration for what that's been used to build. Everything below is for actually running the code it hands you back.

Install (no Rust needed — prebuilt binaries)

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/kannamma-labs/nirdosha/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/kannamma-labs/nirdosha/main/scripts/install.ps1 | iex

Prebuilt binaries: Linux x86_64 and Windows x86_64 have Z3 statically vendored — nothing to install first, no linker errors. macOS binaries link the system Z3 instead (brew install z3 first) — z3-src doesn't compile against the AppleClang on current macOS toolchains, a real upstream incompatibility, not a packaging choice; tracked in PUBLIC_ROADMAP.md. clang is only needed on the machine actually running nirdosha build/ emit-llvm (native codegen) — emit-ui/emit-ast/emit-catalog need neither clang nor a running network service. See GitHub Releases to download a binary directly instead of piping the script.

Windows is untested beyond CI. The compiled tcp/tcp_listener runtime was ported to Windows' socket API but hasn't been verified against a real (non-CI) Windows machine. Please report an issue if something doesn't work.

Get the examples

git clone https://github.com/kannamma-labs/nirdosha.git
cd nirdosha

Or build from source (for contributors)

cargo build --release -p nirdosha
# binary: target/release/nirdosha

Toolchain: Rust (edition 2024), plus two system libraries the build links against directly — install these before cargo build or the build fails with a linker error, not a friendly message:

# Debian/Ubuntu
sudo apt install clang libz3-dev

# macOS (Homebrew)
brew install llvm z3

# Arch
sudo pacman -S clang z3

clang is invoked at runtime by nirdosha build/emit-llvm (native codegen); z3 is linked at compile time for the SMT refinement layer and is required even just to build the compiler, not only to use that feature. (The prebuilt binaries above sidestep this with cargo build --features dist, which vendors Z3 from source instead.)

Run a program

There is no interpreter and no bare "just run this file" mode — every program goes through nirdosha build to a real native binary first:

# Compile to a native binary (a real, growing subset -- see
# Honest Scope & Roadmap for exactly what codegen reaches today)
nirdosha build examples/syntax/hello_nir.nir -o hello
./hello

# Inspect the program instead of running it
nirdosha emit-llvm examples/syntax/hello_nir.nir   # print the generated LLVM IR
nirdosha emit-ast  examples/syntax/hello_nir.nir   # print the parsed AST as JSON

nirdosha build/emit-llvm name the specific unsupported construct and stop, rather than silently mis-compiling it — see Architecture's note on check_supported.

Scaffold a new project

nirdosha init shop
# writes ./shop/:
#   shop.nir      -- starter source (Email/RoleMapping admin-panel
#                     fixtures by default; --no-email/--no-roles/--sms/
#                     --push to change which ones)
#   nirdosha      -- a copy of this executable, so the folder can be
#                     moved to another machine and run standalone (same
#                     OS/arch only -- no cross-compilation)
#   run.sh/run.bat, jwks.json -- see the note below

--dest <path> puts the shop/ folder under <path> instead of the current directory; --force overwrites an existing one. This is tooling convenience only — Nirdosha has no compiler-level notion of "a project" beyond the one .nir file inside the folder.

Known gap, not yet fixed: the generated run.sh/run.bat currently invokes nirdosha serve, a subcommand that doesn't exist in this binary right now (removed along with the interpreter — see the note at the top of this page). Don't run it as-is yet; use nirdosha build shop.nir -o shop && ./shop for a runnable binary, or nirdosha emit-ui shop.nir -o shop.html for the static UI, until this is reconciled.

Generate a UI

nirdosha emit-ui examples/features/39_screen_ui.nir -o ui.html
# --theme theme.json applies a design-token file on top of the Material
# defaults; --manifest-path Cargo.toml (or an auto-detected Cargo.toml
# next to the .nir file) links any nir-ui-component crate the project
# depends on -- see rfcs/0009 and The UI Engine's "Extending the catalog"

This produces a static HTML/JS file — no live backend, no server process. The role/claim field-masking demonstrated in the README's example runs underneath any UI, in the compiled binary itself, whether or not one is ever generated; see The UI Engine for the full picture, including what a live, server-enforced UI would need that doesn't exist yet.

Inspect the standard UI catalog

nirdosha emit-catalog -o catalog.json   # the closed layout/control/chart/
                                         # theme vocabulary emit-ui renders

Explore the language

• Full feature reference: LANGUAGE.md
• Full grammar: GRAMMAR.md
• Design rationale: goal.md, Nirdosha_Unified_Plan.md — see also Design Philosophy
• Sandboxing (designed, not currently running in any form — see Honest Scope & Roadmap): SANDBOXING.md
• Transactions (same caveat): TRANSACT.md
• Agent API: nirdosha-agent-api.md — see also LLM Integration

Start small (examples/syntax/hello_nir.nir → 02_types_and_control_flow.nir → 03_data_modeling.nir → 04_ownership_and_concurrency.nir), then examples/features/ — one file per language feature, 51 in total; see Language Features for which of them nirdosha build compiles today versus which are still waiting on native codegen.