CLI reference

The complete command-line surface of the cruft binary: every command and execution option, the capability and sandboxing flags, exit codes, all CRUFT_* environment variables, the Compartment constructor, and the cruft-caps.json grant file.

The cruft binary, complete. Concepts and rationale live in the concepts and subsystems tiers; this page is the surface itself. Where behavior is stated concretely, it describes the current cruft binary.

Commands

Runnable file extensions now include .tsx and .fts (CruftScript) alongside the JavaScript and TypeScript set:

Unlike node, run is a real verb (node run x tries to execute a file named run). File-type dispatch is by extension: .mjs/.mts are ES modules, .cjs/.cts CommonJS, .js/.ts follow the nearest package.json "type"; .ts/.mts/.cts pass through type erasure first. .tsx is dispatched but not yet type-stripped and has no JSX support — TypeScript type annotations and JSX elements in a .tsx file currently fail to parse.

Execution options

Option parsing stops at the first entry point; flags after it go to your program's process.argv, exactly like node.

Capability options

The sandboxing surface (full treatment: Compartments and capabilities):

Inline -e/-p source runs under the same capability mode as a file; there is no separate eval policy.

Unrecognized flags

The flag set is deliberately small, and anything else in flag position is rejected, not ignored (cruft: bad option: --x, exit 64). This includes node flags Cruft has not implemented: they fail loudly rather than silently running without the requested behavior. (--require/-r preload is implemented — see CRUFT_PRELOAD in the environment table.)

Exit codes

process.exit(N) propagates faithfully. For Cruft's own errors the current convention is sysexits.h, which differs from node, branch on these with care:

The convention difference is tracked and may converge toward node-faithful behavior; treat non-zero-ness, not specific codes, as the portable signal.

cruft install

No positional arguments, no flags, configuration is entirely by environment variable (below). Reads dependencies from ./package.json; writes node_modules and cruft-lock.json. Output format:

cruft install: project=<dir> registry=<url> mode=<mode>
+ name@version      # installed this run
= name@version      # already satisfied, skipped
cruft install: <n> installed, <m> skipped

There is no add/remove/init/update yet; edit package.json and re-run. Root devDependencies are not yet read, and lifecycle scripts are not run (both tracked, see the package manager documented limitations).

Environment variables

Runtime / GC

Package manager

Compartment API (runtime globals)

Not a CLI flag but part of the operable surface, the constructor options in one place:

Methods: evaluate(src) (compile + run in the realm, returns completion value; state persists across calls), send(payload) (worker-hosted only: structured-clone delivery; SharedArrayBuffer crosses by reference; functions rejected).

Capability grant file

Sealed modes read grants from a cruft-caps.json next to (or above) the entry file, allow-lists per family:

{ "fs": ["./"], "net": ["127.0.0.1:8080"], "env": ["HOME"], "exec": ["git"], "stdio": { "stdout": true, "stderr": true } }

The stdio family authorizes a sealed program to write to standard output and standard error, so a directly-run sealed script that prints can be granted the streams it needs. Note stdio takes object form ({ "stdout": true, "stderr": true }), not an array — the fs/net/env/exec families are arrays. fs entries match the as-written operation path (use "./" for relative access).