CLI Reference

The scriptc command has four subcommands: build, run, coverage, and cache warm. scriptc --help prints this summary and the options below, and scriptc --version prints the installed version.

$ 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> --external-types <specifier=file.d.ts>
                                            type-resolve an embedder-provided module for analysis
  scriptc build --lib --profile <p.json>    library mode: compile the profile's entry
                                            module to a linkable static archive
                                            (<name>.lib.a), or a Wasm reactor
                                            (<name>.wasm) on wasm32-wasi,
                                            exporting the profile symbols; a profile
                                            with a sidecar section also gets the
                                            contract sidecar JSON beside the archive
  scriptc cache warm [runtime|tls…] verify and load precompiled runtime families
                                            for the current compiler/SDK/target

scriptc build

Compiles a TypeScript or JavaScript entry file. By default it writes a native executable, or a WebAssembly module when the target is wasm32-wasi. The program is type-checked first by the TypeScript compiler, honoring the nearest tsconfig.json. Anything that can't compile is an error with an SC-prefixed code, a code frame, and usually a rewrite hint.

$ scriptc build fib.ts -o fib >/dev/null
$ ./fib
832040

build prints the path of the file it writes. Without -o, the file goes in .scriptc/ next to the input. Use --emit to stop at an earlier stage of compilation:

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

Different output kinds accumulate in .scriptc/; rebuilding a kind updates its file.

--emit=exe is the default. Assembly and object output use the LLVM helper installed with scriptc and need no external compiler, linker, or SDK. An object is a relocatable program object that leaves scriptc's runtime functions undefined; it is not a standalone library. Linking objects yourself is experimental and requires the exact runtime pack reported by --print=native-link-info; see Native Program Objects.

Library mode

scriptc build --lib --profile <profile.json> compiles the entry module named in a library profile into a static archive (<name>.lib.a) that a host application links, or into a Wasm reactor (<name>.wasm) on wasm32-wasi. The profile declares the exported functions and their symbols. Library builds take no input file and don't accept --emit, --print, --optimization, --strip, --ffi, or --npm-static; the profile controls emission and optimization. See WebAssembly Modules for a complete profile and iOS and Android for mobile targets.

scriptc run

Builds the program, then runs it with stdio inherited. For wasm32-wasi, it runs the module with Node.js's WASI Preview 1 implementation, makes the current working directory available as /, and maps the host's temporary directory to /tmp.

$ scriptc run fib.ts
832040

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

scriptc coverage

Analyzes the program without building it and reports what compiles and what blocks the rest. See Coverage Reports.

scriptc cache warm

Verifies and loads the installed precompiled runtime objects and vendored libraries, and prints the cache directory. Pass runtime, tls, or both to select which to warm. Ordinary builds don't need this step. With --sanitize, it builds the instrumented runtime objects using a C toolchain.

Options

-o, --out <path>

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

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

Select the primary artifact: serialized typed IR (ir), textual LLVM IR (llvm), assembly (asm), a relocatable object (obj), or an executable (exe, the default). Every kind except exe is produced without an external compiler, linker, or SDK.

--print <native-link-info|diagnostics>

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 precompiled runtime pack and all link inputs, but does not invoke a linker. diagnostics: for build and coverage, print the versioned JSON diagnostics document described in Coverage Reports instead of the human output.

--fail-on <blockers|divergences>

Coverage only. Exit with status 1 when the entry has blockers that would fail a build, or with divergences, also when it has Node divergence warnings. See Gating builds and CI.

--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 <llvm>

The code generator. llvm is the only backend and the default.

--strip

Remove symbol and debug payload when linking an executable, including cross-compiled targets. This flag preserves code optimization.

--optimization <release|dev|speed>

