One command does everything: it runs a file, manages a project, checks your work and maintains the toolchain. This page lists all of it in the order nyx --help prints it.
Running a file
$ nyx <file.nx> [args...]
Compiles the file to a native binary in a temporary directory, runs it with the arguments you gave, and cleans up. It also works as a shebang: a .nx file starting with #!/usr/bin/env nyx is an executable script.
Projects
| nyx init [name] | Create a project: nyx.toml, src/main.nx, .gitignore, AGENTS.md, CAPABILITIES.md and docs/nyx/. |
|---|---|
| --lang en|es | Language of the seeded documents. Defaults to NYX_LANG, and to en if that is unset. |
| --agent=… | --agent=claude,cursor,copilot — also seed a short adapter file for each named tool. |
| --sdd | Also seed the spec-driven scaffolding described in step 04. |
| nyx sdd init | Seed that same scaffolding in a project that already exists: constitution, glossary, evidence, ADR template, specs/, the constitution test and the guide. |
| nyx sdd evidence | Regenerate docs/evidence/ for the toolchain currently installed. |
| nyx add <pkg> | Add a package dependency. --from <url> names where to clone it from. |
| nyx build | Build the project into a binary named after [package].name. |
| nyx run [args…] | Build and run. Arguments go to your program; use -- before any that could be mistaken for a flag of nyx itself. nyx run file.nx runs that file directly instead. |
| nyx info | Print the project's name, version, entry point and memory mode. |
| nyx capabilities [out.md] | Regenerate the standard-library index. nyx build does it for you when the file is missing or was written by another version, so you rarely need this by hand. |
Self-check
None of these link or execute anything, and all of them exit non-zero on a problem, so they chain with &&. Given no file, they use src/main.nx in a project and script.nx outside one.
| nyx check [f.nx] | Parse and type-check. The fastest feedback there is. |
|---|---|
| nyx fmt [f.nx] | Print the file in canonical form on standard output. It never edits in place. |
| nyx vet [f.nx] | Unused variables, dead code, unused imports, and the language's known traps as warning[W1NN] file:line. |
| nyx test | Run every tests/*.nx. Tests are test "name" { … } blocks; a file with test_* functions is skipped in silence. |
Toolchain
| nyx update | Fetch the latest version into ~/.nyx, rebuild the compiler and the five tools, then print what changed and which traps were fixed. |
|---|---|
| nyx update --sync-docs | Run inside a project: refresh AGENTS.md, the reference and the guides from the installed toolchain, regenerate CAPABILITIES.md, and leave a .bak of anything replaced. |
| nyx report [f.md] | Create a FRICTION.md in the project for a bug, a limitation or a documentation gap. It is local; --send is a separate, explicit step. |
| nyx uninstall | Remove ~/.nyx and ~/.local/bin/nyx. |
| nyx --version | Print the installed version, as nyx 0.31.0. |
| nyx --help | Print this list. nyx help works too. |
Once a day — after locating the toolchain and the compiler binary, and before dispatching your subcommand — the wrapper compares your local commit against the remote and mentions it on standard error if a newer version exists. It never updates on its own.
Environment variables
| NYX_LANG | es switches the compiler's diagnostics to Spanish and makes nyx init seed the Spanish documents. Anything else means English. |
|---|---|
| NYX_HOME | Where the toolchain lives. Set it to use an installation other than ~/.nyx — building the compiler from a clone, for instance. |
| NYX_DIAG | json adds one NDJSON line per diagnostic, alongside the human-readable output. |
| NYX_PROJECT_DIR | The project root used to resolve import "src/…". The wrapper finds it by walking up from the current directory; setting it explicitly wins. |
With NYX_LANG=es, the diagnostic from step 02 comes out like this:
$ NYX_LANG=es nyx greet.nx ✗ error [NYX1002] en 'main' (línea 7): 'greeting' no declarado (¿quisiste decir 'greet'?)
And with NYX_DIAG=json, the same failure also produces a line meant for a program to read:
$ NYX_DIAG=json nyx greet.nx {"code":"NYX1002","severity":"error","phase":"semantic","line":7,"column":19,"function":"main","message":"'greeting' not declared (did you mean 'greet'?)","suggestion":"greet"}