The CLI
Everything Nish does goes through one command, nish. It has two shapes:
nish run, which compiles a program and runs it at once, and the plain
nish <files>, which writes LLVM IR, a native binary or the files another
language needs to call your code. This page covers the flags you will reach
for; nish --help prints the whole list on stdout and exits 0, grouped by what
the flags are for (Build, Check, Capabilities, Interop, Inspect, Code
generation) and followed by the exit codes and a few examples. The
command-line reference is that list as a
page, generated from the same source.
usage: nish <file.ts> [more.ts ...] [flags] compile to LLVM IR
nish run [flags] <file.ts> [args ...] build, cache and run it
nish run --watch <file.ts> [args ...] rebuild and rerun it on each edit
nish upgrade [<version>] [--check] install a newer release
nish -v, --version | -h, --help
Running a program: nish run
nish run is the shape for scripts and for trying things out. It compiles the
file, links it into a cache, and starts it with the rest of the command line
as its arguments:
export const main = (): i32 => {
const args = process.argv;
for (let i: i32 = 1; i < args.length; i++) {
console.log(`argument ${i}: ${args[i]}`);
}
return 0;
};
$ nish run args.ts one two --help
argument 1: one
argument 2: two
argument 3: --help
-
Flags before the file are the compiler's, everything after it is the program's,
--helpincluded.nish run --number-mode f64 tool.ts xcompiles in f64 mode and hands the programx. -
The program owns the terminal. Its stdin, stdout and stderr are the program's, and so is the exit status once it starts. Performance warnings are not printed under
nish run, because stderr belongs to the program; runnish tool.tswithoutrunto see them. -
Every run compiles, and a link happens only when something changed. The first run after an edit links the program (with the fast
debugprofile, unless you pass--profile), and every run after that starts the binary it already linked. Underdebug, the link compiles only the modules your edit changed: a one-line edit to a 5,000-line server rebuilds in about a second and a half on four cores, against about five seconds for the first link. -
What
nish runcaches, under$XDG_CACHE_HOME/nish, or~/.cache/nishwhen that is unset:Directory Holds Kept for runone linked binary per program the same program, built the same way runtimethe C runtime, compiled once per profile every link with that profile moduleeach module's object, debugprofile onlythe same module, unchanged An entry is used only when everything it was built from is unchanged: the compiler, the profile and its flags, the C compiler, and the code itself. The
speedandsizeprofiles do not usemodule, so their binaries are exactly what a build without a cache makes. Without an absoluteXDG_CACHE_HOMEorHOME, or whennish/modulecannot be made private to you (mode 700, owned by you), the link skipsmoduleand compiles every module, as the first link does. -
The cache is safe to delete. Removing any of these directories costs one rebuild and nothing else. Nothing prunes them, so delete
nish/modulenow and then if a program you edit often has grown it.
Flags that write a file the run would keep to itself — -o, --link,
--target, the --emit-* sidecars and --profile wasi — are usage errors
under nish run.
Rebuilding on each edit: --watch
nish run --watch builds and runs the program as nish run does, then
watches every file the program was built from. When one changes it builds
again and puts the new program in place of the running one:
$ nish run --watch server.ts 8080
watch: built in 1830 ms
listening on 8080
watch: rebuilt in 412 ms
listening on 8080
-
What is watched is the entry file and every module it imports, as far as the last build got to load them, so a build that fails in an imported module rebuilds when you fix that module. The standard library is left out, since an installed
nishdoes not change under you; run from a checkout of the compiler,std/is watched too. -
A failed build changes nothing. Its diagnostics are printed, as plain
nish runprints them (one JSON object per line under--json), followed bywatch: the build failed; the running program keeps running, and the program you had keeps running until the next edit builds. When no program is running yet, the line endswaiting for a changeinstead. -
Edits are gathered, and the newest wins. A change waits a tenth of a second for the editor's next write before it builds, and an edit during a build stops that build and starts a new one, so the program that runs is always built from the files as they are.
-
A server is started before the old one stops. A program that uses the network is taken for a server: the new build starts while the old one still runs, and once the new one has lasted a moment the old one is sent SIGTERM, then SIGKILL if it has not exited after five seconds. Listen with
SO_REUSEPORT(tcpListenFlags(host, port, backlog, 1)) so both can hold the port at once, and answer SIGTERM by accepting what is queued and finishing the connections you have accepted.On Linux, also turn on
sudo sysctl -w net.ipv4.tcp_migrate_req=1(Linux 5.14 and later): without it, closing the old listener resets any connection the kernel queued on it after the server's last accept, so an occasional request across a rebuild fails with a reset. A server that does all three loses no request. A server that does not setSO_REUSEPORTcannot bind beside the old one: the new build exits as it starts, that is reported, and the old one keeps serving the old code. A network client is taken for a server too, so for a moment after each rebuild the old and the new copy both run. -
Any other program is stopped, then started again, with the same SIGTERM and SIGKILL, because two copies would write the same terminal and files. A program that exits on its own leaves the watch waiting for an edit.
-
Each run sees
NISH_WATCH=1in its environment, so a program can tell it is being watched, and each build prints how long it took. -
Ctrl-C stops the watch and the program and leaves nothing running. The exit status is the one an interrupted program has (130 in a shell). If the
nish run --watchprocess itself is killed, the watch stops the program and exits as a hangup does (129).
--watch is a flag of nish run; nish --watch app.ts is a usage error
(exit 2).
Compiling: IR and binaries
Without run, nish compiles the entry file and every module it imports.
| Command | What it writes |
|---|---|
nish app.ts |
app.ll, the LLVM IR, beside the source |
nish app.ts -o out.ll |
the IR at that path (one module only) |
nish app.ts -o build/ |
one .ll per module in build/ (the trailing / matters) |
nish app.ts --link app |
a native binary app, plus its IR; the entry must export const main |
--link needs clang and lld on your PATH; installing them is in
Installation. The flags you are most
likely to add to it:
-
--profile speed|size|debug|wasi—speed(the default) is-O3with link-time optimisation (its code generation spread over every core when the link goes through lld) and a stripped binary;sizeoptimises for bytes;debuglinks fastest and keeps symbols;wasibuilds awasm32-wasimodule instead of a native binary. Every native profile links a hardened binary: position independent, with a read-only GOT (full RELRO), a non-executable stack, stack-clash probes, control-flow protection (CET on x86-64, BTI and pointer authentication on arm64) and the stack protector in the C runtime.You do not need a flag for it, and
node scripts/check-hardening.mjs <binary>in a checkout reads the protections back from a binary's headers. On Linux every native binary also carries a GNU build id (anNT_GNU_BUILD_IDnote;readelf -n appshows it), whichperf,gdband debuginfod use to match a binary with its debug information. The id is a hash of the binary's bytes, so linking the same program twice gives the same id, while two different builds (a-glink and a plain one, or two profiles) give different ones. -
--cpu x86-64-v3— compiles your program and the runtime for x86-64 CPUs with AVX2 (Intel Haswell, AMD Excavator and later), which can make tight loops faster. It is the one levelnishaccepts; anything else, and the flag with--profile wasior a non-x86-64--target, is refused with exit 2. What your program computes does not change. A binary built with it crashes withSIGILLon a CPU without AVX2, so use it only for binaries that stay on machines you know; ship anything else without it. -
--debug-arena— links a runtime that catches a stale reference to arena memory. Every allocation gets memory pages of its own, and when the scope that made it ends, those pages are made unreadable and never handed out again. A program that still reads such a value stops at that read instead of seeing whatever was allocated there next:nish: --debug-arena: stale arena reference at 0x00007e9a73001010: the memory was released by the scope that allocated itand it dies of
SIGSEGV(exit status 139 in a shell). The compiler's escape rules mean a correct compiler never builds such a program, so this is a mode for tests and fuzzing, to catch a compiler or runtime bug, not for a binary you ship: each allocation takes at least a page and no address is reused, so a program runs slower and uses more memory under it. It needs--linkornish run, and is refused with--profile wasi. -
-g— DWARF debug info, sogdbandlldbstep through your.tssource.To ship a binary without its debug information and keep that information beside it, split the
-gbuild rather than linking twice, since a second link would carry a different build id:nish app.ts --link app -g objcopy --only-keep-debug app app.debug strip -g app objcopy --add-gnu-debuglink=app.debug appappandapp.debugshare one build id, sogdb, debuginfod orperf buildid-cache -a app.debugmatch the shippedappwith the DWARF inapp.debug, and source lines come back for it. (strip -gkeeps the symbol table, so function names resolve without the debug file.) -
--number-mode f64— makes a barenumbera 64-bit float rather than the defaulti32. Code that spells its widths (i32,f64) means the same thing in both modes.--compatimplies it. -
--target <triple>or--target host— stamps the IR with a target's data layout, for cross-compiling or for reading optimised IR by hand.--linkdoes not need it. -
--host <file.ts>— makes that file a host module: a TypeScript file of the page's whose exported functions a--target wasm32build imports from the page. Repeat it for each one; a rootpackage.json's"nish": { "host": [...] }names them too. A native or WASI build that imports one is refused.
Optimizing a build with a profile
A profile-guided build links your program twice. The first link is an instrumented binary: it counts which branches and calls your program takes. You run it on real work, and the second link uses those counts to lay out and inline the code. Four commands:
nish app.ts -o build/app.ir/ --link build/app.instr --pgo-generate
LLVM_PROFILE_FILE=build/app-%p.profraw build/app.instr <a representative run>
llvm-profdata merge -o build/app.profdata build/app-*.profraw
nish app.ts -o build/app.ir/ --link build/app --pgo-use build/app.profdata
- The profile covers the whole binary. The runtime and, when your program calls it, SQLite are compiled with the same flag, so the hot paths in them are optimised too. Such a link compiles every unit itself rather than reusing the runtime cache, so it takes longer, and it never leaves an instrumented object behind for a plain link to pick up.
-
Train on what production sees. Run the instrumented binary on input
shaped like the real thing: the binary is fast where the training was.
Each run writes one
.profraw(%pputs the process id in the name); merge them all. -
A profile belongs to one machine and one LLVM. Train and link on the
same toolchain;
llvm-profdataandclangof another LLVM version may refuse the file. Don't commit a.profdata: regenerate it. -
What is refused. Each flag needs
--linkand thespeedorsizeprofile, builds for this machine only, andnish rundoes not take it; a--pgo-usefile must be the merged.profdata(a raw.profrawis refused with themergecommand to run). Each is a usage error, exit 2.llvm-profdatamust be on yourPATH(Ubuntu'sllvm-18installs it asllvm-profdata-18; link that asllvm-profdata); without it the link stops with exit 3. The instrumented link also needs compiler-rt's profile runtime (libclang-rt-18-devon Ubuntu).
The rules are in the language reference, Profile-guided builds.
The sidecars that let C, Node and WebAssembly call your code —
--emit-header, --emit-napi, --emit-dts — and host modules have a page of
their own: Calling Nish from other languages.
SQLite is linked when your program calls it
nish ships SQLite 3.54.1 as source, and --link
compiles it into a program that calls a SQLite C function (sqlite3_open, or
any other sqlite3_*). You need no SQLite library on your system, and a
program that does not call SQLite gets none of it.
declare function sqlite3_libversion(): string;
export const main = (): i32 => {
console.log(sqlite3_libversion());
return 0;
};
$ nish run version.ts
3.54.1
-
The first link that uses it is slower. SQLite is about 9.6 MB of C. The
first link compiles it once, which takes about 1.5 s under
debug(andnish run) and about 18 s underspeed.nishkeeps the result in the runtime cache, so every later link takes about as long as one without SQLite. -
One thread, unless you build with
--threads. SQLite is compiled withSQLITE_THREADSAFE=0, and with=2under--threads: multi-thread mode, where no mutex guards a connection, so open one per thread and never share it. -
The defaults are most of SQLite's
recommended options.
Two are left out.
SQLITE_OMIT_DECLTYPEwould removesqlite3_column_decltype, which reports a column's declared type.SQLITE_OMIT_AUTOINITwould make any call beforesqlite3_initialize()undefined behaviour. -
NISH_SQLITE_CFLAGSadds compile-time options. Its words are added to SQLite's compile line, and a-Dor-Ufor an optionnishalready sets replaces it. For example,NISH_SQLITE_CFLAGS="-DSQLITE_ENABLE_FTS5"adds full-text search. The cache keeps a separate copy for each value. Only the first line is read, and it is split on whitespace: quotes are not removed, so a word cannot hold a space. A relative-Ipath is taken fromruntime/sqlite/, where SQLite is compiled, so give an absolute one. -
--profile napilinks it with hidden visibility. The addon uses SQLite but does not export its functions to Node or to other addons. -
--profile wasilinks it. There SQLite locks a database with lock files and has no WAL mode across processes.scripts/build.sh --profile wasm, which links no C library, refuses a module that calls SQLite with exit 2.
Writing TypeScript: --emit-ts
nish app.ts --emit-ts out/ writes your program back out as TypeScript that
Node runs, one file per module, and no IR:
nish app.ts --emit-ts out/
node out/entry.ts
The output imports its runtime from the nish package, as nish/runtime, so
Node has to find nish from out/, the way it finds any dependency. Node
22.18 or newer runs it, with the type stripping it has on by default. A program that uses using needs Node 24, or
--js-explicit-resource-management on Node 22.
Inside out/:
-
Your modules keep their paths relative to the directory they share:
app.tsandlib/tally.tsare written asout/app.tsandout/lib/tally.ts. -
Each standard-library module your program imports is written under
nish/, sonish/pairbecomesout/nish/pair.ts. -
entry.tsruns yourmainand exits with the number it returns. In a program with anasyncfunction it awaitsmain, then every taskspawnstarted, before it exits. -
nish-storage.ts, in a program with module storage, holds that storage as the wasm loader lays it out: it exportsmemory,layout,views,loadSyncandload, so a page written against the loader runs against this reading too.
Imports are rewritten so Node can follow them. A nish: builtin becomes
nish/runtime, the one package the output imports, nish:secret included
(nish:async alone becomes nish/runtime/async.mjs): its wipe is the
runtime's, and std/secret.ts is not written. A nish/x or relative import
becomes a relative path ending in .ts. A host module (--host) is not
written: the import points back at the page's own file, relative to out/. An
imported interface or type alias is marked import { type Pair }.
A module that needs none of this, and none of the rewrites below, is written
byte for byte; one rewrite that reaches an otherwise plain module is const s = "hi", written const s: string = "hi" so TypeScript does not narrow s to
the literal.
Some constructs JavaScript spells differently are rewritten too:
-
x.orReturn()becomes a local,const __t0 = x;, andif (__t0.isErr()) return Err(__t0.error);before its statement, with__t0.valuein its place. Where that would change when the call runs — the right of&&, a branch of?:, a loop's condition, after a call in the same statement — it stays a call, and the function around it gets atrythat turns the call's throw into theErrit returns. -
An
enumbecomes aconstobject of its members' values and a type of the same name:enum Shape { Circle, Square = 4 }is written asconst Shape = { Circle: 0, Square: 4 } as const;andtype Shape = (typeof Shape)[keyof typeof Shape];. A string enum's members keep their strings:enum Role { Admin = "admin", Guest = "guest" }is written asconst Role = { Admin: "admin", Guest: "guest" } as const;with the sametype Role, andString(r)stays as it is, since JavaScript'sStringof a string is that string. -
Arena.used()andArena.mark()becomenish/runtime'sarenaUsedandarenaMark, and aResultannotation importsResultfrom it. -
An element read
a[i]whose index the compiler cannot prove in range becomesidx(a, i), and a storea[i] = vbecomessetIdx(a, i, v). Both panic out of range as the native check does, where JavaScript would readundefinedor grow the array. A compound storea[i] += vchecks the index again aftervruns, at a proven index too, sincevcan shrink the array. -
new Array<T>(n)becomesnewArray(n, zero), filled withT's zero (0,0n,false, ornullfor a nullableT) where JavaScript would leave holes. Ani64oru64length goes throughNumber. -
A record an array holds inline is copied as it goes in:
xs.push(p)pushes{ ...p }, andxs[i] = pwritesp's fields into the record already in the slot, so a later change topleavesxsalone, as it does natively. A(P | null)[]holds references and copies nothing. -
i32arithmetic that can overflow,a + b,a - b,a * band-a, becomescheckedAdd(a, b),checkedSub,checkedMulandcheckedNeg, which panic as the native build does; where the compiler proved the result fits, it is(a + b) | 0orMath.imul(a, b)./and%becomeidivandirem. -
dst.set(src, at)between two arrays of one type becomesarraySetAt(dst, src, at), the copy a plain JavaScript array lacks, which panics past the end as the native one does.
The flag also turns on --warn-portability. Those warnings name the places
where your program can answer differently under Node.
Seven kinds of module cannot be written. In each case nish exits 1 and
writes no file:
app.ts:4:1: error: --emit-ts cannot write a module that declares C functions; keep it native and import it through --emit-napi
app.ts:4:1: error: --emit-ts cannot yet write signalFd, readSignal or nish:net, whose translation is not local to its statement
app.ts:6:3: error: --emit-ts cannot write this compound assignment, whose target it would read twice and which holds a call, a step or an element read: hoist the index into a const
app.ts:9:1: error: --emit-ts cannot write this generic, whose instances would be written as different TypeScript: an element held inline in one and by reference in another, or two element types with different zeros; write a function per element type
app.ts:12:15: error: --emit-ts cannot write this generic, which no instance reaches: its body copies or zero-fills an element whose type only an instance would say; call it with the element type it is for, or write a function per element type
app.ts:1:1: error: --emit-ts cannot yet write a module that imports nish:region, whose regions the TypeScript runtime does not answer; keep it native
app.ts:3:1: error: --emit-ts cannot yet write an async function, whose resume order the TypeScript runtime does not answer yet; keep it native
The second is reported at each nish:net import and at each call to a
nish:net function, signalFd or readSignal, imported or not.
The third is reported at an x op= e that Node needs written as
x = x op e, such as += on a u8 that has to wrap, when the index in x
holds a call, a ++, or another array read: hist[data[0]] += 10. Read the
index into a const first, const at = data[0], then hist[at] += 10.
The fourth is reported at a generic function that TypeScript writes once
for all the types it is called at, when those types need different code: a
record held inline in one call and a P | null reference in another, or an
i32 and an i64 element in new Array<T>(n), whose zeros differ. Write a
function per element type.
A generic nothing calls is written too: a function or method, or the methods
and constructor of a class no type argument list names. The native build
compiles no body for it, so there are no types to translate by. Where no type
would change its text, it is written as it is, with only the rewrites that
need no type, such as the bounds check on a[i].
Where a type would (a 64-bit integer, an f32, a builtin call such as toU32,
arithmetic whose width wraps, a string's .length or methods), it is written
with a body that throws instead, and a warning (portability:, NL8012) names
it and its line when it is the program's own; the standard library's are
written without one.
The fifth refusal (NL4014) is a generic of your own whose body fills new Array<T>(n) with T's zero, or copies an element into an array slot in a
program that keeps records inline: which code those need depends on a T no
call names, so it is refused rather than stubbed, even where a 64-bit integer
or a builtin call in the same body would have made it a stub. Call it, or write
a function per element type.
The same body in the standard library is a stub, and the program is written.
The sixth (NL4015) is a program that imports nish:region: the TypeScript
runtime has no regions to allocate into yet, so keep that program native.
The nish:unsafe functions are imports from nish/runtime too:
uncheckedGet, uncheckedSet and the wrapping* arithmetic run under Node,
and readCString and readStruct, which read C memory, have no export, so
a program that calls either does not run under Node.
The nish:term functions are written as imports from nish/runtime too, and
they resolve. Under Node, isTerminal and terminalSize answer, and
readStdin, waitStdin, setRawMode and setTerminalRestore throw, naming themselves, as they do
when a program is run under Node.
--emit-ts writes a directory instead of IR, so it exits 2 if you also
pass -o, --link, --emit-ast, --emit-checked, --emit-header,
--emit-dts, --emit-napi or --emit-napi-async, or give it an empty
directory. It also exits 2 when a
module lies above the directory of the others (../shared/s.ts), or when two
modules would land on one file — a module of your own at nish/pair.ts and
the standard library's nish/pair, say. And it exits 2, before writing
anything, when a file it would write is one of your own sources: --emit-ts .
next to app.ts would write over it, so give it a directory of its own.
--emit-panics, --emit-arena and --emit-capabilities still write their
files alongside --emit-ts, and they are written before the TypeScript, so
they are there even when the program is refused or its modules cannot be laid
out.
Reading diagnostics
An error prints with its position and an excerpt, and the compile exits 1:
export const main = (): i32 => {
const x: i32 = 1;
if (x == 1) {
return 1;
}
return 0;
};
$ nish bad.ts
bad.ts:3:7: error: Loose equality is forbidden; use === / !==
3 | if (x == 1) {
| ^~~~~~
Every code, with its rule and an example program that provokes it, is in the diagnostic index.
A compile reports every error it finds, in source order, up to 20. Besides
errors there are performance warnings — the compiler took a slow path and
names the faster one — which are on by default, print on stderr and never
change the exit code. --no-warn-performance silences them.
--json, for tools
--json prints each diagnostic as one flat JSON object per line on stdout,
with nothing else on stdout:
$ nish bad.ts --json
{"file":"bad.ts","line":3,"column":7,"endLine":3,"endColumn":13,"severity":"error","code":"NL1047","message":"Loose equality is forbidden; use === / !==","fix":[{"line":3,"column":9,"endLine":3,"endColumn":11,"text":"==="}]}
- Lines and columns are 1-based, and
endLine/endColumnare exclusive. -
codeis the field to match on.NL1047will mean the same rule in the next release; the wording ofmessagemay improve. The first digit names the stage that found it:NL1xxxforbidden syntax,NL2xxxthe type checker,NL3xxxmodules and the driver,NL4xxxthe interop sidecars,NL7xxxdeprecations,NL8xxxportability,NL9xxxperformance; the diagnostic index lists them all. -
severityis"error","performance","portability"or"deprecation". Only errors fail a compile. -
package, aftermessage, names the dependency when the diagnostic is in a package's own source (node_modules/<pkg>/…); it is absent for your program's files and the standard library's. -
Failures with no source position — no usable
clang, an internal error — are JSON objects too, so under--jsonyou never need to read stderr. -
review, afterfix, is on some portability warnings (--warn-portability): the same kind of edit list, for a rewrite that makes the line mean the same under Node and compiles to the same native code, but changes what your source says.nish --fixnever applies it; see below. -
The standard library has a reader for these objects:
nish/json.
--fix
Some diagnostics carry a fix: the edits that make them go away, attached
only when the rewrite plainly means what you wrote. nish --fix <files>
applies them to the files you name, recompiles, and repeats until nothing
changes, then reports what is left exactly as a plain run would, and exits
with that run's code:
$ nish --fix bad.ts
fixed bad.ts (1 edit)
$ grep '===' bad.ts
if (x === 1) {
It never edits a standard-library module or anything under node_modules,
and it writes no IR, so -o and --link are usage errors beside it. It
rewrites your files in place with no backup, so run it on a tree you have
committed.
--fix applies fix and nothing else. A portability warning's review is
a suggestion for you, or the agent driving nish, to read and apply by hand:
an integer division wrapped in its own type's conversion, which truncates
under Node as it does natively and adds no instruction. For a half.ts of
const half = (n: i32): i32 => n / 2;
--json prints:
$ nish half.ts --warn-portability --json
{"file":"half.ts","line":1,"column":31,"endLine":1,"endColumn":36,"severity":"portability","code":"NL8006","message":"this `/` on i32 truncates here, and TypeScript divides exactly","review":[{"line":1,"column":31,"endLine":1,"endColumn":31,"text":"toI32("},{"line":1,"column":36,"endLine":1,"endColumn":36,"text":")"}]}
Applied, n / 2 reads toI32(n / 2), and the warning is gone. Apply a
run's edits together, from the end of the file back, each placed in the
original text: a / b / c gets two edits that both insert toI32( at one
place, and applied that way they nest, toI32(toI32(a / b) / c). Wrapping
arithmetic (NL8007) and >>> on an i32 (NL8008) get no review: no
spelling of them reads the same under Node without costing an instruction
here. A division gets none either in a generic function; where an operand's
type differs from the conversion's; for an i64 or u64, which no
conversion leaves alone; for a /= on a field, an element or a ranged
target, or with a comment before it; or in a file that binds a name
toI32, toU8, toU16 or toU32 of its own (a function, const,
parameter, loop variable, field, method or import), which the edit would
call instead of the conversion. The full list is NL8006's row in
the language reference.
Colour, and when an agent runs nish
nish --help and the compiler's errors and warnings are coloured when they
print to a terminal and plain when they are piped or redirected, so
nish --help | less and nish app.ts 2> errors.txt hold no escape
codes, and --json never has any. A diagnostic shows its location in bold,
error: in red or a warning's label in yellow, the message in bold with each
`name` in cyan, the line-number gutter faint, and the offending code and
its ^~~ underline in the label's colour; with the escapes taken out it is
the plain text byte for byte. These variables change when colour is used:
| Variable | Effect |
|---|---|
NO_COLOR, not empty |
never colour; it wins over everything below |
FORCE_COLOR set to 0, false, no or off, in any case |
never colour, even on a terminal |
FORCE_COLOR or CLICOLOR_FORCE, neither empty nor one of those |
colour even when piped, unless an agent is running nish |
CLICOLOR set to one of those, or TERM=dumb |
no colour, unless one of the two above forces it |
The colours are your terminal's own: the basic ANSI colours, bold and faint,
which your theme defines, so the help takes on whatever palette you chose (a
terminal with no theme shows its built-in defaults). On a terminal whose
TERM terminfo entry declares no colours at all (tput colors prints fewer
than 8, as it does for TERM=vt100), the help marks headings and flags in
bold and placeholders with an underline instead, and a diagnostic keeps its
bold and faint parts without the colours, which a monochrome terminal still
shows.
Forced colour (FORCE_COLOR, CLICOLOR_FORCE) is always the theme's,
whatever TERM says, because what reads it is a pager or an editor that
paints the escapes itself. Your own tools can print a help that behaves the
same way with nish/cli.
Coding agents get plain output and a help with an extra section. When
nish runs under an agent — CLAUDECODE or GEMINI_CLI is set to anything
but empty or a no (0, false, no, off), or you set NISH_AGENT the
same way (NISH_AGENT=1) — neither the help nor a diagnostic has colour, even
on a terminal or with FORCE_COLOR set, and the help ends with an Agents
section: the absolute path of docs/AI.md (the language as rules, traps
first) in the installed package, and the flags an agent's loop needs —
--json, --fix and nish run.
NISH_AGENT=0 (or false, no, off) turns this off when one of those
variables is set for some other reason. If the package's docs/AI.md cannot
be found, the section names it without a path.
Staying up to date: nish upgrade
nish upgrade installs the latest release when it is newer than the compiler
you are running, and does nothing when it is not:
nish upgrade # the latest release, if it is newer
nish upgrade 0.40.0 # a version you name, newer or older
nish upgrade --check # print the version you have and the latest; install nothing
--check prints two lines, current 0.39.0 and latest 0.40.0, and exits
0, or 3 when the latest cannot be found: no network, GitHub refusing or slow
to answer (it waits at most two seconds).
How it installs depends on how you installed:
-
With the install script (
~/.nishor your--dir): it fetches the release's owninstall.sh, from that release's tag and nevermain, into a private file, and runs it assh install.sh <version> --dir <your install>. The script checks the download and swaps the new compiler in only once it runs, as Installation describes. With no version named it never installs an older release, or the same one; a version you name that is older is installed, with a line saying it is a downgrade. -
With npm: npm owns the files, so it prints the command to run,
npm install -g nish@<version>, and exits 2 without changing anything. - From a checkout: it refuses with exit 2. Pull and rebuild instead.
A version must be a semantic version, such as 0.40.0 or 1.0.0-rc.1:
three numbers with no leading zeros, then an optional -prerelease and
+build. Anything else, such as 1.2 or 1.0.0/../x, is a usage error
(exit 2) before anything is fetched.
The update notice
When a newer release is out, a command run on a terminal that exits 0 or 1
(a compile, nish --version, nish --help, --describe and the like) ends
with one line on stderr:
nish 0.40.0 is available (you have 0.39.0); run `nish upgrade`
It never changes stdout or the exit code. Finding out costs nothing you wait
for: the answer comes from a cache under ~/.cache/nish/release (or
$XDG_CACHE_HOME), and when that is missing or more than a day old a check
runs in the background, so GitHub is asked at most once a day. The line is
never shown:
- when stderr is not a terminal (piped, redirected, or under a script),
- with
--json, - in
nish run, whose stderr is your program's, - in CI (
CIset to anything but empty,0orfalse), - with
NISH_NO_UPDATE_CHECK=1, which also stops the check itself.
A cache another user could have written is ignored and replaced, so nobody else chooses what the line says. What the check trusts is in the security record.
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | the program was rejected: a compile error, or an input file that does not exist |
| 2 | usage error: an unknown flag, a missing argument, no input files |
| 3 | toolchain error: no usable clang, or the link failed (the .ll files are still written); for nish upgrade, no answer from the release server, or the installer failed |
| 70 | internal compiler error: a bug in nish, not in your program — please report it with the input, the command line and the message it printed |
nish run answers these codes until the program starts, and the program's own
exit status after that — the value main returns, 1 for a panic such as an
index out of range, or 128 + n for a signal.
Asking what a program can do
A few flags report on a program rather than build it; each but --sandbox
leaves the IR unchanged.
-
--capabilitiesprints, on stderr, what the program can reach — files, processes, the network, the environment, the clock and so on — and--allow <cap>/--deny <cap>refuse a program that reaches more than you grant. A call to anish:unsafefunction, in your code or in a dependency's, shows up asunsafe, and--deny unsaferefuses it.nish run --capabilities hello.tsprintscapabilities: none (deterministic)before the program's own output. See Capabilities. -
A dependency needs your grant for
unsafe,ffi,netandprocess.spawn. A package undernode_modulesthat reaches one of them, itself or through anything it calls, stops the build until yourpackage.jsonnames it:{ "nish": { "capabilities": { "dependencies": { "pkg_http": ["net"] } } } }Without it the build stops with exit code 1, and the error names the grant to add and the calls that reach the capability:
node_modules/pkg_http/src/index.ts:6:10: error: the dependency `pkg_http` reaches `net` through `dial`, which the root package does not grant it; grant it with "nish": { "capabilities": { "dependencies": { "pkg_http": ["net"] } } } — the chain that reaches it: node_modules/pkg_http/src/index.ts:6:10 calls netAddressOnly your own
package.jsongrants:--allowdoes not, and neither does the dependency's. The standard library needs no grant. See A dependency's capabilities. -
--update-capability-lockwritesnish-capabilities.lock.jsonbeside yourpackage.json: every capability each dependency reaches, granted or not. Commit it. While it exists, an upgrade that makes a dependency reach something new stops the build with exit code 1, naming the dependency, the capability and the calls, until you read the chain and run the flag again:node_modules/pkg_http/src/index.ts:6:10: error: the dependency `pkg_http` reaches `net` through `dial`, which `nish-capabilities.lock.json` does not record for it; review the chain, then record it with `--update-capability-lock` — the chain that reaches it: node_modules/pkg_http/src/index.ts:6:10 calls netAddressA dependency that reaches less than its row records is fine. A build the grants refuse writes no lockfile.
nish runtakes the flag;--fixand--emit-astdo not. See The capability lockfile. -
--sandboxgoes one step further on Linux: the built program asks the kernel, beforemainruns, to refuse the files, processes and sockets itsmaindoes not reach — C code it links included. It adds a few lines to the IR. With it,--allow fs.read=<dir>and--allow fs.write=<dir>grant a capability beneath one directory. See The sandbox. -
--deterministicmakes floats answer the same bits on every target: natively on x86-64 and Arm, in a wasm build, and in the--emit-tsreading under Node.Math.sin,cos,exp,log,powand a float%run the standard library's own versions instead of the platform's, andf64ToBitsgives one bit pattern for every NaN.Number(s),parseFloat(s)andparseInt(s)read a string the way the--emit-tsreading does, so a hex float such as"0x1p3"is not read as 8. A program that reads the clock, a random number, the environment, a file, the network, another process, the terminal, C code or a page's host import is refused, because those answer differently on every run. Exit code 1, naming the call:main.ts:2:15: error: `main` reaches `clock`, which `--deterministic` refuses: the clock and the random source answer differently on every run; the chain that reaches it: main.ts:2:15 calls Date.nowUse it for a simulation a server and a browser both run and must agree on (
--deterministic). -
--compatselects the compatibility dialect, which accepts more of TypeScript than Nish does by default: a barenumberis a 64-bit float, as--number-mode f64makes it, and its features (nullish,optional-chaining,string-switch,for-of-string) admit forms the strict dialect refuses.--compat=<feature>,...allows only the features it names, and a name that is no feature is a usage error (exit 2)."compat"in yourpackage.json's"nish"field selects the dialect without the flag.nish runand--fixtake it too (The compatibility dialect). -
--deny-panicsturns every panic the compiler cannot prove away into an error, and--emit-panics <file.json>lists them all. A call toreadCStringorreadStructfromnish:unsafeis refused there: each tests its pointer and panics withffi-nullonNULL, a check no proof removes (The no-panic scope). -
--explain-memoryprints every loop and function that keeps the memory it allocates past its arena scope, and why (Memory).nish runtakes the flag;--emit-ast,--jsonand--fixdo not. -
--explain-layoutprints one line for each class: whether the compact-class rule would pick it, or the first of the rule's five tests that refuses it, with its size in bytes now and with its links narrowed to 4 bytes (Memory). A generic class gets one line for each of its instantiations, named as written in a type (TNode<i32>), at the generic class's declaration. An instantiation from the standard library is marked(std). A generic class that nothing instantiates gets no line. Nothing uses the verdict yet, and the flag changes no byte of the build. Only a native executable can pick a class: a build with--link, ornish run. Every other build refuses every class at the first test: IR alone (-owith no--link), which a host may link; a wasm32 target;--emit-ts,--emit-header,--emit-napi,--emit-napi-asyncand--emit-dts; and a program that declares a C function. The report is printed once the program checks cleanly and passes the build's own refusals, so a program with errors prints none, and nor does one with nomainunder--link,--emit-ts,--sandboxornish run.nish runtakes the flag;--emit-ast,--jsonand--fixdo not. -
--emit-astand--emit-checkedprint what the compiler parsed and what its checker recorded, one line per node.
The reference for diagnostics and the flags that shape them is Diagnostics and debugging flags; the exit codes and the caches are also described in INSTALL.md.

