Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

InputExecution mode
.mjs fileES module
.cjs fileRejected; CommonJS is unsupported
Other files, --eval, or standard inputDetected 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:

InputLocal root
JavaScript fileThe entry file’s directory
--eval or standard inputThe 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 optionDescriptionDefault
[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-securityDisable browser web security, including CORS checks.Off.
--timeout-ms <MS>Execution timeout in milliseconds.600000 (10 minutes).
-h, --helpPrint help.
-V, --versionPrint 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.