CLI reference

This page is generated from viscosity --help, so it always matches the code.

viscosity: rewrites arrays of objects (JavaScript, TypeScript, Python) into struct-of-arrays layouts
when it can prove it is safe and expects it to be faster.

Usage:
  viscosity build <file> [-o out.js] [options]   compile a file
  viscosity build <file>... -o <dir> [options]   compile several files into dir/
  viscosity explain <file>... [options]          show every decision and why
  viscosity profile <file> [-o profile.json]     run the program and record collection sizes
  viscosity --help | --version

Options:
  -o, --out <path>          build: the output file, or a directory (several
                            files, or a path ending in /) that gets one file
                            per input, named after it
  --frames                  explain: under each refusal, show the source line
                            with carets under the code it is about
  --jobs <n>                compile up to n files at once (default: one per
                            CPU in the Rust CLI; this CLI compiles one at a
                            time)
  --mode auto|opt-in        auto (default) decides everything; opt-in only
                            transforms collections marked // @viscosity soa
  --bounds check|assume     check (default) keeps out-of-bounds behaviour
                            identical; assume trusts the program
  --min-size <n>            leave collections smaller than n alone (default 64)
  --profile <profile.json>  use measured sizes from `viscosity profile`
  --parser acorn|mini       JavaScript parser (default acorn)
  --explain                 also print the explanation when building
  --python-auto             Python: transform without annotations (CPython
                            column access is slower; the gain is memory)

This is the TypeScript CLI’s help. The Rust CLI (engine/rust) takes the same commands and options, except --parser (it has one JavaScript parser, oxc), and it does not read TypeScript files. Errors and their messages are described in Errors and validation.

Examples

viscosity explain src/particles.js
viscosity explain --frames src/particles.js
viscosity build src/particles.js -o dist/particles.js --explain
viscosity build src/*.js -o dist/
viscosity profile src/particles.js -o profile.json
viscosity build src/particles.js --profile profile.json -o dist/particles.js