cli.md

Command-line guide

Build the runner from the repository root:

cargo build --release -p spite --locked

The examples below use a POSIX shell. On Windows, the executable is target\release\spite.exe.

Scripts

Pass source text with --eval, supply a file, or use - to read standard input:

./target/release/spite --eval '6 * 7'
./target/release/spite example.js
printf '6 * 7' | ./target/release/spite -

Each invocation creates a fresh realm and prints the script's completion value. Strings are quoted, with escapes that preserve lone surrogates. Input must be UTF-8. There is no console or process global.

Before printing the result, the runner drains queued Promise jobs. An idle pending Promise does not keep a script running.

Modules and imports

Use --module to parse the input as a module. It works with files, --eval, and standard input:

./target/release/spite --module main.js
./target/release/spite --module --eval 'export const answer = await Promise.resolve(42)'

Module mode waits for top-level await. Successful evaluation normally prints undefined; a rejected or idle, unsettled evaluation fails.

The file loader treats import specifiers as filesystem paths. Relative paths are resolved from the importing file's directory, or from the current directory for --eval and standard input. There is no package lookup or extension search. Static imports and dynamic import() share a cache keyed by canonical path and module type, including when modules form a cycle. Dynamic imports also work in scripts.

For example, with these files in the same directory:

// answer.js
export const answer = 42;

// main.js
import { answer } from "./answer.js";
if (answer !== 42) throw new Error("unexpected answer");

Run ./target/release/spite --module main.js to load and evaluate both modules.

JSON modules

Select JSON parsing with the type import attribute:

import settings from "./settings.json" with { type: "json" };
const { default: other } = await import("./other.json", {
  with: { type: "json" },
});

JSON modules expose a default export. The only supported attribute is type: "json"; other keys or values are rejected. With no attributes, the loader parses a JavaScript module regardless of the file's suffix.

Check syntax

Use --check to parse the supplied source and check early errors without executing it:

./target/release/spite --check example.js
./target/release/spite --module --check main.js

A successful check produces no output. Module checks do not load dependencies.

Options and resource limits

spite [--max-steps N] [--max-source-bytes N] [--module] [--check] (--eval SOURCE | FILE | -)

Place options before the input argument.

Option	Effect
--eval SOURCE	Use source text from an argument
--module	Parse and evaluate a module instead of a script
--check	Check syntax and early errors without evaluation
--max-steps N	Limit interpreter work for each evaluation or job
--max-source-bytes N	Limit the encoded size of each parsed source
--help, -h	Print usage

Resource quotas are disabled by default. To bound a script's execution:

./target/release/spite --max-steps 1000 --eval 'while (true) {}'

Work units count interpreter and built-in operations, rather than JavaScript statements or elapsed time. A work limit has no effect on a syntax-only check.

The source limit applies to the input, imported JavaScript and JSON files, and source generated by eval or the function constructors. File and standard-input readers stop after at most one byte beyond the limit. Sizes use UTF-8 encoding; an unpaired surrogate in generated source counts as three bytes.

Native stack and platform capacity checks remain active with no quotas selected. See native constraints.

Diagnostics and exit codes

Diagnostics go to standard error. Imported syntax errors reject dynamic imports with a SyntaxError. Filesystem errors, unsupported features, and host resource limits remain host failures. See embedding errors for the distinction between host failures and JavaScript exceptions.

Exit code	Meaning
0	Successful evaluation or syntax check
1	Input, parsing, loading, or evaluation failed
2	Invalid option arguments or input combination