Toolchain & CLI

Every nyra subcommand — what it does, when to use it, and a copy-paste example. Path arguments default to . (the current project). Run nyra --help or nyra <cmd> --help for the live flag list.

Quick reference

Help & version

Job: Discover commands and confirm which nyra binary is on your PATH.

nyra --version          # e.g. nyra 0.1.1
nyra --help             # list all subcommands
nyra test --help        # flags for one command
nyra --color never …    # disable ANSI colors (also respects NO_COLOR)

Comptime modules

Job: Validate a compile-time-only file (lookup tables, generated constants) without a main or runtime codegen.

nyra check examples/toolchain/comptime_tables.ny
nyra run examples/toolchain/comptime_import_main.ny

Three forms: file-level comptime, function #[comptime], and block comptime { … }. Full guide: Comptime evaluation.

Start a project

Job: Scaffold main.ny, nyra.mod, and lockfiles before your first build. File roles: packages.html.

mkdir myapp && cd myapp
nyrapkg init
nyra run .

Multi-file layout (imports resolved from project root):

myapp/
  main.ny              # import "src/helper.ny"
  src/helper.ny
  nyra.mod
  target/debug/main

myapp/
  main.ny              # import "src/helper.ny"
  src/helper.ny
  nyra.mod
  target/debug/main

nyra run

Job: Fastest feedback — compile and run in one step while you edit code. If nyra.mod require lines changed, Nyra syncs first: fetches missing packages and removes orphaned ones from .nyra/cache/ (like cargo run).

nyra run .                          # project with main.ny
nyra run examples/syntax/hello.ny   # single file
nyra run . --release                # optimized run
nyra run . -- --arg1 value          # pass args to your program (after --)

nyra build

Job: Produce a binary you ship, profile, or debug — without executing it. Same auto-sync of require lines as nyra run.

nyra build .                        # target/debug/main
nyra build . --release              # target/release/main
nyra build . --pgo                  # release + automated PGO (see pgo.html)
nyra build . --verbose              # escape analysis report (see escape-analysis.html)
nyra build . -o mybin               # target/debug/mybin
nyra build . --debug-symbols        # DWARF for lldb/gdb
nyra build app.ny --release -o app  # single-file stem

Job (incremental): Second build skips codegen when sources and link flags are unchanged.

nyra build .
# incremental: cache hit (4 source files)

# edit one file → reports dirty crates, then rebuilds
nyra build .
# incremental: 1 crate(s) changed: helper.ny

Per-file manifest: target/debug/.nyra-cache/crates/manifest.json (Cargo-style dirty tracking).

nyra check

Job: Catch type and borrow errors quickly — no object files, no link.

nyra check .
nyra check src/module.ny
nyra check . --deny-extended     # Core-only (reject async, traits, macros, …)
nyra check . --ownership-verbose  # per-binding ownership at function exit

With --ownership-verbose, stderr lists each local binding’s Copy/Move kind and valid/moved status at function exit (same borrowck walk as compile). Full guide: Ownership inspect.

nyra inspect

Job: See who owns a variable and who borrows it at a specific source line — compile-time only (not a runtime method). Unique among systems languages today: Rust has no stable equivalent.

nyra inspect name --at main.ny:42
nyra inspect user --at src/app.ny:18 .

Example output (Move):

myname2 (string) @ main.ny:5 in main
  ownership chain:
    name ──move──► myname ──move──► myname2
  current owner:  `myname2` (owns value)

Example output (Borrow):

myname2 (&&string) @ main.ny:11 in main
  you inspect:  `myname2` (borrower)
  heap owner:  `name` (owns Move value)
  borrow chain:
    name ◄──borrow── myname ◄──borrow── myname2

Color-coded on TTYs. Respects NLL (borrows end at last use of the ref). See Ownership inspect · Memory · Ownership UX.

nyra test

Job: Discover and run unit tests — each test fn is compiled, linked, and executed as its own temporary binary (similar to cargo test).

Write a test

import "stdlib/testing.ny"

test fn adds() {
    assert_eq(2 + 3, 5)
    assert_bool(true)
}

import "stdlib/testing.ny"

test fn adds() {
    assert_eq(2 + 3, 5)
    assert_bool(true)
}

Discovery rules:

• test fn name() { … } — preferred
• Functions named test_* also count
• Legacy: files named *_test.ny run main as the harness

Run tests

nyra test                       # same as nyra test .
nyra test .                     # all tests under the project
nyra test main.ny               # one file
nyra test . --filter adds       # only tests whose name contains "adds"
nyra test . --list-json         # discover only — JSON for IDE Test Explorer
nyra test . --release           # optimized test binaries
nyra test tests/conformance/pass

What the output means

Example successful run:

nyra test: root=. timeout=60s
COMPILE ./main.ny::adds
LINK ./main.ny::adds -> /tmp/…/test_bin
RUN ./main.ny::adds …
RUNNING pid=… bin=/tmp/…/test_bin
PASS ./main.ny::adds (0.74s)
1 tests passed

