# 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](install.html).

## Quick install

```bash
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`:

```niell
action main
  show with "hello, niell"
end
```

Compile and run:

```bash
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`:

```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:

```bash
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:

```bash
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:

```bash
niell explain NIELL-PARSE-001
```

## Next steps

- [01 Syntax (ES)](../01-sintaxis.html) — case sensitivity, keywords, operators, precedence
- [02 Types (ES)](../02-tipos.html) — primitives, structural relations, type system
- [04 Actions and errors (ES)](../04-acciones.html) — signatures, returns, overloading, `fails with`
- [Keywords (ES)](../keywords.html) — 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.