Getting started

A 10-minute tour through Niell — install, first program, second program, next steps. Assumes Linux x86_64 with clang installed; for other platforms see Install.

Quick install

sudo apt install -y clang xz-utils
curl -L https://niell.dev/dl/niell-linux-x86_64.xz | xz -d > niell
chmod +x niell
sudo mv niell /usr/local/bin/
niell --help

The binary is self-contained with respect to LLVM 18 — you don't need to install the Rust toolchain. You do need clang because Niell invokes it to link the C runtime with the emitted IR.

Your first program

Create hello.niell:

action main
  show with "hello, niell"
end

Compile and run:

niell hello.niell -o hello
./hello
# → hello, niell

niell produces three files alongside the source:

• hello — the native executable
• hello.ll — the generated LLVM IR (useful to understand what the compiler is doing)
• Temporary intermediate outputs that clean themselves up

A program with types and actions

Niell lets you declare compound types and actions that operate on them. Create geometry.niell:

type Point has
  x: number
  y: number
end

action distance with a: Point, b: Point -> number
  dx: number = b.x - a.x
  dy: number = b.y - a.y
  return sqrt of (dx * dx + dy * dy)
end

action main
  origin: Point
    x = 0
    y = 0
  end
  target: Point
    x = 3
    y = 4
  end
  show with "distance: {distance with origin, target}"
end

Compile and run:

niell geometry.niell -o geometry
./geometry
# → distance: 5

Notice how:

• Types are capitalized (Point), actions and fields are lowercase (distance, x)
• Building an instance uses name: Type ... end with per-field assignment
• Invocation is always action with arg1, arg2 — never instance.method
• {distance with origin, target} interpolates the result inside the string

Compiler introspection

Niell exposes its own description so humans and tools can know what the compiler understands:

niell describe --json | head -20

It returns a versioned schema with keywords, primitive types, built-in modules, prelude, and error code catalog. Useful for writing an agent that writes Niell, or for checking which features are available without parsing the spec.

To inspect a specific error code:

niell explain NIELL-PARSE-001

Next steps

• 01 Syntax (ES) — case sensitivity, keywords, operators, precedence
• 02 Types (ES) — primitives, structural relations, type system
• 04 Actions and errors (ES) — signatures, returns, overloading, fails with
• Keywords (ES) — full catalog

If you get stuck, niell's error codes carry a reference to the spec section where the rule is documented — use niell explain <CODE> to navigate it.