---
title: CLI Reference
url: "https://scriptc.dev/docs/cli"
docs_index: /llms.txt
lastUpdated: 2026-10-02
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

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

```console
$ 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…] verify and load precompiled runtime families
                                            for the current compiler/SDK/target
```

## scriptc build

Compiles a TypeScript (or JavaScript) entry file to serialized typed IR, textual LLVM IR, native assembly, a relocatable object, a native executable, or a WebAssembly module when the <code>wasm32-wasi</code> 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.

```console
$ 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:

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

The IR and LLVM source outputs require only Node. On supported macOS, Linux, and Windows hosts, 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 <code>scr\_\*</code> runtime symbols and a required <code>scr\_runtime\_abi\_v6</code> marker, not a standalone library. External consumption is experimental and requires the exact runtime version reported by <code>--print=native-link-info</code>. That option still writes the object, performs no link, and prints a versioned JSON recipe with the target, <code>main</code> entry, installed precompiled runtime pack, FFI inputs, and system libraries. It never reports private scriptc cache paths. See <a href="/native-objects">Native Program Objects</a> for complete C-driver and direct-linker examples. <code>--emit=exe</code> is the default. LLVM builds emit the program object through the helper and link precompiled runtime objects; runtime development with AddressSanitizer compiles an instrumented C runtime.

## scriptc run

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

```console
$ 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](/docs/coverage).

## scriptc cache warm

Verifies and reads the installed precompiled runtime objects and vendor archives. Pass one or more of `runtime`, `tls`, and `dynamic` to select those families. Ordinary builds need no runtime compilation or installation-time warming. With `--sanitize`, this command builds instrumented runtime objects using the development C toolchain.

## Options

<dl>
  <dt>
    <code>-o, --out \<path></code>
  </dt>

  <dd>
    Primary artifact path. An explicit path is exact. Defaults are

    <code>.scriptc/\<name>.ir.json</code>

    ,

    <code>.ll</code>

    ,

    <code>.s</code>

    ,

    <code>.o</code>

    , or the platform executable name.
  </dd>

  <dt>
    <code>--emit \<ir|llvm|asm|obj|exe></code>
  </dt>

  <dd>
    Select the invocation's one primary artifact.

    <code>ir</code>

    and

    <code>llvm</code>

    need only Node.

    <code>asm</code>

    and

    <code>obj</code>

    use a matching bundled LLVM helper on supported macOS, Linux, and Windows hosts and for WASI; they need no installed C compiler.

    <code>exe</code>

    is the default.
  </dd>

  <dt>
    <code>--print \<native-link-info></code>
  </dt>

  <dd>
    Build an object (equivalent to

    <code>--emit=obj</code>

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

  <dt>
    <code>--dynamic</code>
  </dt>

  <dd>
    Embed the JavaScript engine to run npm dependencies and supported

    <code>any</code>

    -typed code. Static compilation is the default; without this flag, dynamic-tier sites produce compilation errors. See

    <a href="/dependencies">npm Dependencies</a>

    .
  </dd>

  <dt>
    <code>--ffi \<file></code>
  </dt>

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

    <a href="/ffi">Native FFI</a>

    .
  </dd>

  <dt>
    <code>--backend \<llvm></code>
  </dt>

  <dd>
    The production code generator is

    <code>llvm</code>

    . This is also the default when the option is omitted.
  </dd>

  <dt>
    <code>--strip</code>
  </dt>

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

  <dt>
    <code>--optimization \<release|dev></code>
  </dt>

  <dd>
    Select native optimization for executable, assembly, or object output. The default is

    <code>release</code>

    (

    <code>-O2</code>

    ).

    <code>dev</code>

    uses

    <code>-O0</code>

    and emits source locations for TypeScript and JavaScript breakpoints and stack frames. LLVM builds include source variable names and native storage descriptions; see

    <a href="/limitations#native-debugging">Native debugging</a>

    for the supported representations. macOS executable builds also produce an adjacent

    <code>.dSYM</code>

    bundle.
  </dd>

  <dt>
    <code>--windows-subsystem \<console|gui></code>
  </dt>

  <dd>
    Select the subsystem of a Windows executable.

    <code>console</code>

    is the default;

    <code>gui</code>

    prevents Windows from opening a console window for the app. Valid only for executable builds targeting Windows.
  </dd>

  <dt>
    <code>--npm-static \<pkg\[,pkg…]|auto></code>
  </dt>

  <dd>
    EXPERIMENTAL. Compile the named npm packages' shipped JS statically as program modules instead of embedding them for the engine (repeatable;

    <code>auto</code>

    opts in every eligible direct import). A package the preflight refuses falls back to the island with a coverage-report note. See

    <a href="/dependencies">npm Dependencies</a>

    for maturity notes.
  </dd>

  <dt>
    <code>--provenance-sources</code>
  </dt>

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

  <dt>
    <code>--external-types \<specifier=file.d.ts></code>
  </dt>

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

    <code>SC1010</code>

    blockers. Relative paths resolve from the current working directory. Accepted files end in

    <code>.d.ts</code>

    ,

    <code>.d.mts</code>

    , or

    <code>.d.cts</code>

    .
  </dd>

  <dt>
    <code>--sanitize</code>
  </dt>

  <dd>
    Build an executable with AddressSanitizer plus the runtime reference-count audit — the same lane the compiler's own test corpus runs under.

    <code>--emit=asm|obj</code>

    rejects this option until the helper's sanitizer pipeline has parity.
  </dd>

  <dt>
    <code>--emit-ir</code>
  </dt>

  <dd>
    Additive IR side artifact. It is deprecated for executable builds for one release cycle; prefer

    <code>--emit=ir</code>

    when IR is the primary output. Library mode retains

    <code>--emit-ir</code>

    because

    <code>--emit</code>

    does not select library artifacts.
  </dd>

  <dt>
    <code>--keep-llvm</code>

    /

    <code>--no-keep-llvm</code>
  </dt>

  <dd>
    Keep (default) or delete the generated

    <code>.ll</code>

    file next to the executable.
  </dd>

  <dt>
    <code>-h, --help</code>
  </dt>

  <dd>
    Show usage.
  </dd>
