Process & CLI

The command-line arguments, in Node's shape: argv[0] and argv[1] are the executable's absolute path (a compiled program is its own script) and the arguments follow, so process.argv.slice(2) is what the user typed. An out-of-range read is undefined.

string[] — The argument vector.

const args: string[] = process.argv
for (const a of args) console.log(a)

Environment variables, via both dot and bracket notation. A missing variable is undefined (typeof included), so ??, === undefined and narrowing behave as in Node.

string | undefined — The value, or undefined if unset.

const path: string = process.env.PATH ?? "no PATH set"

Exits the process: the code (validated like exitCode, or process.exitCode when omitted) becomes the exit code, 'exit' fires once, then C exit(); code after it is unreachable.

never — Does not return.

Reads all of stdin (file descriptor 0) to its end, blocking — the Node idiom for a CLI tool that takes piped input. A line-at-a-time read is the readline module.

string — Everything on stdin.

import { readFileSync } from 'fs'
const input = readFileSync(0, 'utf8')
console.log(input.split('\n')[0])

Config, data, and log I/O for a CLI program — the full sync/async/stream fs surface has its own reference page.

The current working directory, via POSIX getcwd(NULL, 0) (auto-sizing).

string — The current directory.

const startDir: string = process.cwd()

Changes the current working directory via POSIX chdir(). A failure throws Node's error: ENOENT: no such file or directory, chdir '<cwd>' -> '<dir>', with errno, code, syscall, path and dest.

void — Nothing.

process.chdir("/tmp")

The current process ID, via POSIX getpid(). A property read, not a call.

number — The process ID.

A pure compile-time constant ("darwin"/"linux"/"win32"/…) baked in at codegen — no runtime code. Under the --target cross-compile flag it follows the target: codegen reads the target OS/arch through a target abstraction, so an OS-aligned (e.g. Linux→Linux) or macOS→Linux cross build bakes the target's platform, not the build host's.

string — The OS platform.

console.log(process.platform, process.arch)

A compile-time constant ("arm64"/"x64"/…) from the Go compiler's runtime.GOARCH, exactly like process.platform.

string — The CPU architecture.

The absolute, symlink-resolved path of the running executable — the compiled program is itself the binary (no separate runtime). Always absolute like Node's, not a raw argv[0].

string — The executable's absolute path.

Emits the process 'warning' event on the next tick with an Error whose name is the type ("Warning" by default), with code and detail when given; the default listener prints (node:<pid>) [<code>] <name>: <message> and a <detail> line to stderr, as Node's does.

void — Nothing.

process.emitWarning("legacy call site", { type: "DeprecationWarning", code: "DEP001" })

Sends signal (SIGTERM by default) to pid via POSIX kill(). The signal may be a name ('SIGTERM', 'SIGINT', …) or a number; an unknown name throws ERR_UNKNOWN_SIGNAL. A failure throws Node's 'kill <code>' Error with code, errno and syscall; signal 0 is the standard existence check and delivers nothing. On Windows SIGTERM/SIGKILL/SIGINT/SIGQUIT terminate the target unconditionally (exit code 1), as in Node, and any other signal throws ENOSYS.

true — true, when the signal was sent.

process.stdout and process.stderr are Node's streams, made on first use by what the descriptor is: a tty.WriteStream on a terminal, a net.Socket on a pipe or socket, a synchronous Writable on a file. write takes a string or a Buffer, an encoding and a callback, and appends nothing — unlike console.log/.error's trailing newline. Writes to a terminal, a file or a POSIX pipe are synchronous, as in Node, so output stays ordered with console.log; pipe() into them works.

void — Nothing.

process.stdout.write(chunk.toUpperCase())

The terminal's width and height, on a tty.WriteStream: read at creation and refreshed on SIGWINCH, which emits 'resize' when the size changed. Off a TTY (piped/redirected) the stream has no columns/rows: a real undefined, as in Node; ?? 80 is the idiomatic fallback.

number | undefined — Columns or rows, or undefined when the fd is not a terminal.

console.log(process.stdout.columns + "x" + process.stdout.rows)

