Skip to main content
The ant binary is the single entry point for running scripts, starting the REPL, evaluating inline code, and managing packages. Every interaction starts here. This page covers all flags, execution modes, and the subcommands Ant exposes for package management.

​
Basic usage

ant [flags] <file> [-- script-args]
Pass a file to run it as a module. Flags come before the file. Arguments you want your script to receive go after --. 
# Run a file
ant script.js

# Pass arguments to the script
ant script.js -- arg1 arg2
Inside your script, process.argv contains ["ant", "script.js", "arg1", "arg2"]. Without --, anything after the file is interpreted by Ant itself rather than forwarded to your script.

​
Execution modes

Ant supports four distinct execution modes depending on how you invoke it.

​
Run a file

ant script.js
ant server.ts
Ant resolves the file, strips TypeScript types if needed, and executes it as an ES module. The event loop runs until there is no more pending work.

​
Inline eval

Use -e / --eval to run a short snippet without creating a file. 
ant -e "console.log(process.version)"
Combine with -p / --print to evaluate an expression and print the result to stdout: 
ant -p "1 + 2"
# 3

​
Stdin mode

Pipe a script through stdin and Ant will execute it. This is useful for scripting and one-liners. 
echo "console.log(42)" | ant
Ant detects that stdin is not a TTY and reads the full input before executing. You can use -p here too.

​
REPL

Run ant with no arguments to start the interactive REPL. See REPL for details.

​
Flags

​
-e, --eval <script>
flag
Evaluate the given script string directly. The script runs as if it were an inline file. Combine with --print to output the result.
​
-p, --print
flag
Evaluate the script and print the return value to stdout. Works with both --eval and stdin mode. Non-undefined values are pretty-printed; strings are printed as-is.
​
-w, --watch
flag
Restart the process automatically when the entry file changes on disk. Cannot be combined with --eval, stdin mode, or subcommands. See Watch mode.
​
--no-clear-screen
flag
When using --watch, keep previous output visible instead of clearing the terminal on each restart. Must be used together with --watch; using it alone is an error.
​
--localstorage-file <path>
flag
Set the file path used to persist localStorage data between runs. By default localStorage is in-memory only and lost when the process exits.
​
-v, --version
flag
Print full version information and exit.
ant --version
​
--version-raw
flag
Print just the bare version number and exit. Useful for scripts that need to compare or parse the version string.
ant --version-raw
# 0.1.0
​
-h, --help
flag
Print the help message listing all flags and subcommands, then exit.
​
--verbose
flag
Enable verbose output for package manager operations. Has no effect during normal script execution.
​
--no-color
flag
Disable all ANSI color codes in Ant’s output. Set this when piping output to tools that don’t handle escape sequences.
​
--stack-size=<kb>
flag
Override the JavaScript stack size in kilobytes. The default is derived from the operating system thread stack size. Increase this if you hit stack overflow errors in deeply recursive code.
ant --stack-size=8192 script.js
--verbose, --no-color, and --stack-size are consumed by Ant before argument parsing and are not passed through to your script.

​
Package manager subcommands

Ant includes a built-in package manager. Pass a subcommand name as the first positional argument. Each subcommand is covered in detail in the Package Manager section.
SubcommandAliasDescription
init—Create a new package.json
installiInstall dependencies from lockfile
updateupRe-resolve dependencies and refresh lockfile
addaAdd a package to dependencies
removermRemove a package from dependencies
trust—Run lifecycle scripts for packages
run—Run a script from package.json
execxRun a command from node_modules/.bin
whyexplainShow why a package is installed
info—Show package information from registry
lslistList installed packages
cache—Manage the package cache
create—Scaffold a project from a template
You can also invoke antx as a shorthand for ant exec. The antx binary forwards all arguments to the exec subcommand automatically.
Watch mode (--watch) cannot be combined with any subcommand. Ant exits with an error if you attempt this.