`, using `moduleName` or the module holding the entrypoint. An entrypoint outside
any module builds from the class path. `moduleName` has no effect without modular JARs.
## Compile to WebAssembly
Declare a `WebImage` artifact or pass `--tool:wasm-gc` / `--tool:wasm-lm`; see [WebImage](https://elide.help/docs/toolchain/jvm/webimage).
To run existing WASM, see [WebAssembly](https://elide.help/docs/wasm). A native image can be the input to a
[container image](https://elide.help/docs/toolchain/jvm/containers).
---
# WebImage: JVM to WebAssembly
URL: https://elide.help/docs/toolchain/jvm/webimage
> Compile JVM code to a JavaScript loader and WebAssembly module.
Status: experimental. A `WebImage` artifact compiles JVM bytecode to a JavaScript loader plus a WASM module. To run
an existing WASM or WASI binary, see [WebAssembly](https://elide.help/docs/wasm).
## Prerequisites
- [Binaryen](https://github.com/WebAssembly/binaryen) 119 or later, with `wasm-as` on `PATH` at build time.
- Code that meets the [Native Image requirements](https://elide.help/docs/toolchain/jvm/native-image): reachability metadata for reflection,
resources and proxies; no native dependencies.
- A host with WASM exception handling (and WASM GC for `wasm-gc`): Node.js 25+ or a current browser.
The deployed bundle needs neither Elide nor Binaryen.
## Build a complete project
```text
hello-wasm/
elide.pkl
src/main/java/Hello.java
```
```java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello from WebImage");
}
}
```
```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as jvm
import "elide:NativeImage.pkl" as nativeImage
name = "hello-wasm"
artifacts {
["app-jar"] = new jvm.Jar {
sources { "main" }
}
["web"] = new nativeImage.WebImage {
from { "app-jar" }
name = "hello"
entrypoint = "Hello"
backend = "wasm-gc"
runtime = "generic"
autoRun = true
sourceMap = false
options {
optimization = "b"
}
}
}
```
```bash
elide build
```
Elide builds `app-jar`, then compiles it to `web`. `name` is the basename without `.js` or `.wasm`;
`optimization = "b"` is quick-build mode. Output is written to `.dev/artifacts/native-image/`:
| File | Purpose |
| --- | --- |
| `hello.js` | JavaScript loader and entrypoint. |
| `hello.js.wasm` | WASM module, loaded by `hello.js`. |
| `hello.js.wat` | WASM text form, for inspection. |
| `hello.js.map` | Source map for the loader, when `sourceMap = true`. |
Deploy `hello.js` and `hello.js.wasm` together. Kotlin and other JVM languages work the same way once packaged in a
JAR. A cache hit restores the whole bundle; turning `sourceMap` off removes the old `.js.map`.
## Choose a backend and host
| Property | Value | Meaning |
| --- | --- | --- |
| `backend` | `"wasm-gc"` (default) | Uses the host's WASM garbage collector. |
| `backend` | `"wasm-lm"` | Uses a garbage collector in linear memory; still needs the loader, not a WASI binary. |
| `runtime` | `"generic"` (default) | Loader supports browsers and Node. |
| `runtime` | `"browser"` | Loader specialized for browsers. |
| `runtime` | `"node"` | Loader specialized for Node-compatible APIs. |
| `autoRun` | `true` (default) | Starts the program when the loader loads; `false` leaves startup to the embedding page. |
| `sourceMap` | `false` (default) | `true` emits `hello.js.map`. |
An entrypoint is required even with `autoRun = false`. No `runtime` targets Cloudflare Workers, Fastly Compute or
WASI. Shared fields (`from`, `entrypoint`, `moduleName`, `options`) are listed under
[Native Image](https://elide.help/docs/toolchain/jvm/native-image#project-artifact). A WebImage cannot be the input to a
[container artifact](https://elide.help/docs/toolchain/jvm/containers).
### Run on a backend host
With `runtime = "generic"` or `"node"`:
```bash
node .dev/artifacts/native-image/hello.js
```
```text
Hello from WebImage
```
### Run in a browser
With `runtime = "browser"` or `"generic"` and `autoRun = true`, put this `index.html` in
`.dev/artifacts/native-image/`:
```html
Hello WebImage
Open the browser console to see the application output.
```
```bash
elide serve --no-tui --port 8000 .dev/artifacts/native-image
```
Open `http://localhost:8000/`; the output appears in the browser console. `file://` URLs do not work.
## Compiler options
The artifact's `options` block takes the [Native Image compiler options](https://elide.help/docs/toolchain/jvm/native-image#compiler-options);
which apply depends on the backend. Two cases specific to WebImage:
- `options.driverMode = "external"` uses the compiler at `GRAALVM_HOME` or `JAVA_HOME`, which must include the
`svm-wasm` modules.
- `-H:EntryPointsConfig=config/entrypoints.json` in `options.flags` sets entry points; the path is relative to the
project root, and editing the file triggers a rebuild.
Do not combine the typed properties with raw flags for backend, runtime, startup or source maps.
## Compile without a project manifest
```bash
elide javac -- -d classes src/main/java/Hello.java
elide native-image -- --tool:wasm-gc -Ob -cp classes -o hello Hello
elide native-image -- --tool:wasm-lm -Ob -cp classes -o hello-lm Hello
```
Bundles are written to the current directory. A `NativeImage` artifact with `--tool:wasm-gc` or `--tool:wasm-lm` in
`options.flags` still builds. To migrate it, change the class to `WebImage`, drop the flag and any `type`, and set
`backend`.
## Troubleshooting
| Symptom | Fix |
| --- | --- |
| `wasm-as` not found | Install Binaryen and put it on the build's `PATH`. |
| External driver cannot load `svm-wasm` | Use an installation that includes the `svm-wasm` modules. |
| Conflicting raw options | Remove backend, runtime, startup and source-map flags; use the typed properties. Do not override `Backend` or the launcher property. |
| Host rejects WASM instructions | Use a host with exception handling and, for `wasm-gc`, WASM GC. |
| Browser cannot load the module | Serve loader and module together over HTTP; check the requested URL. |
| `elide run hello.js.wasm` reports missing imports | Run `hello.js` instead; the module needs its loader. |
---
# JVM Containers
URL: https://elide.help/docs/toolchain/jvm/containers
> Build a container image from a JAR or native-image artifact.
Container images are project artifacts; there is no `elide` container subcommand.
## Declare an image
```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm
import "elide:Container.pkl" as Container
artifacts {
["app"] = new Jvm.Jar {
sources { "main" }
}
["image"] = new Container.ContainerImage {
from { "app" }
image = "my-app"
base = "eclipse-temurin:25-jre"
tags { "latest" }
output = "daemon"
}
}
```
```bash
elide build
```
## Fields
| Property | Values | Default |
| --- | --- | --- |
| `from` | Exactly one `Jvm.Jar` (JVM image) or `NativeImage` (executable image). | — |
| `image` | Target image coordinate. | — |
| `base` | Base image coordinate. | — |
| `tags` | Image tags. | none |
| `output` | `"daemon"` (local Docker daemon) or `"tarball"` (importable archive). | `"daemon"` |
| `format` | `"docker"` (manifest v2) or `"oci"`. | `"docker"` |
| `dependsOn` | Artifacts to build first. | none |
An empty `from`, two distinct entries, or any other artifact type (including a WebImage) fails validation before the
build.
---
# Web Toolchain
URL: https://elide.help/docs/toolchain/web
> Run JavaScript and TypeScript, serve files, process web assets and configure web builds.
## Run JavaScript and TypeScript
```bash
elide run app.js
elide run app.ts
```
TypeScript types are stripped. `.mjs`, `.cjs`, `.mts` and `.cts` also work.
## Serve and develop
```bash
elide serve dist # serve a directory on 127.0.0.1:8080
elide dev src # dev server on 127.0.0.1:3000, with watching and live reload
```
`--host` and `--port` set the address, `--no-watch` disables watching, `--no-tui` prints plain logs. More, including
`--contexts`: [Development Server](https://elide.help/docs/dev-server).
## Process assets
No manifest needed:
```bash
elide web build app.ts --out dist # JavaScript
elide web build page.md --out dist # HTML
elide web build style.css --out dist # CSS
```
Several sources and shell globs are accepted.
## Install npm packages
```bash
elide install --ecosystems=npm
```
See [NPM Installer](https://elide.help/docs/toolchain/web/npm).
## Manifest settings
```pkl
web {
minifyHtml = true
css {
minify = true
targets {
new { browser = "chrome"; version = "120" }
new { browser = "safari" }
}
}
}
javascript {
ecma = "stable"
}
```
| Property | Meaning | Default |
| --- | --- | --- |
| `web.minifyHtml` | Minify HTML, including inline scripts and styles. | `true` |
| `web.css.minify` | Minify CSS. | `true` |
| `web.css.targets` | CSS browser targets: `browser` (`chrome`, `firefox`, `safari`, `edge`, `opera` or other) and optional `version`. | none |
| `web.browsers` | Browser targets for all outputs; `css.targets` overrides it for CSS. | none |
| `javascript.ecma` | Target: a year `2015` … `2025`, `"stable"` or `"latest"`. | `"stable"` |
## Project builds
To build a site with `elide build`, declare a [static-site artifact](https://elide.help/docs/toolchain/web/static-site).
---
# NPM Installer
URL: https://elide.help/docs/toolchain/web/npm
> Install npm packages with elide install.
```bash
elide install --ecosystems=npm
```
npm is opt-in; a bare `elide install` installs Maven only. Elide reads `package.json` and the `npm` block in
`elide.pkl`:
```pkl
amends "elide:project.pkl"
dependencies {
npm {
packages {
"react@19.0.0"
}
devPackages {
"typescript@5.6.2"
}
}
}
```
| Property | Meaning |
| --- | --- |
| `packages` | `name@version` or `@scope/name@version`. |
| `devPackages` | Development-time packages. |
Packages go to `.dev/dependencies/npm/node_modules`, linked from `node_modules` at the project root. Resolution is
recorded in `aube-lock.yaml`. Ecosystem selection and shared options: [Dependencies](https://elide.help/docs/toolchain/dependencies).
---
# Static Sites
URL: https://elide.help/docs/toolchain/web/static-site
> Build a static-site artifact from Markdown, scripts, styles and images.
A `StaticSite` artifact renders Markdown, processes scripts and stylesheets, compresses images and copies everything
else.
```pkl
amends "elide:project.pkl"
import "elide:Web.pkl" as Web
artifacts {
["site"] = new Web.StaticSite {
srcs = "site"
domain = "example.com"
stylesheets { "site/theme.css" }
hosting = "github-pages"
}
}
```
```bash
elide build
```
## Fields
| Property | Meaning | Default |
| --- | --- | --- |
| `srcs` | Source directory, relative to the project. | — |
| `domain` | Production domain. | — |
| `preview` | Preview domain; informational. | — |
| `prefix` | Mount path for links and assets; must end with `/`. | `"/"` |
| `assets` | Public asset path. | `"_/assets"` |
| `stylesheets` | Added to every page, besides those in its frontmatter. | none |
| `scripts` | Added to every page, besides those in its frontmatter. | none |
| `rewriteLinks` | Rewrite relative Markdown links against `prefix`. | `true` |
| `hosting` | `"workers"` or `"github-pages"`; informational, the build does not publish. | — |
| `dependsOn` | Artifacts to build first. | none |
Minification and browser targets come from the `web` block ([Web Toolchain](https://elide.help/docs/toolchain/web#manifest-settings)).
Without image codecs, the build warns once and copies images unchanged.
---
# Development Server
URL: https://elide.help/docs/dev-server
> Serve files with live reload, run fetch handlers, and replicate a server across contexts.
```bash
elide dev ./public
elide serve ./dist
```
| Command | Default address | Watches files | Live reload |
| --- | --- | --- | --- |
| `elide dev` | `127.0.0.1:3000` | Yes | Static files only |
| `elide serve` | `127.0.0.1:8080` | No | No |
A directory subject starts a file server; a script subject runs as a program.
| Flag | Effect |
| --- | --- |
| `--host HOST` | Bind host. |
| `--port PORT` | Bind port. |
| `--no-tui` | Plain log output instead of the TUI. |
| `--no-watch` | `dev` only: no watching or reload. |
| `--contexts=N` | Run `N` copies of the app; `auto` sizes from the CPU cores. Linux only. |
## Fetch handlers
```js
// entrypoint.mjs
export default {
async fetch(request) {
return new Response("ok");
},
};
```
```bash
elide serve entrypoint.mjs
```
`elide run entrypoint.mjs` also serves, on the exported `hostname` and `port` or `127.0.0.1:8080`.
`Elide.serve({ port: 3005, fetch })` uses its own address with every command.
## Replicated serving
```bash
elide serve --contexts=4 entrypoint.mjs
```
- Each context runs the entry module once and keeps its own globals; a request counter counts per context.
- A connection stays on one context for its lifetime, including keep-alive requests.
- If one context fails, the server stops.
Set `engine.contexts` in `elide.pkl` for finer control; see [Engine contexts](https://elide.help/docs/elide-pkl-reference#engine-contexts).
---
# Interactive REPL
URL: https://elide.help/docs/repl
> Evaluate JavaScript, TypeScript, Python and WebAssembly interactively and share values between them.
```bash
elide repl
```
`elide` with no arguments in a terminal also starts it. Languages: JavaScript, TypeScript, Python and WebAssembly.
## Commands
| Command | Effect |
| --- | --- |
| `/js`, `/ts`, `/py`, `/wasm` | Switch language. With an argument, evaluate it once in that language. |
| `/lang NAME` | Switch language. |
| `/export NAME` | Share a value with the other languages. |
| `/import NAME` | Bind a shared value in the current language. |
| `/history [N]` | Show recent entries. |
| `/reset` | Delete saved history. |
| `/clear` | Clear the screen. |
| `/help` | List commands. |
| `/exit` | Leave the REPL. |
## Share values
```text
const x = 41
/export x
/py
/import x
print(x + 1)
```
```text
42
```
Sharing works without `--interop`.
---
# Languages and Interop
URL: https://elide.help/docs/languages
> Which languages Elide runs, how to start each one, and how they call each other.
| Language | Status | Runs as | Start with | Interop |
| --- | --- | --- | --- | --- |
| JavaScript | Supported | Script | `elide app.js`, `elide -s CODE` | Python: `--interop`; WASM: no flag |
| TypeScript | Supported | Script, types stripped | `elide app.ts`, `elide -l ts -s CODE` | As JavaScript |
| Python | Experimental | Python 3.13 | `elide app.py`, `elide python -m MOD` | JavaScript: `--interop` |
| WebAssembly | Experimental | WASI Preview 1 command | `elide app.wasm` (`_start` or `_main`) | From JS/TS, no flag |
| Java, Kotlin | Supported | Compiled, run on the bundled JDK | `elide run Main.kt`, `elide.pkl` projects | None |
| Pkl | Supported | Configuration | `elide.pkl` manifests | None |
`elide info` lists the languages in your binary; `elide setup python` adds Python. Per-language pages:
[JavaScript and TypeScript](https://elide.help/docs/web), [Python](https://elide.help/docs/python), [Java and Kotlin](https://elide.help/docs/jvm),
[WebAssembly](https://elide.help/docs/wasm).
## Python calling JavaScript
```python
# sum.py
from elide import js
print(js("[1,2,3].reduce((a,b)=>a+b,0)"))
```
```bash
elide --interop python sum.py
```
```text
6
```
## JavaScript importing Python
```python
# mod.py
def greet(name):
return f"hello {name}"
```
```javascript
// main.mjs
import mod from "./mod.py";
console.log(mod.greet("elide"));
```
```bash
elide --interop main.mjs
```
```text
hello elide
```
Import the `default` export; it is the Python module. Use an `.mjs` entry.
## Without `--interop`
Each program runs only its entry language, plus WebAssembly for JS/TS. Calls between languages fail:
| Program | Error |
| --- | --- |
| `sum.py` | `ValueError: polyglot language 'js' not found` |
| `main.mjs` | `Cannot import 'mod.py': JavaScript entries run without Python. Re-run with --interop to use it.` |
Pass `--interop` only to programs that call between languages. Under `--interop`, Python threads fail with
`Creating threads is not allowed.`
## JavaScript and WebAssembly
```javascript
import { add } from "./math.wasm";
console.log(add(1, 2));
```
`.wasm` imports and the `WebAssembly` API work in every JS and TS program. When Python is installed, modules that use
SIMD instructions are rejected with `Vector instructions are not enabled`.
## In the REPL
The REPL shares values across languages without `--interop`; see [Interactive REPL](https://elide.help/docs/repl).
---
# Editors & IDEs
URL: https://elide.help/docs/connect-ide
> Connect an editor to Elide with a plugin or the Java language server.
| Editor | Use |
| --- | --- |
| IntelliJ IDEA | [IntelliJ IDEA Plugin](https://elide.help/docs/intellij) |
| VS Code | [VS Code Extension](https://elide.help/docs/vscode) |
| Any LSP client | `elide lsp` (Java) |
| AI agents | [MCP Server](https://elide.help/docs/mcp) |
## Java language server
```bash
elide lsp
```
`elide lsp` is an LSP server on stdio. Set it as the server command for the `java` language. The client must send a
workspace root (`rootUri`); launch it from the project directory.
Editors get diagnostics, completion, hover, signature help, go to definition, references, rename, formatting, code
actions, inlay hints and semantic highlighting.
---
# IntelliJ IDEA Plugin
URL: https://elide.help/docs/intellij
> Import, run and debug Elide projects in IntelliJ IDEA.
## Requirements
- IntelliJ IDEA 2025.1 or newer.
- Elide installed ([Installation](https://elide.help/docs/installation)).
- A JDK registered in the IDE, for JVM projects.
## Install
In **Settings → Plugins → ⚙ → Manage Plugin Repositories**, add:
```text
https://plugins.elide.dev/intellij
```
Install **Elide** from the Marketplace tab and restart the IDE. Install **Pkl** from the same repository for
completion and inspections in `elide.pkl`.
## Import a project
Open a directory that contains `elide.pkl` ([Projects](https://elide.help/docs/projects)). The plugin links it and syncs in the background.
- Each source set becomes a module; dependencies become libraries with sources attached.
- The project SDK is the JDK for `jvm.target`, or the newest installed JDK.
- Editing `elide.pkl` or the lockfile prompts a reload.
The **Elide** tool window lists linked projects and has the reload actions.
## Run
Create an **Elide** run configuration. Its command line takes anything the CLI accepts, with completion:
```text
run
test -t 'MyTest'
serve --port 8080
run app.js -- --flag-for-the-program
```
Run and debug icons appear on `jvm.main`, `entrypoint` and `scripts` entries in `elide.pkl`, on `main` functions,
and on JUnit tests. **Run Anything** (double Ctrl) also accepts `elide …`.
## Debug
**Debug** on a `run` configuration adds `--debugger` and attaches the IDE's JVM debugger. To debug tests, run
`elide test --debugger` and attach a **Remote JVM Debug** configuration to `localhost:5005`. See
[Debugging](https://elide.help/docs/debugging).
## Choose an Elide install
**Settings → Build, Execution, Deployment → Build Tools → Elide** sets **Elide distribution** to *Auto-detect* or a
custom path. Auto-detect checks `$ELIDE_HOME`, then:
| Platform | Locations, in order |
| --- | --- |
| Unix | `$XDG_DATA_HOME/elide`, `~/.local/share/elide`, `/opt/elide/current`, `~/.elide` |
| Windows | `%LOCALAPPDATA%\elide`, `%ProgramFiles%\Elide`, `%USERPROFILE%\.local\share\elide`, `%USERPROFILE%\.elide` |
---
# VS Code Extension
URL: https://elide.help/docs/vscode
> Sync, run and debug Elide projects in Visual Studio Code.
## Requirements
- VS Code 1.105 or newer.
- Elide installed ([Installation](https://elide.help/docs/installation)).
- The **Kotlin by JetBrains** extension (`JetBrains.kotlin-server`). It installs automatically; finish its one-time
setup prompt.
- A separate JDK for code intelligence, set with `elide.jdk.home` or `$JAVA_HOME`.
## Install
```bash
curl -LOJ "https://plugins.elide.dev/vscode/files?id=elide.elide"
code --install-extension elide-*.vsix
```
## Sync a project
Opening a folder with `elide.pkl` syncs it into `workspace.json`, which the Kotlin extension reads. Add
`workspace.json` to `.gitignore`. Click the **Elide** status bar item to sync again.
| Status bar | Meaning |
| --- | --- |
| **Elide** with a check | In sync |
| **Elide** with a spinner | Syncing |
| **Elide: out of date** | `elide.pkl` changed; click to sync |
| **Elide**, error-colored | Sync failed; click to retry, or run **Elide: Show Output** |
If the folder also has `.idea`, set `"intellij.buildTool": "json"` in `.vscode/settings.json` so the Kotlin extension
reads `workspace.json`.
## Run
| Command | Effect |
| --- | --- |
| `Elide: Sync Project(s)` | Sync again. |
| `Elide: Run Elide Command…` | Run `build`, `test`, `install`, or `run ` as a task. |
| `Elide: Show Output` | Show CLI output and the sync log. |
Tasks use type `elide`:
```jsonc
{ "type": "elide", "command": "test", "args": ["-t", "MyTest"] }
```
`command` is `build`, `run`, `test` or `install`; `args` follow the command; `project` picks a project root.
## Debug
```jsonc
{
"type": "elide",
"request": "launch",
"name": "Elide: Run (debug)",
"entrypoint": "src/main.kt"
}
```
Without `entrypoint`, the manifest's `entrypoint` or `jvm.main` runs. `args`, `env` and `project` are optional.
`elide.debug.adapter` picks the debugger: `intellij` (default, from the Kotlin extension) or `java` (install
[Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug)).
To debug tests, see [Debugging](https://elide.help/docs/debugging#debug-tests).
## Settings
| Setting | Default | Effect |
| --- | --- | --- |
| `elide.home` | `""` | Elide install root. Empty: `$ELIDE_HOME`, install locations, then `elide` on `PATH`. |
| `elide.jdk.home` | `""` | JDK for code intelligence. Empty: `jvm.javaHome`, `$JAVA_HOME`, a JDK for `jvm.target`. |
| `elide.sync.onStartup` | `true` | Sync when the workspace opens. |
| `elide.sync.onManifestChange` | `"prompt"` | `always`, `prompt` or `never`. |
| `elide.kotlinLsp.writeWorkspaceJson` | `true` | Write `workspace.json`. |
| `elide.debug.adapter` | `"intellij"` | `intellij` or `java`. |
---
# MCP Server
URL: https://elide.help/docs/mcp
> Give AI agents Elide's build, run and Insights tools over the Model Context Protocol.
```bash
elide mcp
elide mcp --mode http --host localhost --port 8125
```
`--mode` is `stdio` (default) or `http` (default address `localhost:8125`). Start it in a project directory, or pass
`--project PATH`.
## Client config
```json
{
"mcpServers": {
"elide": { "command": "elide", "args": ["mcp"] }
}
}
```
## Tools
| Tool | Does |
| --- | --- |
| `build/inspect` | List the project's build tasks and their options without running them. |
| `build/run` | Start a build in the background and return a `buildId`. |
| `build/status` | Report the state of a build by `buildId`. |
| `build/cancel` | Cancel a running build. |
| `run/file` | Run a file in any supported language. |
| `run/snippet` | Run inline code in any supported language. |
| `insight/run` | Run a script with an [Insights](https://elide.help/docs/api-insight) script attached and return its events. |
| `elide` | Run any `elide` command. |
## Resources
| URI | Contains |
| --- | --- |
| `elide://advice/builtin` | Common commands and behavior. |
| `elide://insights/api` | TypeScript definitions for the Insights API. |
| The project's `elide.pkl` | The project manifest. |
---
# Elide for AI Agents
URL: https://elide.help/docs/agents
> Run Elide non-interactively and collect diagnostics.
Elide runs, builds, tests and formats JavaScript, TypeScript, Python, Java and Kotlin projects. When Elide detects an
agent harness, its output is plain and non-interactive; `ELIDE_AGENT=1` forces this.
## Invocation
```bash
NO_COLOR=1 ELIDE_LOG=warn ELIDE_ERROR_FORMAT=plain CI=1 \
elide --ignore-version --timeout=120s
```
`--ignore-version` ignores a project `.elideversion` pin. `ELIDE_ERROR_FORMAT=plain` sends program output to stdout
and uncaught errors to stderr. `--quiet` silences progress only.
## Commands that need a terminal
| Interactive | Use instead |
| --- | --- |
| `elide repl`, bare `elide python` | `elide run `, `elide python `, or an inline `-s` snippet |
| `elide init` | `elide init --plain --skip-defaults --template `; ids from `elide init --templates --json` |
| `elide adopt` | `elide adopt --non-interactive --build --harness --approval ` |
| `elide serve`, `elide dev` | Add `--no-tui`. |
| `elide help` | `elide help --format=markdown` |
`elide adopt` launches `codex`, `claude` or `omp`, and `upgrade`, `setup` and `use` change the installation; run them
only when asked. `--approval` must be `auto-approve` or `yolo`.
## Exit 0 with no work done
- `elide test` with no tests prints `No tests found.`
- Plain `elide install` installs Maven only; use `--workspace` or `--ecosystems=npm` for `package.json`.
- `--workspace` skips `dependencies.pypi`; `--verbose` reports the skip on stderr.
- Without a terminal, `elide repl` and bare `elide python` read stdin; empty stdin runs nothing.
## Exit codes
| Code | Meaning |
| --- | --- |
| `0` | Success, help, or version output. |
| `1` | The command or guest program ran and failed. |
| `2` | Invalid CLI usage or an unresolved run target. |
| `3` | `--heap-dump-on-oom` wrote a heap dump after an out-of-memory error. |
| `124` | `--timeout` expired. |
| other | The guest program or tool chose its own code. |
## Commands
| Command | Use |
| --- | --- |
| `elide run ` | Run a program; script arguments follow `--`. |
| `elide python ` | Run with Python-style arguments. |
| `elide build --inspect` | List project task names. |
| `elide test ` | Run tests; raise `--concurrency` to parallelize. |
| `elide project export` | Print the manifest as JSON; `--format=pom` or `--format=intellij` for other tools. |
| `elide classpath :` | Print a resolved classpath, e.g. `test:runtime`. |
| `elide install` | Install Maven dependencies; `--ecosystems=npm` for npm, `--workspace` for all. |
| `elide format --list-files -- --dry-run ` | Name files that need formatting; exit `1` if any. |
`elide install` accepts `--with=sources` and `--with sources`; `--with:sources` is not accepted. `elide format` has
no `--check`; `--set-exit-if-changed` is accepted but not required. In a project, prefer `elide run` and
`elide build` to `java`, `javac`, `kotlinc` and `jar`.
## Running a script
`elide run 
`elide info` lists the available languages, including `python` when it is installed. If the shell cannot find
`elide`, open a new terminal or add the install's `bin` folder to `PATH`.
| Platform | Architectures |
| --- | --- |
| Linux | `amd64`, `arm64` |
| macOS | Apple Silicon |
| Windows | `amd64` |
---
# Packages & Installers
URL: https://elide.help/docs/installation/packages
> Install Elide with Homebrew, apt, RPM, or the macOS and Windows installers, and verify downloads
Upgrade these installs through their package manager, not `elide upgrade`. Only Homebrew includes Python; see
[Installation](https://elide.help/docs/installation#python).
## Homebrew
```bash
brew install elide-dev/elide/elide
brew upgrade elide
```
The [`elide-dev/homebrew-elide`](https://github.com/elide-dev/homebrew-elide) tap tracks `nightly` on macOS (Apple
Silicon) and Linux (`amd64`, `arm64`).
## Debian and Ubuntu (apt)
```bash
curl -fsSL https://keys.elide.dev/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/elide.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/elide.gpg]" \
"https://dl.elide.dev release main" | sudo tee /etc/apt/sources.list.d/elide.list
sudo apt update && sudo apt install elide
```
Replace `release` with `nightly` for daily builds. Upgrade with `sudo apt update && sudo apt upgrade elide`. The
package installs into `/opt/elide/
## Python
Needs the Python component ([Installation](https://elide.help/docs/installation#python)).
```python
# hello.py
print("Hello from Python!")
```
```bash
elide python hello.py
```
## Java or Kotlin
```java
// Hello.java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello from Java!");
}
}
```
```bash
elide run Hello.java
elide run Hello.kt # Kotlin works the same way
```
## WebAssembly
```bash
elide run app.wasm
```
See [WebAssembly with Elide](https://elide.help/docs/wasm).
## Start a project
```bash
elide init --plain --skip-defaults --template java
elide build
elide run
elide test
```
`elide init --templates` lists templates. In a terminal, `elide init` without flags opens an editor for the parameters.
To move an existing Java or Kotlin project to Elide, run `elide adopt` in it; see
[Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt).
Next: [Elide Projects](https://elide.help/docs/projects) or [Code Samples](https://elide.help/docs/code-samples).
---
# JavaScript and TypeScript with Elide
URL: https://elide.help/docs/web
> Run JavaScript and TypeScript, install npm packages, test, and serve with Elide
Elide runs JavaScript and TypeScript directly, with CommonJS, ES modules, and a subset of the Node and Web APIs.
TypeScript needs no compile step and no `tsconfig.json`.
```bash
elide run app.js
elide run app.ts
elide app.ts
elide run -s 'console.log(1 + 1)'
```
Extensions: `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`. JSX and TSX are transformed, but Elide
provides no UI framework or DOM; install what your code imports, such as React's `react/jsx-runtime`.
## npm packages
Declare dependencies in `package.json`. Plain `elide install` skips npm, so pass `--ecosystems=npm`:
```json
{
"type": "module",
"dependencies": { "zod": "3.24.1" }
}
```
```ts
// app.ts
import { z } from "zod";
const User = z.object({ name: z.string() });
console.log(`Hello, ${User.parse({ name: "Ada" }).name}!`);
```
```bash
elide install --ecosystems=npm
elide run app.ts
```
The general commands also run `.py` files, with the same `sys.argv`:
```bash
elide app.py
elide run app.py
elide -l python -s 'print(1 + 1)'
```
### Interpreter options
These go before the script, `-c`, or `-m`. `elide --help-all` lists them under "Python interpreter options".
| Flag | Effect |
| --- | --- |
| `-c CMD` | Run `CMD` as the program; trailing tokens become `sys.argv[1:]`. |
| `-m MODULE` | Run a library module as `__main__`. |
| `-s` | Don't add the user site directory to `sys.path`. |
| `-I` | Isolated mode. |
| `-E` | Ignore `PYTHON*` environment variables. |
| `-S` | Don't `import site` on startup. |
| `-P` | Don't prepend a potentially unsafe path to `sys.path`. |
| `-B` | Don't write bytecode files. |
| `-u` | Unbuffered standard output and error. |
| `-O` | Optimization level; repeat for `-OO`. |
| `-b` | Warn on `bytes`/`str` comparisons; repeat to raise errors. |
| `-W ARG` | Warning control; repeatable. |
| `-x` | Accepted for compatibility; no effect. |
## Standard library
The Python 3.13 standard library is included, among it `json`, `pathlib`, `sqlite3`, `ssl`, `zlib`, and
`ctypes`. `bz2` and `lzma` need no system `libbz2` or `liblzma`.
## JavaScript interop
With `--interop`, Python evaluates JavaScript through the built-in `elide` module:
```python
# sum.py
from elide import js
print(js("[1, 2, 3].reduce((a, b) => a + b, 0)"))
```
```bash
elide --interop python sum.py
```
JavaScript and TypeScript import a Python module's default export:
```javascript
// main.mjs
import mod from "./mod.py";
console.log(mod.hello());
```
```bash
elide --interop run main.mjs
```
Without `--interop`, these calls fail. See [Languages and Interop](https://elide.help/docs/languages).
## Third-party packages
Elide does not install PyPI packages: `elide install` skips `dependencies.pypi`, and
`elide install --ecosystems=pypi` exits `2`. Packages in a Python 3.13 virtual environment load when `VIRTUAL_ENV`
points at it:
```bash
export VIRTUAL_ENV=/path/to/venv
elide python app.py
```
Elide reads the environment's `lib/python3.13/site-packages`.
## Known limitations
- **C extensions**: some C extension modules do not load.
- **macOS**: native module isolation is not available.
- **WebAssembly SIMD**: installing Python disables it; see [WebAssembly with Elide](https://elide.help/docs/wasm#limits).
- **CPython differences**: some edge cases behave differently from CPython 3.13; see the
[Compatibility Matrix](https://elide.help/docs/compatibility).
---
# Java and Kotlin with Elide
URL: https://elide.help/docs/jvm
> Run, compile, format, build, and test Java and Kotlin with Elide's built-in JDK 25 and Kotlin toolchain
Elide compiles, formats, builds, and tests Java (up to JDK 25) and Kotlin (2.5.0-Beta1), and resolves Maven
dependencies.
## Run a source file
A file with a `main` entrypoint compiles and runs directly:
```bash
elide run Hello.java
elide run Hello.kt
```
## Use individual tools
`elide java`, `elide javac`, `elide kotlinc`, and `elide jar` behave like the tools of the same name. Pass their
arguments after `--`:
```bash
elide javac -- -d target src/main/java/app/Main.java
elide kotlinc -- -d target src/main/kotlin/app/Main.kt
elide java -- -cp target app.Main
```
`elide format` formats Java with Google Java Format and Kotlin with ktfmt:
```bash
elide format -- src # rewrite files
elide format --list-files -- --dry-run src # list files that would change; exit 1 if any
```
## Start a project
```bash
elide init --plain --skip-defaults --template java
```
| Template | Creates |
| --- | --- |
| `java` | A Java project. |
| `ktjvm` | A Kotlin project. |
| `workspace` | A Kotlin library and an app that depends on it. |
For an existing Maven or Gradle project, `elide adopt` runs an AI coding agent to do the migration; see
[Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt).
## Build a project
```bash
elide install # resolve Maven dependencies
elide build # compile and assemble artifacts
elide test # run JUnit tests
elide run # run the project's main class
```
`elide build --inspect` lists the project's task names. See [Elide Projects](https://elide.help/docs/projects) for the manifest and
[JVM Toolchain](https://elide.help/docs/toolchain/jvm) for compiler and packaging options.
---
# WebAssembly with Elide
URL: https://elide.help/docs/wasm
> Run WASI command modules and load WASM libraries from JavaScript and TypeScript
WebAssembly support is experimental in 1.6.0.
| You have | Use | Result |
| --- | --- | --- |
| A WASI command | `elide run app.wasm` | Runs the module with WASI Preview 1 imports. |
| A WASM library | The `WebAssembly` API or an ES module import from JS/TS | Exposes the module's exports. |
To compile Java or Kotlin to WebAssembly, see [WebImage](https://elide.help/docs/toolchain/jvm/webimage); its output needs its JavaScript
loader and does not run with `elide run`.
## Run a WASM file
```bash
elide run app.wasm
elide app.wasm
elide run app.wasm -- first second # program arguments
elide run --timeout=5s app.wasm # exit 124 after 5 seconds
```
Elide calls the module's exported `_start`, or `_main` if `_start` is absent; a module with neither fails, so load it
from JavaScript instead.
| Behavior | Value |
| --- | --- |
| Argument zero | The module's absolute path. |
| Exit status | Set by WASI `proc_exit`, not by a function's return value. |
| Traps, malformed binaries | Nonzero exit. |
| `--timeout` | Covers instantiation and execution; exits `124`. |
### Project entrypoints
Name a module as the project entrypoint in `elide.pkl`, then run `elide run` in the project:
```pkl
amends "elide:project.pkl"
name = "wasm-app"
entrypoint { "app.wasm" }
```
See [Elide Projects](https://elide.help/docs/projects).
## WASI
Commands receive **WASI Snapshot Preview 1** imports under `wasi_snapshot_preview1`: standard streams,
arguments, exit status, and filesystem operations. Libraries loaded from JavaScript do not get WASI.
### Directory access
WASI commands cannot access host directories until you map one:
```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run app.wasm
```
This exposes `./data` as the guest directory `work`. Separate mappings with commas:
`work::./data,output::./results`.
The sandbox still applies, and WASI file opens need both read and write permission, even for reads:
```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run \
--sandbox --allow-read=./data --allow-write=./data app.wasm
```
See [Sandbox and Limits](https://elide.help/docs/sandbox).
## JavaScript and TypeScript interop
The global `WebAssembly` API needs no flag:
```javascript
import { readFile } from "node:fs/promises";
const bytes = await readFile(new URL("./math.wasm", import.meta.url));
const { instance } = await WebAssembly.instantiate(bytes, {});
console.log(instance.exports.add(20, 22));
```
Elide does not call `_start` or `_main` on modules loaded from JavaScript. The second argument supplies the
module's imports:
```javascript
const imports = { env: { log: (value) => console.log(value) } };
const { instance } = await WebAssembly.instantiate(bytes, imports);
```
The API includes `validate`, `compile`, `Module`, `Instance`, `Memory`, `Table`, `Global`, and import and export
inspection. A compiled `Module` can be instantiated more than once. File reads follow the same permissions as other
JS code.
### ES module imports
```javascript
import { add } from "./math.wasm";
console.log(add(20, 22));
```
```javascript
const math = await import("./math.wasm");
console.log(math.add(20, 22));
```
Specifiers can be relative or absolute paths, `file:` URLs, or package exports that resolve to `.wasm`. A
source-phase import gives you the compiled module to instantiate yourself:
```javascript
import source mathModule from "./math.wasm";
const math = await WebAssembly.instantiate(mathModule, {});
console.log(math.exports.add(20, 22));
```
## Supported WebAssembly proposals
Defaults for both commands and JS/TS interop:
| Feature / proposal | Standard distribution | With Python installed |
| --- | --- | --- |
| Mutable globals, sign-extension operators | Enabled | Enabled |
| Non-trapping float-to-integer conversions | Enabled | Enabled |
| Multi-value function and block results | Enabled | Enabled |
| Bulk memory operations and reference types | Enabled | Enabled |
| Multiple memories | Enabled | Enabled |
| Extended constant expressions | Enabled | Enabled |
| Exception handling | Enabled | Enabled |
| Typed function references | Enabled | Enabled |
| Garbage-collected types (WasmGC) | Enabled | Enabled |
| Tail calls | Enabled | Enabled |
| Fixed-width SIMD (`v128`) | Enabled | Disabled |
| Relaxed SIMD | Enabled | Disabled |
Off by default:
| Proposal | Option | Notes |
| --- | --- | --- |
| Memory64 | `wasm.Memory64` | Also requires `wasm.UseUnsafeMemory`. |
| Threads and atomics | `wasm.Threads` | No WASI thread-spawning host API is supplied. |
| Wide integer arithmetic | `wasm.WideArithmetic` | Separate from ordinary `i64` arithmetic. |
| Legacy exception handling | `wasm.LegacyExceptions` | The newer exception-handling proposal is on by default. |
Enable one with `-Xpolyglot.