A tty.ReadStream method that puts the terminal into raw mode (libuv's UV_TTY_MODE_RAW): canonical mode, echo and signal generation are off, so keystrokes arrive one at a time and Ctrl-C comes through as the byte 3; isRaw reports the mode, and the original mode is restored at exit. When fd 0 is not a terminal, process.stdin is a net.Socket without setRawMode, as in Node — guard on process.stdin.isTTY.

void — Nothing.

import { readKey } from 'klain:tty'
process.stdin.setRawMode(true)
const k = readKey()

Synchronous single-keystroke reads off fd 0, for a blocking raw-input loop. readByte() returns one byte (or -1 at EOF); readKey() returns one read()'s whole burst as a string, so an escape sequence like an arrow key (ESC [ A) is a single key. A bespoke klain: primitive because Node has no synchronous single-key read — it uses process.stdin.on('data') events.

number | string — The byte (-1 at EOF) or the keystroke string.

import { readKey } from 'klain:tty'
const k = readKey()

Sets an environment variable to String(value) through setenv, compound assignment included (process.env.X += …); a Symbol throws TypeError. A written variable is inherited by child processes, and delete process.env.KEY unsets it.

void — Nothing.

process.env.GREETING = "hi"

The bare process.env is the live environment block as a dynamic object — a copy of environ on POSIX, GetEnvironmentStringsW on Windows (the hidden =X: per-drive entries skipped, key case kept) — so every enumeration form works and every value is a string.

for (const [k, v] of Object.entries(process.env)) {
  if (k.startsWith("MYAPP_")) console.log(k, v)
}
const child = { ...process.env, NODE_ENV: "production" }

Any signal is an event name — SIGINT/SIGTERM to shut down gracefully, SIGWINCH (terminal resize) to re-read process.stdout.columns/.rows and repaint a TUI, SIGHUP, SIGUSR1/2, … The first listener starts a watcher and removing the last restores the default disposition; SIGKILL/SIGSTOP throw uv_signal_start EINVAL. On Windows, as in Node, SIGINT fires on Ctrl+C, SIGBREAK on Ctrl+Break, and a SIGTERM listener is accepted but never fires.

NodeJS.Process — process, for chaining.

process is an EventEmitter: on/once/off/emit/listenerCount and the rest, any event name. 'exit' fires at normal end and from process.exit(), receiving the exit code, and a listener may set process.exitCode; process.exit() with no argument uses it. 'uncaughtException' receives the thrown value and its origin. A rejected promise nothing handles is reported after the microtask checkpoint, as Node's default does: 'unhandledRejection' receives (reason, promise), else it is an uncaught exception.

void — Registers a lifecycle listener.

process.on('exit', (code: number) => console.log("exiting with code", code))
process.exitCode = 0

CLOCK_MONOTONIC high-resolution timing. hrtime() returns a [seconds, nanoseconds] tuple; hrtime(prev) returns the elapsed diff from a prior reading (with Node's borrow), and rejects a non-array or wrong-length argument as Node does; .bigint() returns total-nanoseconds as a bigint.

[number, number] | bigint — The timestamp or elapsed diff.

const start = process.hrtime()
// ...work...
const [s, ns] = process.hrtime(start)

Direct POSIX credential reads returning a number, matching Node-on-POSIX. Node leaves all four undefined on Windows: there the bare call is rejected at compile time in typed code and throws Node's TypeError when reached in untyped JS, and the portable optional call process.getuid?.() evaluates to undefined — it is typed number | undefined on every host.

number — The uid/gid.

Returns Node's object shape. rss is the process's instantaneous resident set size (Darwin task_info, Linux /proc/self/statm), matching Node's live rss. heapTotal/heapUsed report this compiler's own object heap — Boehm's collected heap under -mm=gc, otherwise the C allocator's arena (Darwin malloc_zone_statistics, glibc mallinfo2) — so they are real and grow with allocation, a native reinterpretation rather than V8's number. external/arrayBuffers have no native off-heap analogue and stay 0.

object — Memory-usage byte counts; rss and heapTotal/heapUsed are populated, external/arrayBuffers are 0.

const m = process.memoryUsage(); console.log(m.rss > 0)

Enqueues fn on the existing microtask queue.

void — Nothing.

process.nextTick(() => console.log("ran after synchronous code"))

process.version = "v22.11.0"; process.versions is a real object (JSON.stringify/field access/Object.keys all work), matching Node v22.11.0's node/v8 verbatim, plus a klain key for this compiler's version — stamped at link time from the release tag (the same value `klainmain --version` prints).

string | object — Version string / versions object.

console.log(process.version, process.versions.klain)

Seconds (a double) since process start, captured once at main entry via CLOCK_MONOTONIC.

number — Seconds since start.

The process's file-mode creation mask. With no argument it reads the mask the way libuv does (set 0, restore); with one (a number, or an octal string such as '022') it sets it and returns the previous value. POSIX umask(2), so a file created afterwards carries the mask; on Windows it is the CRT's _umask — 0 by default and inert for created files, exactly Node's own answer there.

number — The current (or previous) mask, e.g. 0o022.

const prev = process.umask(0o077)
fs.writeFileSync('secret', '…') // mode 600 on POSIX
process.umask(prev)

Node's stdin stream: a tty.ReadStream on a terminal, otherwise a net.Socket over the descriptor (a pipe, a socket or a file). It starts paused; a 'data' listener, resume(), pipe() or for await starts it, and pause() stops reading so the process can exit. 'data' delivers Buffers unless setEncoding is called; read()/'readable' and several listeners per event work as on any Readable.

typeof process.stdin — The stream, for chaining.

process.stdin.setEncoding("utf8")
  .on("data", (chunk: string) => process.stdout.write(chunk.toUpperCase()))
  .on("end", () => console.error("done"))

Node's readline over any Readable — stdin, a file stream, a child's stdout, a socket: 'line' per line (\r\n, \n, \r and the Unicode separators end one), 'close' at the end, question() with an AbortSignal, prompt/setPrompt, pause/resume, and for await (const line of rl). On a terminal it edits the line as Node does: cursor and word movement, kill ring, undo, history and tab completion. readline/promises' question returns a promise.

Interface — The readline interface.

fork()+execvp() with three pipes; the read ends are non-blocking and fold into the same select() event loop as Worker/channel pipes. spawn streams (child.stdout/stderr 'data'/'end', child.on('close'/'exit'/'error'), child.stdin.write/.end, child.pid, child.kill); exec runs via /bin/sh -c and execFile execvp's directly, both buffering into one (err, stdout, stderr) callback.

ChildProcess — The child handle.

Node's own mechanism: socketpair + re-exec of the current binary with NODE_CHANNEL_FD set; json serialization, newline-framed. Parent: child.send(msg, cb?), child.on('message'/'exit'/'close'), child.disconnect(); child: process.send(msg, cb?), process.on('message'/'disconnect'), process.disconnect(), process.connected. child.send(msg, server | socket) passes a net.Server or net.Socket to the other process, which gets its own. process.send is undefined in a program that was not forked.

ChildProcess — The forked child with an IPC channel.

A native blocking spawn on its own libuv loop, as Node's spawn_sync is (uv_spawn): the piped stdio read to completion (no deadlock when a child fills stderr while stdout drains), an optional input fed to stdin, a timeout/maxBuffer kill, then the exit; execSync runs via /bin/sh -c (%ComSpec% /d /s /c on Windows). Node's full options set: cwd, env (replaces the child's), input (string or Uint8Array), argv0, stdio ('pipe'/'inherit'/'ignore', string or 3-element array), timeout + killSignal (error.code ETIMEDOUT), maxBuffer (1 MiB default, ENOBUFS on overrun), shell (true or a shell path; args join the command with spaces), windowsHide, windowsVerbatimArguments. spawnSync returns Node's record in Node's key order — status is null on a signal death or a never-started child, output is [null, stdout, stderr], error carries code/errno/syscall 'spawnSync <file>'/path for a failed spawn (ENOENT: status null, pid 0, null streams). execSync/execFileSync return stdout — a Buffer, or a string with encoding: 'utf8' — or throw: the spawn/timeout/maxBuffer error itself, or 'Command failed: <cmd>' plus the captured stderr, the Error carrying the ExecException own properties status, signal, output, pid, stdout, stderr (readable through catch (e: any)); without an explicit stdio the child's stderr is mirrored to ours, as in Node.

SpawnSyncResult | string — The result object / captured stdout.

const r = spawnSync("echo", ["kalimera", "kosme"])
console.log(r.status, r.stdout.trim())