CLI Reference

The CLI has four commands. scriptc --help prints this same surface.

$ scriptc --help
scriptc  TypeScript/JavaScript to native and WebAssembly executables (experimental)

Usage:
  scriptc build <file.ts|.js> [options]     compile to an executable or source artifact
  scriptc run <file.ts|.js> [options]       compile and run
  scriptc coverage <file.ts|.js>            how much compiles statically, and why not
  scriptc coverage <file.ts|.js> --dynamic  what a --dynamic build compiles, and what still blocks it
  scriptc coverage <file.ts|.js> --external-types <specifier=file.d.ts>
                                            type-resolve an embedder-provided module for analysis
  scriptc cache warm [runtime|tls|dynamic] prebuild expensive native cache families
                                            for the current compiler/SDK/target

scriptc build

Compiles a TypeScript (or JavaScript) entry file to serialized typed IR, readable C, textual LLVM IR, native assembly, a relocatable object, a native executable, or a WebAssembly module when the wasm32-wasi target is selected. The program is type-checked first by the real TypeScript compiler, honoring the nearest tsconfig.json and any construct without a lowering is a compile error with an SC-prefixed code, a code frame, and usually a rewrite hint.

$ scriptc build fib.ts -o fib
$ ./fib
832040

Without -o, the primary artifact lands in .scriptc/ next to the input. Source outputs have stable suffixes and stop before native compilation:

$ scriptc build fib.ts --emit=ir >/dev/null
$ ls .scriptc/
fib.ir.json
$ scriptc build fib.ts --emit=c >/dev/null
$ ls .scriptc/
fib.c
$ scriptc build fib.ts --emit=llvm >/dev/null
$ ls .scriptc/
fib.ll
$ scriptc build fib.ts --emit=asm >/dev/null
$ ls .scriptc/
fib.s
$ scriptc build fib.ts --emit=obj >/dev/null
$ ls .scriptc/
fib.o

The three source outputs require only Node. On macOS 15+ arm64, assembly and object outputs use the matching native helper installed with scriptc and do not invoke an external compiler, archiver, linker, or SDK. The object is a relocatable program object with undefined scr_* runtime symbols and a required scr_runtime_abi_v1 marker, not a standalone library. External consumption is experimental and requires the exact runtime version reported by --print=native-link-info. That option still writes the object, performs no link, and prints a versioned JSON recipe with the target, main entry, installed source runtime pack, FFI inputs, and system libraries. It never reports private scriptc cache paths. See Native Program Objects for complete C-driver and direct-linker examples. --emit=exe is the default. On macOS 15+ arm64, LLVM-tier builds emit the program object through the helper and link release-built runtime objects; explicit C, LLVM fallback, and sanitizer builds retain runtime C compilation.

scriptc run

build followed by executing the binary, with stdio inherited. For wasm32-wasi, the CLI starts the module through Node's WASI Preview 1 host, preopens the current working directory as /, and exposes the host's /tmp as the guest's /tmp.

$ scriptc run fib.ts
832040

Note: run does not forward extra command-line arguments to the program. To pass arguments, build the executable and invoke it directly.

scriptc coverage

Analyzes the program without producing a binary and reports, statement by statement, what compiles statically, what needs the embedded dynamic engine, and what blocks the rest. With --dynamic it answers a different question: what would a --dynamic build compile, and what still blocks it. Both forms are covered in depth in Coverage Reports.

scriptc cache warm

Prebuilds release runtime objects and native TLS/dynamic-engine archives for targets that still compile runtime C locally. macOS 15+ arm64 installations already carry the release-built runtime pack and skip automatic warming; older macOS hosts retain warming for the source-toolchain path. Use this command when preparing another supported target's container image or CI runner. Pass one or more of runtime, tls, and dynamic to seed only those families.

Options

-o, --out <path>

Primary artifact path. An explicit path is exact. Defaults are .scriptc/<name>.ir.json, .c, .ll, .s, .o, or the platform executable name.

--emit <ir|c|llvm|asm|obj|exe>

Select the invocation's one primary artifact. ir, c, and llvm need only Node. asm and obj use the bundled LLVM helper on macOS 15+ arm64 and emit artifacts targeting macOS 14.0. exe is the default.

--print <native-link-info>

Build an object (equivalent to --emit=obj) and print its machine-readable external link recipe as JSON instead of printing the artifact path. The document names the exact installed source runtime pack and all link inputs, but does not invoke a linker.

--dynamic

Embed the dynamic engine (~620KB) so npm dependencies and any-typed code can run. Static stays the default without this flag, dynamic-tier sites are per-site compile errors. See npm Dependencies.

--ffi <file>

Bind signature-only TypeScript declarations to native C ABI symbols and link the manifest's archive, object, and system-library inputs. See Native FFI.

--backend <c|llvm>

Code generator: llvm (default) or c (the readable debugging backend). On macOS arm64, LLVM-tier executable code generation uses the bundled helper and precompiled runtime pack before the platform link. Unset, a native build can fall back to C when the program is outside the LLVM tier. The production wasm32-wasi target never falls back: a missing LLVM lowering is SC3001.

