Nagi Docs
Follow installation with your first CLI app. Use the language feature index for a path through the language, or open the syntax reference and built-in functions for lookup.
These Docs target Nagi 0.2.0, released on 2026-10-20. Editor extensions have separate versions; see the editor guide. The official site is normally built from main and may include later changes. See the Changelog and 0.2.0 migration guide.
See About Nagi for its purpose and current scope. The references below describe implemented APIs and their limits. Unimplemented proposals are kept in design and the roadmap.
On this page
First steps
- Setup and first run: install the compiler and run Hello World.
- Learn by writing code: try values, functions, lists, borrowing, and Results.
- Your first small CLI app: connect input, typed failures, and a manual boundary check.
- HTTP and HTML: build an API, then store data with SQLite.
See the VS Code guide for editor support. See JetBrains installation and Release ZIP selection for IntelliJ IDEA and PyCharm.
Language feature index
Run an example and check its expected result, then read the detail page for conditions and limits. The columns below point to each feature's purpose, runnable example and result, common mistakes and fixes, and alternatives. A code fragment is not always a complete program; use a section with nagic run instructions or the linked sample.
| Feature | Use and runnable example/result | Limits, common mistakes, and fixes | Choices and detail |
|---|---|---|---|
| Values, annotations, assignment, and reassignment | Guide #1: values and types updates a number and prints 11 |
A variable keeps its inferred type; reassignment cannot change it | Types, values and variables |
| Functions, parameters, return, and function values | Guide #2: define functions returns 42 |
Annotate parameter/return types; call executable code from main |
function syntax, function types |
| if, match, for, while, and operators | Guide #3: lists, classes, branches, and loops prints OK and loop results |
Conditions require bool. break, continue, and elif are unsupported |
branches, loops, operators, match |
| Lists, classes, fields, and enums | Guide #3: lists, classes, branches, and loops and the class example print a sum and field values | Lists have one element type. Classes use named fields; methods, inheritance, and field reassignment are unsupported | types and enums, classes |
Nullable T? / Option[T] |
Absent-value example handles Some and None |
Match both cases. There is no unwrap or Python-style if value is not None narrowing |
types, match syntax |
Result[T, E], try, match, and custom Errors |
First CLI app propagates bad input; Guide #5: return failures with Result shows recovery | try returns Err to the caller. Use match with both Ok and Err to recover locally |
failure types and examples, built-ins |
| Ownership, explicit move for assignment, and copy | Guide #4: borrow with view shows values after a call | Use move(...) for ordinary assignment of an owned non-Copy local; the source is unavailable afterward |
assignment, move, and mistakes, migration |
Borrowing and view |
The view example reads a string range and compares an owned copy | A view cannot outlive its owner. Do not save a view of a temporary value | borrow checks, views |
shared, owned, and Copy |
share/clone_shared examples are in built-ins |
shared does not make every type thread-safe. owned[T] is unfinished |
types, memory |
| Files, imports, and module aliases | Guide #6: split code into files calls a function from a second file | Relative files and registered standard modules are supported; cycles and general package discovery are not | modules and Rust |
async functions and await |
The async example prints after waiting | await does not create a task or thread. Storing a Future in a variable is unsupported |
async, CPU concurrency |
scope, spawn, and Task result handles |
The scope example waits for its children | Normal exits follow child completion rules. A Task cannot escape its scope and is received once | Task results, errors, faults, scopes |
| Actors and Supervisors | The supervised service registers, calls, and stops workers | APIs run within one process. Check restart, business error, call failure, and shutdown conditions | actors, Supervisors, API types |
| High and Low | Run High and Low | Low follows the same type and ownership rules; it is not a pointer/unsafe/C ABI layer | High and Low, Rust integration |
| Built-in functions | Find signatures in the built-in reference; common examples are linked by section and in runnable samples | Accepted types, borrowing/consumption, sync/async behavior, and runtime conditions vary by function | all built-ins, HTTP, SQLite |
Each detail page describes current behavior and release scope, then provides or links to usage, code and output, conditions/limits, common mistakes and fixes, and the choice between related features. For tasks involving several features, also browse the sample projects.
Language reference
| Topic | Page |
|---|---|
| Syntax, operators, and function definitions | Syntax reference |
| Built-in function arguments, return values, and limits | Built-in functions |
| Types and annotations | Types and inference |
| Named data fields | Classes |
| Passing, borrowing, and copying values | Ownership, views |
| Returning and handling failures | Error handling |
Build applications
| Task | Page |
|---|---|
| HTTP without a database, headers, and response statuses | HTTP, API reference |
| Read and write JSON | JSON |
| Use the existing SQLite API and preflight SQL | SQLite, SQL checks |
| Use typed parameters, a Pool, and transactions | SQLite Pools and Transactions |
| Split code into files or call Rust | Imports and Rust |
| Share your own libraries or use Rust crates | Libraries and Rust assets |
| Save an entry file and build settings | nagi.toml |
| Use your own Rust crate from an application | Local library example |
| Wait for async work or start child operations | Async and scopes, concurrency |
| Send messages to stateful tasks and manage restart and shutdown | Actors, Supervisors, API reference |
| Read working applications | Sample projects |
| Diagram types, modules, and calls | Code maps |
Runnable examples are in examples/tutorial/. References also include code fragments.
Tutorial code uses the current syntax. Explicit move and Task result handles are published in Nagi 0.1.11; confirm that the installed compiler is version 0.1.11 or later with nagic --version. See the migration guide and Task result handles. Shared actor messages remain future design work.
The SQLite Pool/Tx API is included in 0.2.0; it is not included in 0.1.11.
Implementation and development
About Nagi · Design decisions · Low · Memory · Compiler · Language interfaces · Roadmap
Follow the first contribution walkthrough to locate a source file, make a small change, run the relevant checks, and open a PR.
std.actor is a standard library available from Nagi 0.1.8. The sample covers registration, calls, and shutdown. The older actor/Supervisor built-ins and queues remain test APIs. For performance, read the measurement methods, results, and HTTP load tests.
These pages cover Nagi 0.2.0 and the current source. See the change log for changes by version. Unsupported features are listed on each page.