Skip to main content
Ant’s runtime behavior is controlled through three mechanisms: the ANT_DEBUG environment variable for low-level debug output, CLI flags for process-level options, and process.env for application configuration. You don’t need a config file to get started — all options are available at the shell level and work consistently across platforms.

​
ANT_DEBUG environment variable

Ant reads the ANT_DEBUG environment variable at startup. Use it to enable internal debug output for the parser, compiler, VM, or garbage collector. Multiple flags can be combined in a single string, separated by spaces. Each flag uses the form key:value: 
ANT_DEBUG="key:value"
ANT_DEBUG="key1:value1 key2:value2"

​
Available flags

FlagValuesEffect
gcdisableDisables garbage collection — useful for isolating GC-related issues
dump/parsetraceEnables parse trace output
dump/compiletraceEnables compile trace output
dump/crprintfbytecode, hex, allEnables crprintf debug output
dump/vmbytecode, jit, op-warn, allEnables VM debug output
For dump/crprintf and dump/vm, you can combine multiple values using a comma: 
ANT_DEBUG="dump/vm:bytecode,jit" ant script.js

​
Examples

ANT_DEBUG="dump/vm:bytecode" ant script.js
Setting gc:disable will cause Ant to consume memory without releasing it. Only use it for short-lived diagnostic runs, never in production.

​
CLI flags

These flags are handled directly by the Ant process before any JavaScript runs. Pass them before the script filename.
FlagDescription
--verboseEnable verbose output from the package manager and CLI commands
--no-colorDisable colored terminal output
--stack-size=<kb>Override the default JavaScript stack size in kilobytes
--localstorage-file <path>Path to a file for persisting localStorage data across runs
-e, --eval <script>Evaluate a JavaScript string directly
-p, --printEvaluate a script and print the result
-w, --watchRestart the process when the entry file changes
--no-clear-screenKeep output when restarting in watch mode (requires --watch)
-v, --versionPrint version information and exit
-h, --helpPrint help and exit
# Run with a custom stack size
ant --stack-size=4096 src/index.ts

# Run in watch mode without clearing the terminal
ant --watch --no-clear-screen src/index.ts

# Persist localStorage to a file
ant --localstorage-file ./data/storage.json src/index.ts

# Evaluate a one-liner
ant -e "console.log(Ant.version)"
For full documentation on running scripts and watch mode, see the CLI reference.

​
process.env

Ant inherits all environment variables from the parent process. Access them via process.env exactly as you would in Node.js: 
const port = parseInt(process.env.PORT || '3000');
const dbUrl = process.env.DATABASE_URL;

if (!dbUrl) {
  throw new Error('DATABASE_URL is required');
}
You can also set variables inline when running a script: 
PORT=8080 DATABASE_URL=postgres://localhost/mydb ant src/server.ts

​
Package.json scripts

Define scripts in package.json and run them with ant run <name>. This works the same way as npm run or bun run. 
{
  "scripts": {
    "start": "ant src/index.ts",
    "dev": "ant --watch src/index.ts",
    "build": "ant build.ts"
  }
}

ant run start
ant run dev
ant run build
You can also invoke a script by name directly if there’s no filename conflict — ant dev works if dev is defined in scripts and there’s no file named dev.js in the current directory.

​
LocalStorage persistence

By default, localStorage and sessionStorage are in-memory and reset between runs. To persist localStorage across invocations, pass a file path with --localstorage-file: 
ant --localstorage-file ./storage.json src/index.ts
Ant reads the file on startup and writes to it on exit. The file is created automatically if it doesn’t exist. sessionStorage is always in-memory regardless of this flag.