Assertions: import "stdlib/testing.ny" — assert_eq, assert_ne, assert_true, assert, assert_bool, assert_str_eq. See stdlib → testing.

Use a freshly built CLI (./target/debug/nyra) when testing stdlib imports — a stale global install may not resolve project paths.

Language conformance (CONF-LANG)

Job: Verify each language feature with Nyra-source pass and fail tests — separate from Rust CONF-* compile/IR contracts and the large tests/suite/ compiletest grid.

Pass areas: variables, control, match, types, functions, arrays, enums, strings, generics, borrow, edge, imports. Fail areas: immutable assign, use-after-move, type mismatches.

cargo build -p cli
bash scripts/conformance-tests.sh
# or pass-only:
./target/debug/nyra test tests/conformance/pass

Spec: tests/conformance/README.md in the repo. When adding a language feature, add ≥2 pass tests under pass/<area>/ and ≥2 fail tests under fail/<area>/.

Testing layers (repository)

nyra fmt

Job: Normalize style before review; gate formatting in CI.

nyra fmt .                    # print formatted stdout
nyra fmt . --write            # rewrite files in place
nyra fmt src/helper.ny --write
nyra fmt . --check            # exit 1 if not formatted (CI)

AST-based when the file parses; line-based fallback otherwise. Preserves // comments.

nyra diag

Job: Pipe structured errors into editors or scripts.

nyra diag .
nyra diag src/broken.ny
nyra diag . --json            # machine-readable for custom integrations
nyra diag . --deny-extended

See also Diagnostics. The LSP uses the same compiler pipeline via nyra lsp. JSON output includes code, label, notes, helps, and end positions.

nyra explain

Job: Explain stable diagnostic codes after a compile error.

nyra explain E003
nyra explain P001
nyra explain --list

nyra watch

Job: Keep a terminal open while coding — re-run checks or builds on every save. Watches .ny / .nyra / nyra.mod and ignores target/.

nyra watch .                  # re-check on change (default)
nyra watch . --on build       # rebuild binary
nyra watch . --on run         # rebuild + run main
nyra watch . --on run --race  # rebuild under ThreadSanitizer
nyra watch . --on run --race-native

nyra repl

Job: Interactive session for exploring Nyra without a project file. Declarations persist; expressions are printed.

nyra repl
nyra> 1 + 2
3
nyra> fn add(a: i32, b: i32) -> i32 { return a + b }
ok
nyra> add(10, 5)
15
:help / :quit / :clear / :load file.ny

Works on Linux, macOS, and Windows hosts (compile-and-run; not available for wasm targets).

nyra race

Job: Build and run under a concurrency race detector. Prefer this over remembering flag combinations.

nyra race .                 # ThreadSanitizer (TSan) + auto -g
nyra race . --native        # portable Nyra lock-set runtime
nyra race app.ny --build-only
nyra race . -- --port 8080  # program args after --

Same detectors also work on build, run, test, watch, and debug. See Concurrency → Race detection and Async.

nyra debug

Job: Step through your program with lldb (macOS) or gdb (Linux).

nyra debug .                           # build -g + lldb
nyra debug . -- --port 8080            # program args after --
nyra debug . --debugger gdb            # force gdb
nyra debug . --race                    # TSan binary under the debugger
nyra debug . --race-native
nyra debug . --init-vscode             # write .vscode/launch.json + tasks.json

For VS Code / Cursor, prefer the official extension which uses nyra dap (DAP) instead of raw lldb. See Editor setup.

nyra lsp

Job: Wire Nyra into any LSP-capable editor (diagnostics, completion, hover, go-to-definition, references, rename, format).

nyra lsp    # stdio — configured by extensions/nyra or your editor

Capabilities: cross-file go to definition, find references, workspace rename, document symbols, formatting, semantic tokens, signature help, inlay hints (inferred types + param names), code actions / source.fixAll, CodeLens ▶ Run Test.

nyra dap

Job: Debug from VS Code “Run and Debug” via the Debug Adapter Protocol (LLDB/GDB bridge).

nyra dap    # stdio — launched by the Nyra VS Code extension

Launch config type: nyra. Build with --debug-symbols first.

nyra ide

Job: Script goto-definition and find-references in CI or terminal workflows (same index as LSP).

# cursor on helper_fn in main.ny line 0, column 20
nyra ide goto-def myapp/main.ny 0 --character 20
# → myapp/src/helper.ny:42:1

nyra ide references myapp/main.ny 0 --character 20
# → JSON array of { file, start, end, name }

nyrapkg & nyra pkg

Dependencies: use nyrapkg (full guide). Build / C libs / prune: use nyra pkg.

nyrapkg init
nyrapkg install ny-sqlite@^0.1.0
nyrapkg verify

# Same flows via nyra pkg (delegates to nyrapkg where noted):
nyra pkg init
nyra pkg install ny-sqlite@^0.1.0
nyra pkg sync
nyra pkg build .
nyra pkg prune --check
nyra pkg c add raylib

System C libraries — nyra pkg c

Job: Add or remove a system C library in one command. Full guide: C Bindgen → nyra pkg c.