Select native optimization for executable, assembly, or object output. The default is release (-O2), which emits string retains and the retains and releases of dynamic values inline and lets LLVM inline small runtime functions that keep no internal runtime state into executable code; programs large enough to be compiled in parallel partitions skip that inlining to keep build time and size in check. dev uses -O0 and emits source locations for TypeScript and JavaScript breakpoints and stack frames. LLVM builds include source variable names and native storage descriptions; see Native debugging for the supported representations. macOS executable builds also produce an adjacent .dSYM bundle. speed is -O2 plus optimizations that trade binary size and build time for run-time speed: it lets LLVM inline more small runtime functions into program code, emits the remaining reference counting inline, and on x86-64 starts every runtime function on a cache-line boundary. Expect larger executables and longer cold builds than release; how much faster a program runs depends on how much of its time is spent in the runtime. Runtime inlining needs a runtime pack built with the LLVM helper; where a runtime pack lacks it, programs link the same runtime without it and speed links the release runtime and keeps inline reference counting. Selecting speed never changes what release builds produce, and the two never share cached artifacts. Library profiles accept "optimization": "speed" for inline reference counting.

--windows-subsystem <console|gui>

Select the subsystem of a Windows executable. console is the default; gui prevents Windows from opening a console window for the app. Valid only for executable builds targeting Windows.

--detached-exit

On Linux, when the program calls process.exit(), hand the release of its memory to a helper process so the parent sees the exit sooner. The kernel otherwise frees the whole address space before the exit is reported, which takes tens of milliseconds per gigabyte. Opt in only where the trade-offs are acceptable: for up to about 100 ms after the exit, the helper keeps the executable mapped (overwriting the binary in place fails with "text file busy"), its memory stays charged to the cgroup, and the teardown CPU time no longer appears in the parent's resource usage. Valid only for executable builds; it has no effect on other platforms.

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

Name npm packages to compile even if they don't ship their own type declarations (repeatable). auto uses the default automatic selection. Packages that can't compile produce diagnostics. See npm Dependencies.

--provenance-sources

Experimental. Compile npm dependencies from the source at the commit their provenance attestation names. Packages without a usable attestation compile from their installed files.

--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 and a reference-count audit at exit, the same checks scriptc's own test suite uses. Requires a C compiler and is available only for host builds. Not supported with --emit=asm or --emit=obj.

--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-llvm / --no-keep-llvm

Keep (default) or delete the generated .ll file next to the executable.

--lib, --profile <profile.json>

Build in library mode from the given profile. --lib requires --profile and works only with build.

-h, --help

Show usage.

-v, --version

Print the installed version.

Environment variables

SCRIPTC_CACHE_DIR

Override the persistent build-cache root. By default it is $XDG_CACHE_HOME/scriptc/build when set, $HOME/Library/Caches/scriptc/build on macOS, %LOCALAPPDATA%\scriptc\cache\build on Windows, and $HOME/.cache/scriptc/build elsewhere. Cached frontend results and LLVM artifacts are verified against their source, helper, target, and compilation settings. Native outputs also depend on the selected runtime pack and linker inputs. FFI objects, archives, and system libraries relink against their current dependencies. Sanitizer development builds additionally cache instrumented runtime objects and verify external compiler and header inputs. 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 used for --sanitize builds. zigcc selects zig's cc subcommand.

SCRIPTC_LINKER

The linker driver for executable builds, in place of the default (clang on macOS and glibc Linux, zig elsewhere). It receives only object files, archives, and system libraries, and locates the platform SDK and C runtime itself.

SCRIPTC_TARGET

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

SCRIPTC_RUNTIME_PACK

A runtime pack directory to use instead of an installed @scriptc/runtime-<target> package.

$ 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

LLVM backend

scriptc generates LLVM IR and compiles it to native code. Executable builds link the result with the matching precompiled runtime pack. Use --emit=llvm to inspect the generated code.

For source breakpoints in Xcode or LLDB, build with --optimization=dev. In an Xcode custom build rule, list the executable and its .dSYM bundle as outputs. Keep the bundle next to the executable and retain the original source files at their build paths. LLVM preserves source locations across imported modules.

Tool requirements