Skip to content

Commands

nomi is the one tool. Each command has its section:

CommandWhat it does
nomi run <file>Run a program (Running a program), in a module one of its entry points (Project mode); nomi <file> runs a script (Scripts), --watch runs it again on every change (--watch), and --profile reports where its time went (--profile).
nomi run --web <file>Serve a browser build on localhost and rebuild it on a change (A program in the browser).
nomi test [path]Run tests (Running tests).
nomi check <path>Check a program without running it, as text or JSON (Checking).
nomi fmt [-w|-l|-d|-check] <paths>Format source (Formatting).
nomiThe REPL (The REPL).
nomi build <file>Write an executable (Executables), a browser folder with --web (A program in the browser), or a .nomic file with --no-vm (Compiled programs and nomi-vm).
nomi build-vmWrite nomi-vm, or with --reactor the WASI reactor, with no program (Compiled programs and nomi-vm).
nomi new, nomi initStart a project (Starting a project).
nomi add, nomi remove, nomi update, nomi fetchChange and download dependencies (Add, update and remove dependencies).
nomi tool <module> <name>Run a module’s tool (Tools).
nomi types <paths>Write TypeScript declarations of the JSON a backend’s types cross as (TypeScript types).
nomi phrases accept <locale> <phrase>Mark a translation current ([i18n]).
nomi dapThe debugger editors start (Debugging).
nomi mcpThe compiler as tools for a coding agent (Coding agents).
nomi versionPrint the version, as nomi --version does.

One engine runs every Nomi program: the VM, under nomi run, nomi test, the REPL, a built executable and the tour’s editors. The compiler parses and type-checks the program and compiles its functions to bytecode for the VM, not to native code.

nomi run <file> runs the file’s top-level fn main, which need not be pub. A program whose functions a host calls (spec §7 Exported Functions) has no main, and is built with nomi build --web instead. For a file in a directory of its own, the project root is that directory, and every import resolves from it (Project root discovery).

my_project/
  app.nomi           # declares fn main; `import math` works
  math.nomi          # import path `math`
  models/
    user.nomi        # import path `models::user`
nomi run app.nomi

File mode needs no config file, which suits scripts and small projects.

nomi run --watch <file> [args] runs the program, then watches the files it is built from: the entry, every file it imports (not the standard library’s) and its project’s nomi.toml, polled every 250 ms as nomi run --web polls them. Once a burst of saves has settled, it stops the run if it is still going, prints <file> changed; running again on standard error, and runs the program again with the same arguments. A run that is computing stops at its next call or loop iteration, and one waiting on input, a timer, a channel or a task stops waiting; what a stopped run would still write is dropped. A program that fails to compile is reported as nomi run reports it, and the next change runs it again. The watched files are worked out again on every run, so a file the program starts importing is watched from then on.

The program reads standard input as under nomi run. A read still waiting when a file changes ends with the run, and a line typed while the program restarts goes to the new run. Ctrl-C stops the run and exits with status 130. A compiled program (.nomic) has no source to watch and is refused.

nomi run --profile <file> [args] runs the program and, when it ends, prints on standard error where its time went, by Nomi function:

nomi profile: 2.68s sampled over 2.68s, one sample every 1ms
garbage collector: 0.70s of CPU over 51 cycles, on threads beside the program

    self            total          function
   1.43s   53.1%    1.63s   60.6%  prefix_reversed  fannkuchredux.nomi:39
   0.37s   13.7%    2.00s   74.3%  flips  fannkuchredux.nomi:50
   0.20s    7.5%    0.20s    7.5%  List.concat  (host)
   0.18s    6.9%    0.18s    6.9%  insert_at  fannkuchredux.nomi:59
   0.14s    5.0%    0.45s   16.9%  next  fannkuchredux.nomi:89
   0.13s    4.8%    2.68s  100.0%  walk  fannkuchredux.nomi:105
   ...

