Getting started
Limo runs JavaScript in a browser environment, right from your terminal.
Install
Linux and macOS:
curl -fsSL https://github.com/Spxg/limo/releases/latest/download/limo-installer.sh | sh
Windows PowerShell:
irm https://github.com/Spxg/limo/releases/latest/download/limo-installer.ps1 | iex
Releases support Linux (glibc), macOS 13+, and Windows on x86_64 and ARM64.
Limo installs to ~/.local/bin on Linux and macOS, or %LOCALAPPDATA%\Limo\bin on Windows. Follow the printed instructions to add that directory to your PATH if needed.
Run your first script
Create dom.js:
const title = document.createElement("h1");
title.textContent = "Hello, Limo!";
document.body.append(title);
console.log(document.querySelector("h1").textContent);
Run it from the terminal:
limo dom.js
Hello, Limo!
Continue with running JavaScript or the command-line reference.
Running JavaScript
Run a file, a code snippet, or source from standard input. Each runs in a browser page with access to globals such as document and fetch.
Files
Pass a JavaScript file as the entry point:
limo app.js
limo app.mjs
Code snippets
Use -e or --eval to run source code from the command line:
limo -e 'console.log(1 + 2)'
limo -e 'console.log(await Promise.resolve(3))'
The snippet loads as an entry script, just like a file. Use console.log() to print a value.
Standard input
Use - to read source code from standard input:
echo 'console.log(1 + 2)' | limo -
limo - < app.js
When standard input is redirected or piped, you can omit -:
echo 'console.log(1 + 2)' | limo
Limo reads the complete input before running it. Running limo without an input does not start an interactive REPL.
Scripts and modules
By default, Limo chooses the execution mode from the input:
| Input | Execution mode |
|---|---|
.mjs file | ES module |
.cjs file | Rejected; CommonJS is unsupported |
Other files, --eval, or standard input | Detected from the source syntax |
Static import, export, and top-level await select module execution during syntax detection.
Use --input-type to select a mode explicitly. It takes priority over the file extension and syntax detection:
limo --input-type script app.js
limo --input-type module app.js
limo --input-type module -e 'console.log(import.meta.url)'
Limo uses browser ES modules. CommonJS globals such as require and module.exports, and Node.js built-in imports such as node:fs, are unavailable.
Relative files
Limo serves local files from a directory determined by the input:
| Input | Local root |
|---|---|
| JavaScript file | The entry file’s directory |
--eval or standard input | The current working directory |
In page scripts, relative URLs passed to fetch() or new Worker() resolve from this root. Keep local resources inside it. ES module imports resolve relative to the importing module.
For example, limo scripts/main.mjs loads fetch("./data.json") from scripts/data.json. Piping the same code from the repository root loads data.json from the repository root instead.
Requests to external sites follow browser CORS rules.
Output and completion
Console messages from the page and its Workers are forwarded to standard output, including console.warn and console.error.
Limo waits for browser work to become idle before exiting. Clear repeating timers and terminate Workers when their work is done. A pending top-level await alone does not keep the process running.
The default execution timeout is 10 minutes. Set a different limit in milliseconds:
limo --timeout-ms 5000 app.js
Some uncaught JavaScript exceptions currently do not produce a nonzero exit code.
Command-line reference
limo [OPTIONS] [FILE]
Choose an entry file, --eval, or standard input. A file and --eval cannot be supplied together.
Run limo -h for built-in help.
| Argument or option | Description | Default |
|---|---|---|
[FILE] | JavaScript entry file; use - to read standard input. | Read redirected or piped standard input. |
-e, --eval <CODE> | Run JavaScript source supplied on the command line. | |
--input-type <TYPE> | Execute as script or module. Applies to files, snippets, and standard input. | File extension or syntax detection. |
--port <PORT> | Port for the local server that loads the script and nearby files. | An available port chosen by the OS. |
--profile-dir <PATH> | Directory for persistent browser state. | Temporary storage. |
--disable-web-security | Disable browser web security, including CORS checks. | Off. |
--timeout-ms <MS> | Execution timeout in milliseconds. | 600000 (10 minutes). |
-h, --help | Print help. | |
-V, --version | Print the version. |
See running JavaScript for examples, execution modes, and relative file paths.
Reuse browser state
Use a fixed port and the same profile directory across runs:
limo --port 3000 --profile-dir .limo-profile app.js
--profile-dir keeps browser data on disk. Browser storage is scoped to an origin, so keep the same --port to access it again. Without these options, Limo uses a temporary profile and an automatically assigned port.