--npm-static <pkg[,pkg]|auto>

EXPERIMENTAL. Compile the named npm packages' shipped JS statically as program modules instead of embedding them for the engine (repeatable; auto opts in every eligible direct import). A package the preflight refuses falls back to the island with a coverage-report note. See npm Dependencies for maturity notes.

--provenance-sources

EXPERIMENTAL. Compile npm dependencies from their provenance-attested source, fetched at the attested commit, as static program modules; packages without a usable attestation keep the engine path (a note, never a failure).

--external-types <specifier=file.d.ts>

Coverage only. Map an exact bare module specifier to a local declaration file supplied by an embedder. Repeat the option for multiple modules. The declaration supplies checker types so application coverage can continue; runtime imports and values remain explicit SC1010 blockers. Relative paths resolve from the current working directory. Accepted files end in .d.ts, .d.mts, or .d.cts.

--sanitize

Build an executable with AddressSanitizer plus the runtime reference-count audit the same lane the compiler's own test corpus runs under. --emit=asm|obj rejects this option until the helper's sanitizer pipeline has parity.

--emit-ir

Additive IR side artifact. It is deprecated for executable builds for one release cycle; prefer --emit=ir when IR is the primary output. Library mode retains --emit-ir because --emit does not select library artifacts.

--keep-c / --no-keep-c

Keep (default) or delete the generated program translation unit next to the executable the .ll file under the default LLVM backend, or the .c under --backend c (and when the default build fell back). The generated C is readable and annotated with source lines.

--from-c

Treat the input as a C (or .ll) file. Toolchain plumbing and debugging. These arbitrary translation units bypass the persistent artifact cache because their header dependency graph is caller-owned.

-h, --help

Show usage.

Environment variables

SCRIPTC_CACHE_DIR

Override the persistent build-cache root. By default it is $XDG_CACHE_HOME/scriptc/build when that variable is set, $HOME/Library/Caches/scriptc/build on macOS, %LOCALAPPDATA%\scriptc\cache\build on Windows, and $HOME/.cache/scriptc/build on other platforms. The cache stores checksum-verified, content-addressed executables, library archives, and per-flavor runtime objects. Identities include the compiler's resolved system-header dependencies and linker/assembler identities. The compiler remains required so dependency selection is rediscovered on every cache-enabled invocation. FFI builds with archive/object inputs or ambient system_libraries always relink against their current dependencies while retaining runtime-object reuse. Mutable compiler input paths such as CPATH and SDKROOT, and compiler wrappers, bypass persistent artifacts and objects so dependencies rebuilt in place cannot go stale. Opaque archiver wrappers rebuild library program members and archives while retaining runtime-object reuse. Direct Clang, Apple's system Clang shim, zig cc, trusted platform archivers, and zig ar retain their applicable persistent tiers. An existing POSIX override must already be private; otherwise caching is bypassed without changing the directory's permissions.

SCRIPTC_NO_CACHE

Set to 1 to bypass all build-cache reads and writes. An explicitly empty SCRIPTC_CACHE_DIR has the same effect.

SCRIPTC_CACHE_MAX_MB

Maximum build-cache size in megabytes. The default is 4096; the default cache is swept periodically, while an explicitly configured cap is checked after every successful cache write. Least-recently-used entries are removed when the cache exceeds the cap.

SCRIPTC_CC

The C compiler to invoke. zigcc selects zig's bundled clang, which enables cross-compilation with its bundled sysroots.

SCRIPTC_TARGET

Target triple for cross-compilation, e.g. aarch64-linux-gnu.2.36, x86_64-windows-gnu, or wasm32-wasi. WASI builds default to a .wasm output name. See Platform Support.

$ SCRIPTC_CC=zigcc SCRIPTC_TARGET=aarch64-linux-gnu.2.36 scriptc build fib.ts -o fib-linux
$ file fib-linux
fib-linux: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 2.0.0, with debug_info, not stripped

Backends

The default backend emits textual LLVM IR. On macOS arm64 it is lowered to an object by the bundled helper and linked with the precompiled runtime pack; other executable targets retain their existing toolchain path. A program outside the LLVM tier is never miscompiledthe native build falls back to the C backend transparently and says so in one stderr line. The production wasm32-wasi target uses LLVM's 32-bit ABI path and never falls back; an LLVM coverage gap is a build diagnostic. Dynamic npm embedding is LLVM surface on every target.

The C backend is a debugging aid: deliberately readable, source-line-annotated output with differential tests against LLVM wherever the two overlap. Pin it when you want to inspect what your program became:

$ scriptc build fib.ts --backend c -o fib
$ ./fib
832040
$ head -1 fib.c
/* Generated by scriptc from fib.ts. Do not edit. */

An explicit --backend llvm pins the LLVM backend and fails with diagnostic SC3001, naming the unsupported construct, instead of falling back useful for CI lanes that must notice tier changes.

Tool requirements