CLI Reference

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

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

Usage:
  scriptc build <file.ts|.js> [options]     compile to a native executable
  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 build

Compiles a TypeScript (or JavaScript) entry file to a native executable. 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 executable lands in .scriptc/<name> next to the input, and the generated C translation unit is kept beside it (see --keep-c):

$ scriptc build fib.ts --emit-ir
$ ls .scriptc/
fib
fib.c
fib.ir.json

scriptc run

build followed by executing the binary, with stdio inherited.

$ 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.

Options

-o, --out <path>

Output executable path. Default: .scriptc/<name> next to the input file.

--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 — emits LLVM IR text, compiled by the same clang) or c (the readable reference backend). Unset, the build tries LLVM and falls back to the C backend when the program is outside the LLVM tier — a one-line stderr note says so, and program behavior is identical either way. An explicit --backend llvm fails with a diagnostic instead of falling back (the debugging/CI pin); --backend c pins the reference backend.

--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).

--sanitize

Build with AddressSanitizer plus the runtime reference-count audit — the same lane the compiler's own test corpus runs under. Useful when a program misbehaves and you want leaks or memory errors to be loud.

--emit-ir

Also write the typed IR as JSON (<name>.ir.json) next to the executable.

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

-h, --help

Show usage.

Environment variables

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 or x86_64-windows-gnu. 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, compiled by the same clang that links the runtime. It covers most of the supported surface; a program outside that tier is never miscompiled — the build falls back to the C backend transparently and says so in one stderr line:

$ scriptc build cli-tool.ts --dynamic -o cli-tool
scriptc: backend c (llvm refused: npmEmbedding)

The C backend is the reference, forever: deliberately readable, source-line-annotated output, and byte-identical program behavior wherever the two backends overlap — every release verifies that. Pin it when you want to read 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.