A function’s self time is spent in its own code, and its total time adds what the functions it calls spent. A second table, after the functions, names the lines the time was spent at. A lambda is <lambda> at its line and column. A std function written in Nomi is marked std, and a function implemented in Go, such as Map.get or String.join, is marked (host). --profile=<file> also writes the profile to <file> in pprof’s format, which go tool pprof -http=: <file> shows as a call graph and a flame graph.

The VM samples the program every millisecond, at its next call or loop iteration, and when a call into Go returns, so a profile measures wall time: a call that waits for input, a timer or a task is charged with its wait. A function that ends in a tail call is replaced by the function it calls, as a tail call does, and drops out of the stack, except that a call into a std function (an Iter pipeline at the end of a function) keeps the caller under the std function. A caller is shown by its function, not the line it called from. The garbage collector runs on other threads beside the program, so its time is a total rather than a share. A profiled run is a few percent slower; one that is not profiled pays nothing. An executable nomi build wrote is profiled with NOMI_PROFILE (Environment variables).

nomi <file> [args] is nomi run <file> [args]. Together with a shebang line (spec §2 Shebang line) it lets a file run as a command:

$ cat hi.nomi
#!/usr/bin/env nomi
import std::io

fn main()
    io.print("hi")
end
$ chmod +x hi.nomi
$ ./hi.nomi a b

The operating system runs ./hi.nomi a b as nomi ./hi.nomi a b. Every argument after the file, flags included, is the program’s own: boot reads them as startup.args (spec §15 Scoped application fields), here ["a", "b"].

Subcommand names are matched first. After them, the first argument is a file when it ends in .nomi, whether or not it exists, so a missing x.nomi is reported as a missing file; no subcommand name ends in .nomi, so nomi test is the command and nomi test.nomi runs that file. Any other argument is a file only when it exists and its first two bytes are #!; otherwise it is an unknown command.

A .nomi script runs exactly as nomi run would run it, including the project root discovery below. A script alone in a directory such as ~/bin is its own project, and sibling scripts do not affect it unless it imports them. A .nomi script inside a module (a nomi.toml above it) is held to that module’s entry points, so it must be listed in entry_points unless it is one of the module’s tools under tools/.

Extensionless scripts. A file without the .nomi extension is a program when it starts with #!, so a command can be named like any other:

$ head -1 ~/bin/greet
#!/usr/bin/env nomi
$ greet world        # runs as nomi /home/me/bin/greet world

nomi run, nomi check, nomi test and nomi build accept such a file by path. Its project root is its own directory: root discovery looks for nomi.toml or main.nomi there and nowhere above, so a main.nomi in a home directory or a module around the script never changes what a command on PATH does. It imports .nomi files from its own directory and below, as import greeting reads greeting.nomi beside it, and nothing above it. Its module name is the file name, so a greet.nomi beside greet is a different file that import greet would read. A script in a module’s subdirectory is not one of the module’s entries and needs no entry_points line; one beside the module’s nomi.toml is, and is listed by its bare name. nomi check and nomi test on a directory still look only at .nomi files. A script binds Go as a .nomi file does: Go FFI discovery reads the script itself and the .nomi files of its project, but no other extensionless file beside it, and a gopkg resolves through the nearest go.mod above the script, as it does for any declaring file. A script that binds only Go standard library packages needs no go.mod.

The REPL compiles each input as one more file of the session’s program, which sees the declarations and top-level bindings of the inputs before it, and runs it on one live VM. An earlier input is never checked, compiled or run again, so an input takes as long in a long session as in a new one: a later input reads the value an earlier binding computed, and a closure keeps the value it captured. Redefining a function affects later inputs only, and so does redeclaring a type with a different declaration: earlier values, functions and impls keep the old type, and a later input that names the type gets the new one, which starts with no impls. When the two meet in an error, each is named by the input that declared it (expected Point (input 1), got Point (input 5)). Redeclaring a type exactly as it is keeps it, and redefining an impl replaces the old one everywhere. An input that fails to check, faults or is blocked prints its error and changes nothing.