</dl>

## Environment variables

<dl>
  <dt>
    <code>SCRIPTC\_CACHE\_DIR</code>
  </dt>

  <dd>
    Override the persistent build-cache root. By default it is

    <code>$XDG\_CACHE\_HOME/scriptc/build</code>

    when set,

    <code>$HOME/Library/Caches/scriptc/build</code>

    on macOS,

    <code>%LOCALAPPDATA%\scriptc\cache\build</code>

    on Windows, and

    <code>$HOME/.cache/scriptc/build</code>

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

  <dt>
    <code>SCRIPTC\_NO\_CACHE</code>
  </dt>

  <dd>
    Set to

    <code>1</code>

    to bypass all build-cache reads and writes. An explicitly empty

    <code>SCRIPTC\_CACHE\_DIR</code>

    has the same effect.
  </dd>

  <dt>
    <code>SCRIPTC\_CACHE\_MAX\_MB</code>
  </dt>

  <dd>
    Maximum build-cache size in megabytes. The default is

    <code>4096</code>

    ; 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.
  </dd>

  <dt>
    <code>SCRIPTC\_CC</code>
  </dt>

  <dd>
    The external compiler for runtime development with AddressSanitizer and native FFI build tooling.

    <code>zigcc</code>

    selects Zig's

    <code>cc</code>

    subcommand.
  </dd>

  <dt>
    <code>SCRIPTC\_LINKER</code>
  </dt>

  <dd>
    Platform linker driver for ordinary LLVM executables. The driver receives only the helper-produced program object, precompiled runtime objects/archives, FFI inputs, and system libraries; it locates the platform SDK and CRT inputs but does not compile scriptc-generated or runtime C.
  </dd>

  <dt>
    <code>SCRIPTC\_TARGET</code>
  </dt>

  <dd>
    Target triple for cross-compilation, e.g.

    <code>aarch64-linux-gnu.2.36</code>

    ,

    <code>x86\_64-windows-gnu</code>

    , or

    <code>wasm32-wasi</code>

    . WASI builds default to a

    <code>.wasm</code>

    output name. See

    <a href="/platforms">Platform Support</a>

    .
  </dd>
</dl>

```console
$ 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 emits LLVM IR and lowers it to native code. Executable builds link the resulting object with the matching precompiled C runtime pack. Use <code>--emit=llvm</code> to inspect generated code.

For source breakpoints in Xcode or LLDB, build with <code>--optimization=dev</code>. In an Xcode custom build rule, list the executable and its <code>.dSYM</code> 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

<table>
  <thead>
    <tr>
      <th>
        Operation
      </th>

      <th>
        Node
      </th>

      <th>
        Compiler
      </th>

      <th>
        Linker / SDK
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>coverage</code>

        ,

        <code>--emit=ir|llvm</code>
      </td>

      <td>
        Required
      </td>

      <td>
        Not used
      </td>

      <td>
        Not used
      </td>
    </tr>

    <tr>
      <td>
        <code>--emit=asm|obj</code>

        (macOS 15+ arm64)
      </td>

      <td>
        Required
      </td>

      <td>
        Bundled scriptc LLVM helper
      </td>

      <td>
        Not used
      </td>
    </tr>

    <tr>
      <td>
        External link of

        <code>--emit=obj</code>

        with the reported precompiled runtime pack
      </td>

      <td>
        Not used by the artifact
      </td>

      <td>
        Precompiled runtime objects
      </td>

      <td>
        macOS linker and SDK required
      </td>
    </tr>

    <tr>
      <td>
        <code>--emit=exe</code>
      </td>

      <td>
        Required to run scriptc
      </td>

      <td>
        Bundled LLVM helper
      </td>

      <td>
        Platform linker and SDK/sysroot
      </td>
    </tr>
  </tbody>
</table>

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)