nyra pkg c add raylib
nyra pkg c add zlib
nyra pkg c add sqlite3
nyra pkg c add sdl2

import "vendor/bindings/raylib.ny"

Manifest: vendor/bindings/c-libs.toml · Flags: --path DIR, --no-install

nyra bind c / nyra pkg bind c (advanced)

Job: Generate Nyra FFI from a C header (libclang). Full guide: C Bindgen · copy-paste zlib walkthrough: zlib tutorial.

# zlib on macOS (Homebrew keg-only paths)
brew install zlib llvm
SDK=$(xcrun --show-sdk-path)
nyra pkg bind c /opt/homebrew/opt/zlib/include/zlib.h --lib z \
  -I /opt/homebrew/opt/zlib/include -I "$SDK/usr/include" \
  --export zlibVersion -o vendor/bindings/zlib.ny
# nyra.mod: link z + link -L /opt/homebrew/opt/zlib/lib

nyra bind c vendor/api.h --lib mylib -I vendor/include --update-mod
nyra bind c vendor/api.h --stdout --prefix mylib_   # preview
nyra bind c complex.h --no-shim                    # skip auto C shims

Outputs vendor/bindings/{header}.ny, optional vendor/bindings/shim.c, and link / link-source lines in nyra.mod.

nyra bind (C & Rust crates)

Job: Generate FFI stubs into the current package.

nyra bind c sqlite3.h --lib sqlite3
nyra bind rust uuid
nyra bind rust serde_json@^1.0

bind c uses libclang (see above). bind rust wraps a crates.io crate as a C-ABI + .ny stubs for calling from Nyra.

nyra toolchain

Job: Install or inspect the native LLVM/clang toolchain under $NYRA_HOME (zig-cc–style layout).

nyra toolchain info       # print clang / opt / lld paths and Nyra home
nyra toolchain install    # link or download LLVM into $NYRA_HOME/lib/llvm

After install, ensure NYRA_HOME and PATH point at your Nyra root — see Installation.

nyra cc

Job: Drive LLVM clang for C/C++ sources (vendor shims, mixed projects) with the same target flags as nyra build.

nyra cc -c vendor/shim.c -o vendor/shim.o
nyra cc --for wasm -c app.c -o app.o
nyra cc --print-toolchain          # show discovered clang/opt/lld
nyra cc -v -- -Wall vendor/shim.c  # verbose; args after -- go to clang
CC="nyra cc" make                  # use as drop-in CC

Build output layout

Like Rust/Cargo, artifacts live beside your project:

myapp/
  main.ny
  target/
    debug/main              # nyra build  (host)
    release/main            # nyra build --release
    x86_64-pc-windows-gnu/
      release/main.exe      # nyra build --release --for windows

• Project (nyra build): binary name main.
• Single file (nyra build app.ny): binary stem app.
• -o mybin: custom name inside target/{debug|release}/ (or target/<triple>/{profile}/ when cross-compiling).
• Add target/ to .gitignore.

Cross-compilation

Build for another OS from your dev machine. Use --for for a memorable command, or --os / --arch for precision:

nyra build . --release --for windows
nyra build . --release --for linux
nyra build . --release --for macos
nyra build . --release --os linux --arch aarch64
nyra build . --release --target x86_64-unknown-linux-gnu

Cross builds land under target/<triple>/{debug|release}/. nyra run refuses foreign binaries (build only). --native-cpu is rejected when cross-compiling. See Compilation targets for toolchain prerequisites.

Release / optimization

Job: Ship a faster binary or tune for your CPU.

nyra build --release
nyra run --release
nyra build --release app.ny
nyra build . --release --native-cpu    # explicit -march=native (host)
nyra build . --release --no-native-cpu # portable release (disables default native tuning)
nyra build . --release --no-prelude    # disable lazy stdlib auto-prelude
nyra build . --release --lto-full    # full LTO (slower link)

--release enables LLVM IR opt, clang -O3, thin LTO, and -march=native on host builds (unless --no-native-cpu).

More: Performance toolchain.

CI cookbook

Job: Typical pipeline steps for GitHub Actions or any CI.

nyra check .
nyra fmt . --check
nyra test .
nyra build . --release

Repository scripts: make test-all (includes make test-conformance for CONF-LANG), make test-sanitizer. Workflow: .github/workflows/ci.yml.

no_std & freestanding builds

Job: Bare-metal firmware or kernels without the Nyra runtime.

no_std   // in main.ny, or CLI flag

nyra build firmware.ny --no-std --freestanding -o firmware
nyra build . --no-std

You supply entry point, linker script, and libc stubs for your target. Low-level helpers: import "stdlib/core/mem.ny".

Editor & IDE

Job: Syntax, LSP, and debugging in VS Code / Cursor.

# settings.json (extension defaults)
{
  "nyra.languageServerPath": "nyra",
  "nyra.languageServerArgs": ["lsp"],
  "nyra.debugAdapterPath": "nyra"
}

Setup guide: Editor setup · Grammar: grammar/README.md