An input may be any declaration a file may hold: fn, host fn, a type, an interface, an impl or derive, an import, gopkg, once, embed, test and group, and phrase and noun declarations. A phrase, noun or embed is redefined as a function is: an earlier function keeps the one it was written against. The REPL is no project, so its source locale is en and it reads no catalogs, as a file run outside a project does. An input continues onto the next line while a {, ( or [ is open, while it ends in an operator, and while a backtick or """ string is open.

nomi check <path> type-checks and compiles a program without running it. Code the program reaches that the compiler cannot lower is the error at its source that nomi run would stop with and nomi test would report as BLOCKED. A test file is checked as nomi test loads it, each case lowered and none run, and a directory’s test files, and a module’s beside its entries, are checked with the rest.

In a directory without entry_points, a file that another file there imports is checked through that importer, as nomi run loads it, and listed as ok <file> (through <importer>); a file nothing there imports is checked on its own. A failed check of a directory prints FAIL <file> for each file that holds errors, a file the program imports or a phrase catalog, with its errors below it, and an error two programs share once.

A file that does not parse reports every syntax error it holds in one run: the first of each declaration, and the first of each statement inside a body. A statement after a damaged one is read on its own, so one mistake gives one error. Type errors are reported once the file parses.

--hints also reports the hints the editor shows: a value as Type whose value has the type without it (code redundant-ascription), and an operand in a field’s new value that reads the field’s current value by its path, which .. writes (code restated-current-value), and a call whose Maybe the value’s refinement answers plainly, List.first(names) for a NonEmptyList names, whose NonEmptyList.first(names) is the element (code plain-counterpart). Each prints as hint: and fails no file; without the flag nomi check says nothing of them. A program with Go bindings, checked through its wrapper, reports none.

--format short prints each error as one path:line:col: message line instead of with its source lines (--format full, the default), as NOMI_DIAGNOSTICS=short does for every command.

--format json writes JSON Lines on stdout for a tool or an agent to read, as nomi test --format json does: a record per error, a record per file checked, and a summary last.

{"type":"diagnostic","file":"/abs/main.nomi","line":5,"col":12,"end_line":5,"end_col":15,"start_byte":54,"end_byte":57,"severity":"error","message":"List<Int> has no field 'len'","hints":["Nomi has no method calls: write `List.length(xs)`"],"fix":{"title":"Call `List.length`","edits":[{"line":5,"col":9,"end_line":5,"end_col":9,"start_byte":51,"end_byte":51,"text":"List.length("},{"line":5,"col":11,"end_line":5,"end_col":16,"start_byte":53,"end_byte":58,"text":""}]}}
{"type":"file","file":"/abs/main.nomi","status":"failed"}
{"type":"summary","files":1,"failed":1,"diagnostics":1}
  • file is absolute, or std/<module>.nomi for an error in the standard library. Lines and columns are 1-based, a column counts bytes, and an end is one past the last byte; start_byte and end_byte are the same points as 0-based byte offsets into the file. A span that is a point has no end.
  • severity is error, which stops the program, or warning, which fails no file and is not counted in the summary: an embed pattern whose folder does not exist yet (code embed-missing), or a type parameter the style guide writes as an interface value, with the fix that does (code interface-value-parameter, from nomi check only), or hint, under --hints only, which fails no file either. code names a diagnostic’s class when it has one (unused-import).
  • hints are the help: lines, and related the other places the error names, each with its own file, span and message.
  • fix, when present, is the rewrite the error knows: its edits replace each span’s text with text (an empty span inserts), applied together. Source written as another language writes it (let x = 1, xs.len(), match, Point{x: 1}, nil) carries one; the editor offers the same edits as a quick fix.
  • A "type":"file" record’s status is ok or failed; a file checked through an importer that loads it names it as through.

The exit status is the same as in text mode.

nomi tool <module> <name> [args] runs a module’s tool: the program tools/<name>.nomi at the module’s root, with the arguments after its name. A tool is an entry point without being listed in entry_points. It is an ordinary program, run in the current directory with the same access to files, the network and output that nomi run gives a program, and runs only when someone runs it. <module> is the current module’s name or one its go.mod requires. A dependency’s tool runs with the current project’s dependencies, at the versions its go.mod lists, as go run of a dependency’s command does; the dependency’s own go.mod only says which modules it needs. It is how a module ships a code generator, such as sqlkit’s nomi tool sqlkit generate (Databases), which writes ordinary .nomi files a program commits. A generator passes its text through compiler.format (std::compiler) before writing it, so nomi fmt -check finds the files it writes formatted.

nomi types <paths> [-o <file>] writes TypeScript declarations for the JSON a Nomi backend’s types cross as, so a frontend written in TypeScript shares the shapes of its API. Each path is a .nomi file or a directory, which names every .nomi file under it but those of another module (a directory with its own nomi.toml). The output declares each pub struct, enum, distinct type and typealias those files declare that crosses as JSON (it derives ToJson or FromJson, or implements ToJson by hand), and every type it reaches in any file, std types included, each once, in the order they are reached. It goes to stdout, or to the file -o names. The files are checked as nomi check checks their project: in each of its programs that loads one of them, so a file that reads an application field is checked under the entry whose fn boot returns the application. An error stops the command with its diagnostics. A path whose files declare no such type is an error. The command writes types only: no client, fetch wrapper or validation.

nomi types models.nomi api -o ../web/src/api-types.ts

A type maps to the JSON its ToJson writes:

NomiTypeScript
Int, Floatnumber
Stringstring
Boolboolean
Decimalstring, its exact digits ("12.50")
Uuidstring, lowercase 8-4-4-4-12 hex
Instantstring, RFC 3339 in UTC
Date, Time, NaiveDateTimestring (YYYY-MM-DD, HH:MM:SS[.fff], YYYY-MM-DDTHH:MM:SS[.fff])
List<T>, Vector<T>, Set<T>T[]
Map<String, V>Record<string, V>
Maybe<T>T | null; the field is always present
a structan interface of its fields under their JSON keys, rename_all applied
an enuma union: a bare variant’s name as a string, { Variant: payload } for the others, a tuple payload as [A, B]
a distinct typea type of its inner type
typealias A Btype A = B
a generic typea generic interface or type: Page<T>, referred to as Page<User>
a type whose ToJson is written by handunknown, with a comment that says so

An Int is a number because JSON.parse reads every JSON number as one, so an Int past 2^53 loses precision in JavaScript. An app that sends such Ints, such as 64-bit IDs, should send them as Strings. A Maybe field that ToJson writes as null may be missing in what FromJson reads, and so may a field with a default; the declarations describe what ToJson writes.

A declaration takes its Nomi name. When two files each declare a type of one name, each is named with its file’s name before it (ModelsUser, OrdersUser), and with its directories’ when the files share a name. A Nomi type named Record is named with its file’s too, since the declarations use TypeScript’s own Record. A /// comment on a type becomes its JSDoc comment.

nomi run, nomi check, nomi test and nomi build keep each program they check and compile in the artifact cache, <user cache>/nomi/artifacts (~/Library/Caches on macOS, ~/.cache on Linux, %LocalAppData% on Windows), or NOMI_ARTIFACT_CACHE. The next command over the same files reads it and checks and compiles nothing: an unchanged program of 50,000 lines runs in about 0.06 s instead of 2 s. A program is kept only when it checks with no error and every part of it a run or its tests reach can run, so a command that reads one prints exactly what it would print otherwise. A program with Go bindings is not kept.

A program is read again only while the files its build can read are as they were: its .nomi files and every other in its project and its dependencies, nomi.toml and the other .toml files (phrase catalogs), go.mod and go.sum, the files under a folder an embed pattern names, and any nomi.toml, main.nomi or go.mod above the project. Any change to them, or a new nomi, builds the program again; other files the project holds, such as what a run writes, change nothing. A file saved with the same text is not a change. The settings in NOMI_ variables are part of what is kept, so a command with other settings builds again.

std holds the standard library’s artifacts and programs the programs’. A program nothing has read for five days is removed by the next command that keeps one, which looks at most once an hour. The cache is safe to delete. NOMI_ARTIFACT_CACHE=off keeps and reads nothing, and NOMI_DEBUG_ARTIFACT_CACHE=1 says on stderr, for each command, whether it read a kept program and why not.