# Elide documentation

> Elide is a high-performance runtime and toolchain for Kotlin, Java, JavaScript, TypeScript and Python. This file contains every page of https://elide.help in navigation order. Each page starts with its title and URL; the index is https://elide.help/llms.txt.

# Elide Overview

URL: https://elide.help/

> Install Elide, run your first program, and find guides and references for JavaScript, TypeScript, Python, Java, Kotlin and WebAssembly.

Run JavaScript, TypeScript, Python, Java, Kotlin and WebAssembly with Elide. Use its built-in tools to install
dependencies, build projects and run tests.

## Start here

1. [Install Elide](https://elide.help/docs/installation).
2. Pick a first-program guide: [JavaScript and TypeScript](https://elide.help/docs/web), [Python](https://elide.help/docs/python),
   [Java and Kotlin](https://elide.help/docs/jvm), or [WebAssembly](https://elide.help/docs/wasm).

Already have a project? [Choose how to use it with Elide](https://elide.help/docs/getting-started#use-an-existing-project): keep your build
tools, migrate a JVM build, or run scripts from an existing manifest.

## Common commands

```bash
elide run app.ts                 # run a file
elide python script.py           # run Python with CPython-style arguments
elide repl                       # interactive REPL
elide init                       # start a new project from a template
elide adopt                      # migrate an existing project with an AI coding agent
elide install                    # install Maven dependencies
elide install --ecosystems=npm   # install npm dependencies
elide build                      # build the project
elide test                       # run tests
elide format -- src              # format Java and Kotlin sources
elide serve --no-tui ./dist      # serve a directory over HTTP
elide --help-all                 # every command and flag
elide help <topic>               # any page of these docs, in the terminal
```

## Build and integrate

- [Project setup](https://elide.help/docs/projects)
- [Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt)
- [Build an HTTP service](https://elide.help/docs/http-service)
- [IDE integration](https://elide.help/docs/ide)
- [Build tool integration](https://elide.help/docs/build-tools)
- [Work with coding agents](https://elide.help/docs/agentic-engineering)
- [Troubleshooting](https://elide.help/docs/troubleshooting)

## Reference and comparisons

- [Code samples](https://elide.help/docs/code-samples)
- [CLI Reference](https://elide.help/docs/cli-references)
- [Compatibility Matrix](https://elide.help/docs/compatibility)
- [API Overview](https://elide.help/docs/api-overview)
- Coming from another runtime: [Node](https://elide.help/docs/elide-for-node), [Bun](https://elide.help/docs/elide-for-bun), [Deno](https://elide.help/docs/elide-for-deno),
  [Python](https://elide.help/docs/elide-for-python), [Java](https://elide.help/docs/elide-for-java), [Kotlin](https://elide.help/docs/elide-for-kotlin)

## Documentation, even offline

Run `elide help` to browse and search this manual without a network connection.

---

# Installation

URL: https://elide.help/docs/installation

> Install Elide on macOS, Linux, WSL or Windows with the install script, PowerShell or a package manager, pick a release channel, and add Python.

Choose the installer for your operating system. The scripts install the latest release by default; pass
`--channel=nightly` for daily builds. Check [system requirements](#system-requirements) before installing.

Already installed? [Run your first program](https://elide.help/docs/getting-started).

For Python, use the install script with `--with-python`, Homebrew, or a container. The package installers do not
include Python; see [Python](#python).

## macOS, Linux, or WSL

```bash
curl -sSL --tlsv1.2 elide.sh | bash
```

Installs under `${ELIDE_HOME:-${XDG_DATA_HOME:-$HOME/.local/share}/elide}` and adds `bin` to your shell profile.
Pass options after `bash -s --`:

```bash
curl -sSL --tlsv1.2 elide.sh | bash -s -- --channel=nightly --with-python
```

| Option | Effect |
| --- | --- |
| `--channel=release` or `--channel=nightly` | Select the channel (default `release`). |
| `--install-rev=VERSION` | Install a specific version. |
| `--install-dir=PATH` | Install somewhere else. |
| `--with-python` | Also install the Python component. |
| `--libc=glibc` or `--libc=musl` | Pick the Linux `amd64` build (default: detected, see [System requirements](#system-requirements)). |
| `--no-path` | Leave shell profiles unchanged. |
| `--help` | List every option without installing. |

## Windows

Run this in PowerShell. For WSL, use the [Linux command](#macos-linux-or-wsl) inside your WSL terminal.

```powershell
& ([scriptblock]::Create((irm https://elide.sh/install.ps1)))
```

Installs under `$env:ELIDE_HOME`, or `$env:LOCALAPPDATA\elide` when that is unset. Options: `-Channel`,
`-InstallRev`, `-InstallDir`, `-WithPython`, and `-NoPath`.

## Python

Python is an optional component:

```bash
elide setup python
```

| Install method | Python |
| --- | --- |
| Install script | `--with-python` (`-WithPython` on Windows), or `elide setup python` later |
| Homebrew | Included |
| Container images | Included |
| apt, RPM, MSI, macOS installers | Not available; use one of the methods above |

`elide setup python` uses the binary's own channel; `--channel=release` or `--channel=nightly` overrides it.

## Other methods

- [Packages & Installers](https://elide.help/docs/installation/packages): Homebrew, apt, RPM, macOS and Windows installers
- [Container Images](https://elide.help/docs/installation/containers)
- [Continuous Integration](https://elide.help/docs/installation/ci-cd)
- [GitHub Releases](https://github.com/elide-dev/elide/releases): archives, checksums, and older builds. Keep an
  archive's `bin/` and `lib/` together; `bin/elide` needs `lib/`.

Update a script install with `elide upgrade`, and a package-manager install through its manager.

## Verify the install

```bash
elide --version
elide info
```

<img src="https://elide.help/assets/demos/install-verify.gif" alt="Verifying an Elide installation from the command line" width="1591" height="800" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`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`.

**Next: [run your first program](https://elide.help/docs/getting-started)** in JavaScript or TypeScript, Python, or Java and Kotlin.
If Python is missing, follow [the component setup](https://elide.help/docs/troubleshooting#python-is-not-installed).

## System requirements

| Platform | Architecture | Minimum | Python component |
| --- | --- | --- | --- |
| Linux | `amd64` | glibc 2.17, kernel 4.18 | Yes |
| Linux, static musl build | `amd64` | kernel 4.18 | No |
| Linux | `arm64` | glibc 2.17, kernel 4.18 | Yes |
| macOS | Apple Silicon (`arm64`) | macOS 11 | Yes |
| Windows | `amd64` | — | Yes |

- glibc 2.17 covers RHEL and CentOS 7, Amazon Linux 2, Ubuntu 14.04, Debian 8 and later; the kernel must also be
  4.18 or newer.
- The static musl build (`elide.linux-amd64-musl.*` on [GitHub Releases](https://github.com/elide-dev/elide/releases))
  runs on any `amd64` Linux, including Alpine. It runs JavaScript, TypeScript and WebAssembly, and compiles Java and
  Kotlin; it includes no Python and no JDK, so `elide java` runs programs on an installed JDK (`JAVA_HOME` or `java`
  on `PATH`), and `elide native-image` needs an installed `native-image`. The install script picks it on musl hosts;
  `--libc=glibc` or `--libc=musl` overrides the choice.
- On `arm64`, musl is not supported (`exec elide: no such file or directory`); use a
  [container image](https://elide.help/docs/installation/containers) there.
- Intel Macs are not supported.

Check your glibc with:

```bash
ldd --version | head -1
```

---

# Getting started

URL: https://elide.help/docs/getting-started

> Choose a JavaScript, TypeScript, Python, Java, Kotlin or WebAssembly quickstart, or bring an existing project to Elide.

Choose the language you want to use. Each quickstart takes you from installation to a running program and its next
steps.

## Install

[Install Elide](https://elide.help/docs/installation) for your operating system, then open a new terminal and check:

```bash
elide --version
```

If the shell cannot find `elide`, follow [Verify the install](https://elide.help/docs/installation#verify-the-install). Python also needs
the [Python component](https://elide.help/docs/installation#python).

## Run a file

| Language | Start here | You'll do |
| --- | --- | --- |
| JavaScript or TypeScript | [JavaScript and TypeScript quickstart](https://elide.help/docs/web) | Run a file, import an npm package and run a test. |
| Python | [Python quickstart](https://elide.help/docs/python) | Add Python, run a standard-library program and test it with unittest. |
| Java or Kotlin | [Java and Kotlin quickstart](https://elide.help/docs/jvm#run-your-first-program) | Run source, create a project, resolve Maven dependencies and run JUnit tests. |
| WebAssembly | [WebAssembly guide](https://elide.help/docs/wasm) | Run a WASI module or load a module from JavaScript. |

### Executable scripts

To run a file directly from your shell, follow [Executable scripts](https://elide.help/docs/web#executable-scripts).

## Create a project

The language quickstarts above show the files you need. For scripts, workspaces and a shared `elide.pkl` manifest,
continue to [Project setup](https://elide.help/docs/projects).

### Use an existing project

- **Node, Bun or Deno:** check the [Node](https://elide.help/docs/elide-for-node), [Bun](https://elide.help/docs/elide-for-bun) or [Deno](https://elide.help/docs/elide-for-deno) migration
  guide for command changes and API limits before running the app.
- **Java or Kotlin:** [keep Maven, Gradle or Bazel and use Elide's tools](https://elide.help/docs/build-tools), or
  [migrate the build to Elide](https://elide.help/docs/toolchain/usage/adopt).
- **Python:** check [Python compatibility and command changes](https://elide.help/docs/elide-for-python), then
  [run your project's entry point](https://elide.help/docs/python-toolchain#run-project-scripts).

## Add a dependency

Choose the command for your ecosystem: [npm](https://elide.help/docs/web#npm-packages), [Maven](https://elide.help/docs/toolchain/jvm/maven), or
[Python packages](https://elide.help/docs/python-packages). Plain `elide install` installs Maven dependencies; npm requires
`elide install --ecosystems=npm`.

## Test

Use `elide test` for [JavaScript and TypeScript](https://elide.help/docs/web#tests) or [JUnit](https://elide.help/docs/toolchain/testing).
For Python, [run unittest or pytest as a module](https://elide.help/docs/python-testing); `elide test` does not discover Python tests.

## Build

JavaScript, TypeScript and Python source files run directly. For a project with build tasks, `elide build` writes
outputs and build state to `.dev/`. See [Build tasks](https://elide.help/docs/toolchain/build-tasks) and [JVM packaging](https://elide.help/docs/toolchain/jvm/jar).

## Next steps

- [Build an HTTP service](https://elide.help/docs/http-service): a working server and framework compatibility.
- [Code samples](https://elide.help/docs/code-samples): examples with their expected output.
- [Troubleshooting](https://elide.help/docs/troubleshooting): exact error messages and recovery steps.

---

# Adopt an existing project

URL: https://elide.help/docs/toolchain/usage/adopt

> Migrate a Java, Kotlin or Spring Boot project from Maven or Gradle to Elide with `elide adopt`: what it runs, its flags and exit codes, which projects it fits, and a worked example.

`elide adopt` starts an AI coding harness (Codex, Claude Code or OMP) in the current directory with a built-in
migration prompt. The harness reads the build, edits files and runs Elide; Elide edits nothing itself. The prompt
targets Java and Kotlin projects built with Maven or Gradle, especially Spring Boot, and tells the harness to keep any
other languages working.

```shell
elide adopt
```

`elide adopt` migrates the build to `elide.pkl`. To keep Maven, Gradle or Bazel and use Elide's compilers inside them,
see [Build tool integration](https://elide.help/docs/build-tools).

## Which projects it fits

| Project | Fit | Why |
| --- | --- | --- |
| Single-module Java or Kotlin app on Maven or Gradle | Good | Dependencies, source layout, tests and JAR map onto `elide.pkl`. Tested. |
| Spring Boot application or service | Good | The prompt checks the main class, Spring dependencies and plugins, resources, tests and packaging. Tested. |
| A JVM build you want to keep, using Elide only to run and compile | Good | Choose **Existing build**: no `elide.pkl` is required. |
| Multi-module builds | Untested | Elide [workspaces](https://elide.help/docs/elide-pkl-reference#workspaces) exist, but the prompt is not evaluated on them. |
| Heavy custom plugins, generated sources, unusual annotation processing | Poor | The harness keeps Maven or Gradle for steps Elide does not replace; expect a partial migration. |
| Android | Untested | The prompt is not evaluated on Android builds. |
| JavaScript, TypeScript or Python only | Not needed | Elide runs `package.json` scripts, `pyproject.toml` entry points and `node:test` files without a migration; see [Project Setup](https://elide.help/docs/projects). |

### Tested projects

These shapes pass `elide install`, `elide build`, `elide test`, startup and the original build, starting from a fresh
checkout, with the Codex harness:

| Project shape | Existing build | Tested on |
| --- | --- | --- |
| Java, Spring Boot application | Maven | Spring Petclinic: dependencies, resources, tests, runnable app, JAR |
| Java, Spring Boot service | Gradle | Spring REST service: dependencies, resources, tests, HTTP readiness |
| Kotlin/JVM command-line app | Gradle Kotlin DSL | Single module with Kotlin serialization and coroutines |

The Claude Code harness is shown on the Kotlin app in the [worked example](#worked-example).

## Before you start

1. Install and sign in to a harness. Elide runs it from `PATH`:

   | Choice | Executable | Harness |
   | --- | --- | --- |
   | `codex` | `codex` | OpenAI Codex CLI |
   | `claude` | `claude` | Claude Code |
   | `omp` | `omp` | OMP |

2. Commit the project, so the migration is one reviewable diff.
3. Build it once with Maven or Gradle, so there is a known-good baseline.
4. `cd` into the project, or pass `-p DIR`.

## Run interactively

`elide adopt` asks three questions, then starts the harness. Flags answer a question in advance.

| Question | Answers | Flag |
| --- | --- | --- |
| Use elide build with an elide.pkl project manifest? | Yes (default): **Elide build**. No: **Existing build** | `--build elide`, `--build existing` |
| Which AI coding harness should perform the migration? | `codex`, `claude`, `omp` | `--harness` |
| How should the harness approve tool calls? | `auto-approve`, `manual-approve`, `yolo` | `--approval` |

```shell
elide adopt --build elide --harness claude
```

Esc on a question exits `0` without starting the harness. Ctrl+C stops the harness and exits `130`.

### Build strategy

| Strategy | The prompt tells the harness to |
| --- | --- |
| **Elide build** | Write `elide.pkl`: keep `src/main`/`src/test` without declaring source sets, keep dependency versions and scopes, set the Java target and release, define the JAR with its main class. Keep Maven or Gradle until a final `elide install`, `elide build`, `elide test`, `elide run` and the original build all pass. |
| **Existing build** | Keep Maven or Gradle as the build; use Elide's runtime and tools only where they help; not create `elide.pkl` just for `elide build`. |

Both end with a summary of changed files, the validation run, and anything left to do.

### Approval mode

| Mode | Codex | Claude Code | OMP | Use for |
| --- | --- | --- | --- | --- |
| `auto-approve` | `--approve-for-me` | `--permission-mode auto` | `--auto-approve` | A committed worktree you will review. |
| `manual-approve` | (no flag) | `--permission-mode manual` | `--approval-mode=always-ask` | Unfamiliar or sensitive repositories. |
| `yolo` | `--dangerously-bypass-approvals-and-sandbox` | `--permission-mode bypassPermissions` | `--approval-mode=yolo` | Disposable environments without secrets. |

With `auto-approve` or `yolo`, Elide runs the harness in batch mode (`codex exec --skip-git-repo-check`,
`claude --print`, `omp --print`) and shows a progress line; `--log` also streams the harness output. With
`manual-approve`, the harness runs interactively and its output is always shown.

## Run without questions

```shell
elide adopt \
  --build elide \
  --harness codex \
  --approval auto-approve \
  --non-interactive
```

`--non-interactive` requires `--build`, `--harness` and `--approval`; a missing one exits `2`. It refuses
`manual-approve`. Without a terminal, `elide adopt` exits `1` unless `--non-interactive` and all three are given.

## Add guidance

`--prompt-append FILE` adds a UTF-8 file to the end of the prompt under `Additional adoption guidance:`. Repeat it to
add several, in order:

```shell
elide adopt --prompt-append ./adoption-guidance.md --prompt-append ./team-rules.md
```

Use it for facts the harness cannot infer: internal repositories, which build to keep, commands that must keep
working.

## Output and exit codes

The harness's edits are the only output in the project. On the [worked example](#worked-example) that was a new
`elide.pkl` and `.gitignore` entries for `.dev/`. Elide prints `Adoption log: PATH` before starting; the log is kept at
`.dev/logs/adopt-<timestamp>-<pid>.log` in the project.

| Exit code | Meaning |
| --- | --- |
| `0` | The harness exited `0`, or a question was cancelled. |
| `1` | The harness failed (`Error: claude exited unsuccessfully (exit status: 3)`), could not start (`Error: failed to launch codex: No such file or directory`), a `--prompt-append` file is unreadable, or there is no terminal. |
| `2` | A flag is missing or invalid. |
| `130` | Interrupted with Ctrl+C. |

## Validate the migration

Exit `0` means the harness finished, not that the migration is correct. Review the diff: dependency versions, source
and resource directories, entry point, tests and packaging. Then run:

```shell
elide install
elide build
elide test
elide run
```

Run the original Maven or Gradle build too, while it exists. If the result is wrong, revert, add guidance with
`--prompt-append`, and run again.

## Worked example

A single-module Kotlin command-line app built with Gradle Kotlin DSL: Kotlin 2.3.20, JVM 17,
`kotlinx-coroutines-core` 1.10.2, `kotlinx-serialization-json` 1.9.0 and one `kotlin("test")` test. Committed, then:

```shell
elide adopt --build elide --harness claude --approval auto-approve --non-interactive
```

```terminaloutput
Adoption log: /path/to/project/.dev/logs/adopt-1767225600-973648.log
[3m 56s] ✓ Project adopted in 3m 56s
```

The harness added `elide.pkl` and a `.gitignore`, and changed nothing else. The manifest keeps the Gradle versions and
moves the rest into Elide's terms:

```pkl
amends "elide:project.pkl"

import "elide:Jvm.pkl" as Jvm
import "elide:Kotlin.pkl" as Kotlin

name = "kotlinx-cli"
version = "1.0.0"

dependencies {
  maven {
    packages {
      "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2"
      "org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0"
      // Gradle mediates annotations to 23.0.0 (via coroutines); Elide's nearest-wins picks 13.0.
      "org.jetbrains:annotations:23.0.0"
    }
    testPackages {
      // Gradle's `kotlin("test")` with `useJUnitPlatform()` resolves to the JUnit 5 variant.
      "org.jetbrains.kotlin:kotlin-test-junit5:2.3.20"
      // The JUnit launcher; with `testing = false`, Elide does not bundle one.
      "org.junit.platform:junit-platform-console:1.10.1"
    }
  }
}

jvm {
  main = "dev.elide.samples.MainKt"
  target = 17
  features {
    // JUnit comes from testPackages above, as with Gradle's `kotlin("test")`; Elide's bundled JUnit is off.
    testing = false
  }
  java {
    source = 17
    release = 17
  }
}

kotlin {
  // Matches the Kotlin Gradle plugin version in build.gradle.kts.
  toolchain = new Kotlin.ManagedKotlinToolchain {
    version = "2.3.20"
  }
  compilerOptions {
    jvmTarget = 17
  }
  features {
    // KotlinX libraries are declared explicitly above, at the versions Gradle uses; only the
    // serialization compiler plugin (Gradle's `plugin.serialization`) is enabled.
    kotlinx = false
    serialization = true
    coroutines = false
    atomicfu = false
    powerAssert = false
    metro = false
    reflection = false
  }
}

artifacts {
  ["jar"] = new Jvm.Jar {
    name = "kotlinx-cli"
    main = "dev.elide.samples.MainKt"
  }
}
```

Validation from a clean `.dev/`:

```terminaloutput
$ elide install
[504ms] ✓ Resolved 25 Maven dependencies (476ms)
[505ms] ✓ Dependencies installed in 484ms
$ elide test
 1 pass
 0 skip
 0 fail
Ran one test across one file. (0.57s)
$ elide run
[ 16ms] ⇥ Dependencies ready (Up to date)
[ 16ms] ⇥ Kotlin main compilation skipped (Up to date)
[ 16ms] ⇥ Java main compilation skipped (Up to date)
[ 17ms] ⇥ Packaging jar 'jar' skipped (Up to date)
{"completed":["PARSE","EMIT"]}
[138ms] ✓ JVM jar application completed successfully (121ms)
[139ms] ✓ Build successful in 126ms
```

`elide build` produced `.dev/artifacts/jar/kotlinx-cli/kotlinx-cli.jar`, and `gradle build` still passed.

## See also

- [Project Setup](https://elide.help/docs/projects) and the [elide.pkl reference](https://elide.help/docs/elide-pkl-reference)
- [Elide for Java users](https://elide.help/docs/elide-for-java), [Elide for Kotlin users](https://elide.help/docs/elide-for-kotlin)
- [`elide adopt` flags](https://elide.help/docs/cli-references#adopt)

---

# JavaScript and TypeScript with Elide

URL: https://elide.help/docs/web

> Run your first TypeScript program, install and import an npm dependency, and test it with node:test; no compile step or tsconfig.json.

Elide runs JavaScript and TypeScript directly, with CommonJS, ES modules, and a subset of the Node and Web APIs.
This quickstart builds a small greeting program, adds an npm dependency, and tests the greeting.

Bringing an existing app? Start with [Elide for Node users](https://elide.help/docs/elide-for-node) and the
[framework compatibility table](https://elide.help/docs/http-service#frameworks).

## Install

[Install Elide](https://elide.help/docs/installation), open a new terminal, then check:

```bash
elide --version
```

If the command is not found, follow [Verify the install](https://elide.help/docs/installation#verify-the-install).

## Run a file

> [!TIP] TypeScript runs as written
> No compile step and no `tsconfig.json`: `elide app.ts` runs the file.

```bash
mkdir hello-elide
cd hello-elide
```

Save this as `app.ts`:

```ts
const name: string = "Ada";
console.log(`Hello, ${name}!`);
```

```bash
elide run app.ts
```

```terminaloutput
Hello, Ada!
```

You can also use `elide app.ts`. For JavaScript, remove `: string` and save the file as `app.js`.

<img src="https://elide.help/assets/demos/run-ts.gif" alt="Running a TypeScript file directly with Elide" width="1591" height="982" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## npm packages

Create `package.json` in the same directory:

```json
{
  "type": "module",
  "dependencies": { "zod": "3.24.1" }
}
```

Install the dependency:

```bash
elide install --ecosystems=npm
```

Plain `elide install` installs Maven dependencies and skips npm. If an import cannot find its package, check
[Module not found after `elide install`](https://elide.help/docs/troubleshooting#module-not-found-after-elide-install).

Save the greeting logic as `greeting.ts`:

```ts
import { z } from "zod";

const User = z.object({ name: z.string() });

export function greeting(user: unknown): string {
  return `Hello, ${User.parse(user).name}!`;
}
```

Replace `app.ts` with:

```ts
import { greeting } from "./greeting.ts";

console.log(greeting({ name: "Ada" }));
```

```bash
elide run app.ts
```

```terminaloutput
Hello, Ada!
```

This confirms the installed package imports and validates the input.

<img src="https://elide.help/assets/demos/npm-install.gif" alt="Installing npm dependencies and importing them from TypeScript" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

Packages go into `node_modules`. If the project also has Maven dependencies, use `--ecosystems=maven,npm` or
`--workspace`. Lockfiles and options: [NPM Installer](https://elide.help/docs/toolchain/web/npm).

## Tests

Create `greeting.test.ts` beside the other files. `elide test` discovers `*.test.ts` files and runs `node:test` tests:

```ts
import test from "node:test";
import assert from "node:assert";
import { greeting } from "./greeting.ts";

test("greets a named user", () => {
  assert.equal(greeting({ name: "Ada" }), "Hello, Ada!");
});

test("rejects a user without a name", () => {
  assert.throws(() => greeting({}));
});
```

```bash
elide test
```

Both tests should pass. If no tests are found, check the filename and run the command from `hello-elide`.
More discovery rules and runner options: [Testing](https://elide.help/docs/toolchain/testing).

## Servers

Continue with [Build an HTTP service](https://elide.help/docs/http-service) for a complete server you can run and query.
For an existing directory of web files:

```bash
elide serve --no-tui ./dist # static files on 127.0.0.1:8080
elide dev --no-tui ./src    # port 3000; pages reload on change
```

Given a script, `serve` and `dev` run it; a module that exports a `fetch` handler is served directly. See
[Development Server](https://elide.help/docs/dev-server).

## Executable scripts

On macOS and Linux, start a file with `#!/usr/bin/env elide` and mark it executable:

```ts
#!/usr/bin/env elide
const name: string = process.argv[2] ?? "world";
console.log(`Hello, ${name}!`);
```

Save it as `hello.ts`, then run:

```bash
chmod +x hello.ts
./hello.ts Ada
```

The output is `Hello, Ada!`. The same first line works for `.js`, `.mjs` and `.py` files.

## Samples

- [TypeScript without a build](https://elide.help/docs/code-samples#typescript-without-a-build)
- [HTTP handler](https://elide.help/docs/code-samples#http-handler)
- [TypeScript tests](https://elide.help/docs/code-samples#typescript-tests)
- [Local server and fetch](https://elide.help/docs/code-samples#local-server-and-fetch)

## More

Extensions: `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`. JSX and TSX are transformed; install the
runtime they import, such as `react/jsx-runtime`. Elide provides no UI framework or DOM. See
[TypeScript and modules](https://elide.help/docs/typescript-and-modules) for module resolution and type checking.

Implemented Node and Web modules: [API Overview](https://elide.help/docs/api-overview). SQLite, PostgreSQL and MySQL drivers:
[Databases](https://elide.help/docs/api-database). Measured results:
[Compatibility Matrix](https://elide.help/docs/compatibility). Traces, metrics, and logs through `@opentelemetry/api`, with no SDK:
[OpenTelemetry in JavaScript](https://elide.help/docs/opentelemetry/javascript).

---

# Python with Elide

URL: https://elide.help/docs/python

> Add Python to Elide, run a Python 3.13 program with the standard library, and test it with unittest; then add packages or JavaScript interop.

Python support is experimental. This quickstart runs a program using the bundled standard library, then tests it
with unittest. No third-party packages are needed.

> [!TIP] No CPython install
> Elide runs Python 3.13 and its standard library itself.

## Install

[Install Elide](https://elide.help/docs/installation) using a method that [supports Python](https://elide.help/docs/installation#python), then add the Python
component if it is not already included:

```bash
elide setup python
elide info
```

`elide info` should list `python` on its `Languages:` line. If the shell cannot find `elide`, follow
[Verify the install](https://elide.help/docs/installation#verify-the-install). If Python support is missing, see
[Python is not installed](https://elide.help/docs/troubleshooting#python-is-not-installed).

`elide setup python --channel=release` or `--channel=nightly` picks the channel; `--force` reinstalls the component.

## Run Python

Create a directory for this example:

```bash
mkdir hello-python
cd hello-python
```

Save this as `greeting.py`:

```python
import json


def greeting(name: str) -> str:
    return f"Hello, {name}!"


if __name__ == "__main__":
    print(json.dumps({"message": greeting("Ada")}))
```

```bash
elide python greeting.py
```

```terminaloutput
{"message": "Hello, Ada!"}
```

The `json` import uses the standard library included with the Python component.

## Tests

Create `test_greeting.py` in the same directory:

```python
import unittest

from greeting import greeting


class GreetingTest(unittest.TestCase):
    def test_names_the_caller(self):
        self.assertEqual(greeting("Ada"), "Hello, Ada!")
```

Run unittest as a module:

```bash
elide python -m unittest -v test_greeting
```

The runner should report one test and `OK`. If it cannot import `greeting` or `test_greeting`, check the filenames
and run the command from `hello-python`.

`elide test` does not discover Python tests. For discovery across several files or pytest, see
[Python tests](https://elide.help/docs/python-testing).

## Next steps

- [Add packages](https://elide.help/docs/python-packages): install dependencies with the optional Python package tooling, or use a compatible
  external virtual environment.
- [Run a project entry point](https://elide.help/docs/python-toolchain#run-project-scripts): use the scripts in `pyproject.toml`.
- [Call JavaScript from Python](#javascript-interop): share values between languages.
- [Check compatibility](#known-limitations) before moving an existing application.

## Command-line arguments

`elide python` takes Python interpreter arguments before the script or module. For an existing `app.py`:

```bash
elide python app.py --name Elide --count 2   # sys.argv: ['app.py', '--name', 'Elide', '--count', '2']
elide python -c 'import sys; print(sys.version)'
elide python -m json.tool input.json
echo 'print("from stdin")' | elide python -
```

Tokens after the script, `-c CMD`, or `-m MODULE` go to the program. Bare `elide python` starts the REPL in a
terminal and reads standard input otherwise.

<img src="https://elide.help/assets/demos/python-cli.gif" alt="Running a Python program with command-line arguments in Elide" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

The general commands 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

Put these 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. |

Two flags are on by default: `-S`, because Elide builds `sys.path` itself and skips `site` for startup time, and
`-B`. `sys.flags` reports both. To import `site` (`.pth` files, `sitecustomize`), pass
`-X polyglot.python.NoSiteFlag=false`; to write bytecode, pass `-X polyglot.python.DontWriteBytecodeFlag=false`.

## Standard library

The standard library includes `json`, `pathlib`, `sqlite3`, `ssl`, `zlib`, and `ctypes`. `bz2` and `lzma` need no
system `libbz2` or `liblzma`. For the database drivers Elide includes, see [Databases](https://elide.help/docs/api-database).

## 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

Package installation requires pytools, the optional package tooling installed with the Python component. Use
`elide uv install PACKAGE`, or `elide install --ecosystems=pypi` for declared dependencies. Plain `elide install`
retains its Maven default.

Packages installed through Elide use the project's automatic environment. A compatible Python 3.13 external
virtual environment can also supply packages through `VIRTUAL_ENV`.

Only compatible wheels can be installed; source builds and arbitrary CPython native wheels are not supported.
See [Packages and virtual environments](https://elide.help/docs/python-packages) for setup, commands and limitations.

## Tracing and metrics

The `opentelemetry` API and `logging` export traces, metrics, and logs through Elide, with no SDK installed; see
[OpenTelemetry in Python](https://elide.help/docs/opentelemetry/python).

## 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).

## Samples

- [Python calling JavaScript](https://elide.help/docs/code-samples#python-calling-javascript)
- [JavaScript importing Python](https://elide.help/docs/code-samples#javascript-importing-python)
- [Python script](https://elide.help/docs/code-samples#python-script)

---

# Java and Kotlin with Elide

URL: https://elide.help/docs/jvm

> Run Java and Kotlin source files with Elide, use the bundled JDK 25 and Kotlin tools, resolve Maven dependencies, and build and test a project.

Elide compiles, formats, builds, and tests Java (up to JDK 25) and Kotlin (2.5.0-Beta2), and resolves Maven
dependencies.

> [!TIP] No JDK to install
> The JDK and Kotlin tools ship with Elide; no separate JDK, Kotlin compiler or build tool is needed.

## Run your first program

[Install Elide](https://elide.help/docs/installation), then choose a template below. Each creates a new project directory with a program
and a test.

### Kotlin

```bash
mkdir hello-kotlin
cd hello-kotlin
elide init --plain --skip-defaults --skip-run --template ktjvm
elide run
```

Edit `src/main/com/example/Hello.kt`, then run `elide run` again.

### Java

```bash
mkdir hello-java
cd hello-java
elide init --plain --skip-defaults --skip-run --template java
elide run
```

Edit `src/main/com/example/Hello.java`, then run `elide run` again.

Both programs print:

```text
Hello Elide!
```

Run the generated test with `elide test`. To use a library, declare its
[Maven dependency](https://elide.help/docs/toolchain/jvm/maven) in `elide.pkl`, then:

```bash
elide install
elide test
elide run
```

Already have a project? [Keep Maven/Gradle](https://elide.help/docs/build-tools) and use Elide's compiler or JDK, or
[migrate your build](https://elide.help/docs/toolchain/usage/adopt) to `elide.pkl`.

## 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` work like the tools they name. Arguments go 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. |

To migrate a Maven or Gradle project, `elide adopt` runs an AI coding agent; 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
```

<img src="https://elide.help/assets/demos/project-build.gif" alt="Elide projects — build, run, and reuse cached work" width="1591" height="910" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`elide build --inspect` lists the project's tasks. Manifest: [Project setup](https://elide.help/docs/projects). Compiler and packaging
options: [JVM Toolchain](https://elide.help/docs/toolchain/jvm).

## What programs can use

The JDK, the Kotlin standard library, bundled kotlinx libraries, JUnit for tests, and Elide's annotations; there is no
Elide runtime API and no calls into JavaScript or Python. See [JVM APIs](https://elide.help/docs/api-jvm). For a database, add its JDBC driver
as a Maven dependency ([Databases](https://elide.help/docs/api-database#other-languages)); to share a library, see
[Maven publishing](https://elide.help/docs/toolchain/jvm/publishing).

## Tracing and metrics

Java and Kotlin programs that Elide runs get no OpenTelemetry API, agent, or trace context from Elide. Add the
OpenTelemetry Java SDK or agent to the program as on any JVM. `elide build` and `elide test` still export their own
spans; see [OpenTelemetry](https://elide.help/docs/opentelemetry#languages).

## Rewrite and inspect code

For projects with `elide.pkl`, [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) previews and applies Java recipes, and the
[dependency code index](https://elide.help/docs/toolchain/jvm/code-index) finds class origins, inspects members, and queries compiled
Java and Kotlin references. Both are experimental in 1.6.0.

## Samples

- [Java records and streams](https://elide.help/docs/code-samples#java-records-and-streams)
- [Kotlin collections](https://elide.help/docs/code-samples#kotlin-collections)
- [Kotlin tests](https://elide.help/docs/code-samples#kotlin-tests)
- [Kotlin coroutines](https://elide.help/docs/code-samples#kotlin-coroutines)
- [Java with a Maven dependency](https://elide.help/docs/code-samples#java-with-a-maven-dependency)

Start from a template:

```bash
elide init --template java        # Java app with a JUnit test
elide init --template ktjvm       # Kotlin app with a test
elide init --template workspace   # Kotlin library and app in one workspace
```

---

# WebAssembly with Elide

URL: https://elide.help/docs/wasm

> Run WASI command modules with Elide, map host directories, load WebAssembly libraries from JavaScript and TypeScript, and check supported proposals.

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. |

<img src="https://elide.help/assets/demos/wasm.gif" alt="elide app.wasm — WASI commands and WASM libraries from JavaScript" width="1591" height="546" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

To compile Java or Kotlin to WebAssembly, see [WebImage](https://elide.help/docs/toolchain/jvm/webimage); its output needs its JavaScript
loader, not `elide run`. Target guides: [Browser WASM](https://elide.help/docs/toolchain/web/wasm) and [Edge WASM](https://elide.help/docs/toolchain/edge/wasm).

## 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 exported `_start`, or `_main` if `_start` is absent. Load a module with neither from JavaScript.

| 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

Set the module as the entrypoint in `elide.pkl`, then run `elide run`:

```pkl
amends "elide:project.pkl"
name = "wasm-app"
entrypoint { "app.wasm" }
```

See [Project setup](https://elide.help/docs/projects).

## WASI

Commands get WASI 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 see no host directories until you map one:

```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run app.wasm
```

This maps `./data` to the guest directory `work`. Separate mappings with commas: `work::./data,output::./results`.

The sandbox still applies. WASI file opens need 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));
```

Modules loaded from JavaScript do not run `_start` or `_main`. 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 usual permissions.

### 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 paths, `file:` URLs, or package exports that resolve to `.wasm`. A source-phase import returns
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

On by default, for commands and JS/TS interop:

- Mutable globals and sign-extension operators
- Non-trapping float-to-integer conversions
- Multi-value function and block results
- Bulk memory operations and reference types
- Multiple memories
- Extended constant expressions
- Exception handling
- Typed function references
- Garbage-collected types (WasmGC)
- Tail calls
- Fixed-width SIMD (`v128`) and relaxed SIMD, except with Python installed

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.<option>=true`, for example `-Xpolyglot.wasm.WideArithmetic=true`. This does not
supply the host imports a module needs.

## Limits

- **Binary modules only.** No `.wat`, no compiling C or Rust, no WASM REPL.
- **WASI Preview 1 only.** No WASI Preview 2, component model, or `node:wasi`; no general network access.
- **Host imports.** `elide run` supplies only WASI, not browser APIs or Emscripten glue.
- **SIMD with Python.** With Python installed, SIMD modules are rejected. Use an install without Python or a scalar
  build of the module.

## Samples

- [WebAssembly from JavaScript](https://elide.help/docs/code-samples#webassembly-from-javascript)
- [WASI command](https://elide.help/docs/code-samples#wasi-command)

---

# Packages and installers

URL: https://elide.help/docs/installation/packages

> Install Elide with Homebrew, apt, RPM, or the macOS and Windows installers, upgrade through the package manager, and verify checksums and signatures.

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/<version>`, with `/opt/elide/current` and `/usr/bin/elide` pointing at it.

## Fedora and RHEL (RPM)

```bash
sudo dnf install ./elide_<version>_<arch>.rpm
```

Download the RPM for `amd64` or `arm64` from [GitHub Releases](https://github.com/elide-dev/elide/releases); there
is no yum repository. Upgrade by installing a newer RPM.

## Native installers

These links point at the latest `release`; replace `release` with `nightly` in a URL for the latest nightly.

| Platform | Format | Download | Checksum |
| --- | --- | --- | --- |
| macOS `arm64` | PKG | [elide-installer.macos-arm64.pkg](https://elide.zip/artifacts/release/latest/elide-installer.macos-arm64.pkg) | [sha256](https://elide.zip/artifacts/release/latest/elide-installer.macos-arm64.pkg.sha256) |
| macOS `arm64` | DMG | [elide-installer.macos-arm64.dmg](https://elide.zip/artifacts/release/latest/elide-installer.macos-arm64.dmg) | [sha256](https://elide.zip/artifacts/release/latest/elide-installer.macos-arm64.dmg.sha256) |
| Windows `amd64` | MSI | [elide-installer.windows-amd64.msi](https://elide.zip/artifacts/release/latest/elide-installer.windows-amd64.msi) | [sha256](https://elide.zip/artifacts/release/latest/elide-installer.windows-amd64.msi.sha256) |

## Verify a download

Each installer has a SHA-256 checksum (`<file>.sha256`) and a GPG signature (`<file>.asc`). GitHub Releases also
carries a Sigstore bundle (`<file>.bundle`).

With the download and its `.sha256` file in one directory:

```bash
sha256sum -c <file>.sha256        # Linux
shasum -a 256 -c <file>.sha256    # macOS
```

PowerShell:

```powershell
$file = "elide-installer.windows-amd64.msi"
Invoke-WebRequest -Uri "https://elide.zip/artifacts/release/latest/$file" -OutFile $file
Invoke-WebRequest -Uri "https://elide.zip/artifacts/release/latest/$file.sha256" -OutFile "$file.sha256"
$expected = (Get-Content "$file.sha256").Split(" ")[0]
$actual = (Get-FileHash $file -Algorithm SHA256).Hash.ToLower()
if ($expected -eq $actual) { Write-Host "OK" } else { Write-Host "MISMATCH" }
```

Signature:

```bash
curl -fsSL https://keys.elide.dev/gpg.key | gpg --import
curl -LO https://elide.zip/artifacts/release/latest/elide-installer.windows-amd64.msi.asc
gpg --verify elide-installer.windows-amd64.msi.asc elide-installer.windows-amd64.msi
```

A valid signature reports `Good signature from "Elide Releases (Release key, Elide 1.0 and up)
<engineering@elide.dev>"`. GPG warns that the key is not certified until you sign it yourself.

---

# Container images

URL: https://elide.help/docs/installation/containers

> Run Elide with Docker or any OCI runtime from the elide and bash container images for amd64 and arm64, with Python included, using version or dated nightly tags.

Linux images for Docker and other OCI runtimes, on `amd64` and `arm64`, with Python included.

| Image | Entrypoint | Use |
| --- | --- | --- |
| `elide.dev/elide` | `elide` | Run a command directly. |
| `elide.dev/bash` | `bash` | Open a shell with Elide on `PATH`. |

Both are also published as `ghcr.io/elide-dev/elide` and `ghcr.io/elide-dev/bash`.

## Tags

| Tag | Points at |
| --- | --- |
| `1.6.0` | That release. |
| `1.6`, `1` | The newest release in that line. |
| `latest` | The newest release. |
| `nightly` | The newest nightly build. |
| `nightly-<YYYYMMDD>` | The nightly build from that date. |

Pin a version or dated nightly tag for reproducible builds. The
[`elide`](https://github.com/elide-dev/elide/pkgs/container/elide) and
[`bash`](https://github.com/elide-dev/elide/pkgs/container/bash) package pages list every tag.

## Run a command

```bash
docker run --rm elide.dev/elide:1.6.0 --version
docker run --rm -v "$PWD":/work -w /work elide.dev/elide:1.6.0 run app.js   # run in the current directory
```

## Open a shell

```bash
docker run --rm -it elide.dev/bash:1.6.0
```

---

# Continuous integration

URL: https://elide.help/docs/installation/ci-cd

> Install Elide in GitHub Actions with the setup-elide action, pin a release instead of the default nightly channel, and see an example workflow.

The [setup-elide](https://github.com/elide-dev/setup-elide) action installs Elide and adds it to `PATH`. It
defaults to `nightly`; pin a release:

```yaml
- name: Set up Elide
  uses: elide-dev/setup-elide@v4.2.0
  with:
    version: 1.6.0
    channel: release
```

The action's README lists its other inputs and outputs.

## Example workflow

```yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: elide-dev/setup-elide@v4.2.0
        with:
          version: 1.6.0
          channel: release
      - run: elide install --workspace
      - run: elide format --list-files -- --dry-run src
      - run: elide test
```

`elide install --workspace` installs every ecosystem the project declares; plain `elide install` installs Maven
only. The format step fails when a file under `src` needs formatting.

The action does not install Python; add a step for it:

```yaml
- run: elide setup python
```

To trace `elide build` and `elide test` in CI, see [Builds and tests in CI](https://elide.help/docs/opentelemetry/runtime#builds-and-tests-in-ci).

---

# Toolchain

URL: https://elide.help/docs/toolchain

> Run source files directly with Elide, then add an elide.pkl manifest to install dependencies, build, test, format and package a project.

Elide runs source files directly. Add an `elide.pkl` manifest for dependencies, builds, tests and artifacts.

## Start with a source file

The file extension picks the language:

```bash
elide app.js
elide app.ts
elide app.py
```

Explicit forms:

```bash
elide run app.ts
elide python app.py
```

## Common workflows

| Task | Command | Notes |
| --- | --- | --- |
| Run JavaScript or TypeScript | `elide run app.ts` | Types are stripped. |
| Run Python (experimental) | `elide python app.py` | Needs `elide setup python`; see [Python Toolchain](https://elide.help/docs/python-toolchain). |
| Compile Java | `elide javac -- -d out Hello.java` | |
| Compile Kotlin | `elide kotlinc -- -d out Hello.kt` | |
| Compile freestanding C | `elide cc -- -c answer.c -o answer.o` | [Embedded C compiler and linker via LLVM](https://elide.help/docs/toolchain/native/cc); native tools required. |
| Generate Java bindings for C | `elide jextract -- --output generated api.h` | [C header bindings](https://elide.help/docs/toolchain/native/jextract); native tools required. |
| Format Java and Kotlin | `elide format -- src` | `-n` after `--` checks only. |
| Install dependencies | `elide install` | Maven by default; `--ecosystems=npm` for npm. |
| Build a project | `elide build` | Needs `elide.pkl`. |
| Run tests | `elide test` | JVM tests need `elide.pkl`. |
| Rewrite Java (experimental) | `elide rewrite RECIPE --dry-run` | Preview an [OpenRewrite recipe](https://elide.help/docs/toolchain/jvm/rewrite). |
| Inspect dependency code (experimental) | `elide index build --layers=l1,l2,l3` | Build the [code index](https://elide.help/docs/toolchain/jvm/code-index) for type and reference queries. |

<img src="https://elide.help/assets/demos/project-build.gif" alt="Building and running a Kotlin project with Elide" width="1591" height="910" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## Direct tools

Elide's options go before `--`; the wrapped tool's go after:

```bash
elide javac -- -d out Hello.java
elide kotlinc -- -d out Hello.kt
elide jar -- --create --file app.jar -C out .
elide mvn -- package
```

Wrapped tools: `java`, `javac`, `javap`, `jdeps`, `javadoc`, `jar`, `javaformat`, `kotlinc`, `ktfmt`,
`native-image`, `mvn`, `jextract`, `cc`. `elide <tool> --help` shows Elide's options and how to show the tool's own help.

Native tools (`cc` and `jextract`) are included in Elide 1.6.2 on macOS arm64 and
dynamically linked Linux amd64/arm64. They are omitted from Windows, fully static builds and custom builds
using `--no-jvm-toolchain`. See [Embedded C compiler and linker via LLVM](https://elide.help/docs/toolchain/native/cc) for object/IR
output, in-memory JIT linking and platform boundaries. The
[Java compiler](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings) can also generate C bindings during compilation.

To use these from Maven, Gradle or Bazel without an `elide.pkl`, see [Build tool integration](https://elide.help/docs/build-tools).

## Project-aware commands

```pkl
amends "elide:project.pkl"

name = "my-project"
```

```bash
elide install
elide build
elide test
elide run
```

All take `-p PATH` (project directory) and `-f NAME[=VALUE]` ([build flags](https://elide.help/docs/toolchain/build-flags)).
`elide help options` lists every global flag. Next: [Project setup](https://elide.help/docs/projects).

## OpenRewrite (experimental)

Preview and apply Java recipes in a project with `elide.pkl`:

```bash
elide rewrite --list
elide rewrite org.openrewrite.java.RemoveUnusedImports --dry-run
elide rewrite org.openrewrite.java.RemoveUnusedImports
```

See [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) for recipe modules, prefiltering, and experimental compatibility limits.

## Dependency code index (experimental)

Find which dependency defines a type and which compiled local sources use it:

```bash
elide index build --layers=l1,l2,l3
elide index status
elide index used-by java.util.List
```

See [Dependency code index](https://elide.help/docs/toolchain/jvm/code-index) for addresses, class resolution, member queries, and
reference queries over Maven dependencies and local Java and Kotlin classes.

---

# Component versions

URL: https://elide.help/docs/versions

> Versions configured for Elide's bundled compilers, runtime components and optional tools, generated from its dependency and toolchain pins.

<!-- Generated by make docs-sync-versions; edit scripts/component-versions.mts. -->

This table describes the source configuration for Elide **1.6.3**. Custom builds and optional components can differ; check your installed binary below.

This version is in development. Its component pins can change before release.

## Configured components

| Component | Version | Scope |
| --- | --- | --- |
| GraalVM / Truffle | `25.5.5-elide.24` | Runtime libraries and Native Image toolchain; GraalJS, GraalPy and GraalWasm share this fork version. |
| Java / JDK | `25` | Managed JDK major, not an installed patch-version measurement. |
| Kotlin | `2.5.0-Beta2` | Embedded compiler and standard library. |
| LLVM / Clang | `23.x` | Major required by the native toolchain integration; no patch version is inferred. |
| Elide native toolchain | `2026.11.1` | Pinned bundle containing the native compiler, linker and libraries. |
| Pkl | `0.33.0-elide.1-alpha.1` | Embedded configuration evaluator. |
| Maven core | `4.0.0-rc-7` | Embedded Maven libraries. |
| JUnit Jupiter / Platform | `6.1.3` | Default Jupiter and Platform dependencies for JVM tests. |

## Manifest target declarations

These values describe what the manifest schema accepts, not a language-conformance guarantee. The selected compiler determines which targets it can compile. The ECMAScript setting is a schema declaration; it does not establish the running engine's enabled edition. See [Compatibility](https://elide.help/docs/compatibility) for measured API support.

| Setting | Accepted values |
| --- | --- |
| `javascript.ecma` | `2015`–`2025`, `stable`, `latest`; default: `stable` |
| `kotlin.compilerOptions.languageVersion` / `apiVersion` | `latest`, `stable`, `auto`, `1.9`, `2.0`, `2.1`, `2.2`, `2.3`, `2.4`, `2.5`. Other strings are also accepted by the schema. |
| `kotlin.compilerOptions.jvmTarget` | `8`–`29`, `1.8`, `1.9`, `latest`, `stable`, `auto` |

## Check your installation

Use the binary's own reports for its installed languages and exact compiler versions. [Python](https://elide.help/docs/python-toolchain) is optional; [native tools](https://elide.help/docs/toolchain/native/cc) depend on platform and build options.

```bash
elide --version
elide info
elide java -- --version
elide kotlinc -- -version
```

[Download the machine-readable matrix for Elide 1.6.3](https://elide.help/versions/1.6.3.json).

The JSON identifies the Elide version, release status, source locations and a digest of the extracted values. This page does not reconstruct older releases from current pins.

---

# Project setup

URL: https://elide.help/docs/projects

> Set up an Elide project with elide.pkl: `elide init` templates, named scripts, dependencies, workspaces, and pinning the Elide version.

A project is a directory with an `elide.pkl`. Outputs, dependencies, reports and build state go in `.dev/`. Run
commands from the project directory, or pass `-p PATH`.

See [The .dev directory](https://elide.help/docs/toolchain/development-directory) for generated files, workspace paths and cleanup.

```bash
elide init --templates   # android, java, ktjvm, spring, micronaut, web-simple, web-demo, workspace
```

## Create a project without prompts

`elide init` opens an editor in a terminal. In scripts and CI, pass `--plain --skip-defaults`, a template and its
parameters as `name=value`:

```bash
elide init --template java --parameters          # list parameters and blocks
elide init --template java --parameters --json   # the same, as JSON
elide init --plain --skip-defaults --skip-run --template java \
  project_name=greeter package=dev.acme greeting="Hi there" tests=false
```

```text
elide.pkl
src/main/dev/acme/Hello.java
```

| Argument | Effect |
| --- | --- |
| `NAME=VALUE` or `NAME VALUE` | Sets a parameter; omitted parameters take their defaults. |
| `BLOCK=true`, `BLOCK=false` | Turns an optional block on or off: `tests` (test sources), `mcp` (`.mcp.json`). |
| `--skip-run` | Does not run Elide after generating files. |
| `--overwrite` | Replaces existing files. |

| Input | Result |
| --- | --- |
| No terminal, without `--plain --skip-defaults` | Exit `2`: `` `elide init` needs an interactive terminal. `` |
| A value that fails validation | Exit `2`: `Parameter "package" value "1bad" validation failed with error: "Not a valid Java package name."` |
| A block value other than `true`/`false` | Exit `2`: `Could not parse block "tests" value "maybe" as boolean, it must be true or false` |
| An unknown name | Warning `No parameter or block "colour" exists, value "red" will be ignored`; exit `0` |

## Create a JVM project

```pkl
amends "elide:project.pkl"

name = "hello"

jvm {
  main = "sample.HelloKt"
}
```

`src/main/kotlin/sample/Hello.kt`:

```kotlin
package sample

fun main() {
  println("Hello from Kotlin")
}
```

```bash
elide install
elide build
elide run
```

`src/main/kotlin` needs no `sources` block; see [Source Sets](https://elide.help/docs/toolchain/source-sets).

<img src="https://elide.help/assets/demos/project-build.gif" alt="Building and running a Kotlin project with Elide" width="1591" height="910" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`elide build --inspect` lists the tasks and their options; see [Build Tasks](https://elide.help/docs/toolchain/build-tasks).

## Add a script

```pkl
scripts {
  ["greet"] = "echo hello"
}
```

```bash
elide run greet
```

Scripts run under `/bin/sh`. `elide run NAME` picks the first match: a file, then `elide.pkl` scripts, then
`package.json` or `pyproject.toml` scripts, then `node_modules/.bin`.

## Add dependencies

Declare Maven, npm and PyPI packages under `dependencies`; `elide install` resolves Maven and npm packages, not PyPI
([Python packages](https://elide.help/docs/python-packages)). See [Dependencies](https://elide.help/docs/toolchain/dependencies) and the
[reference](https://elide.help/docs/elide-pkl-reference#dependencies).

## Create a workspace

A workspace root lists member projects and builds them as one task graph. `elide init --template workspace` creates
one. See [Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).

## Inspect a project

```bash
elide project info                 # resolved source sets, dependencies, artifacts
elide project advice               # usage advice for coding agents
elide project export               # the resolved manifest as JSON
elide project export --format=pom  # or intellij
elide classpath                    # the main compile classpath, `:`-separated
elide classpath test:runtime       # [<source-set>:]<usage>
```

`-f` flags change the export. Formats: [Project export formats](https://elide.help/docs/cli-references#project-export-formats).
Classpath usages: [Source Sets](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths).

## Pin the Elide version

```bash
elide use 1.6.0               # write .elideversion and install that version
elide use 1.6.0 --no-install  # only write the file
```

`toolchain.engines` in `elide.pkl` lists accepted versions; see [Toolchain](https://elide.help/docs/elide-pkl-reference#toolchain).

---

# The .dev directory

URL: https://elide.help/docs/toolchain/development-directory

> Find project outputs, dependencies, reports and build state in .dev, understand workspace layouts, and clean generated files without losing source inputs.

Elide writes a project's build files under `.dev/`, beside `elide.pkl`. Directories appear when a command needs them;
a project that only runs JavaScript will not have the same files as one that compiles Java and packages a JAR.
Keep source files and persistent configuration outside this directory.

## Find generated files

| Path under `.dev/` | Contents |
| --- | --- |
| `artifacts/` | Packaged outputs, such as JARs in `jar/`, native executables in `native-image/`, and application distributions. |
| `jvm/classes/<source-set>/java/` | Compiled Java classes. |
| `jvm/classes/<source-set>/kotlin/` | Compiled Kotlin classes. |
| `staging/` | Intermediate packaging files and copied JVM resources. |
| `dependencies/m2/` | Resolved Maven artifacts and classpath files. Artifacts normally link to the Maven cache; `elide install --direct` copies them. |
| `dependencies/npm/` | npm installation files. The project's `node_modules` links into this directory. |
| `reports/tests/` | Test reports, grouped by language and source set when reporting is enabled. |
| `reports/coverage/` | Coverage reports when coverage is enabled. |
| `telemetry/` | Local build traces when `ELIDE_BUILD_TELEMETRY` is enabled. |
| `elide.lock.v2.bin` | Portable task fingerprints and resolution state. This is not an ecosystem dependency lockfile. |
| `elide.build.bin` | Machine-local build state. |
| `elide.filehash.bin` | Cached file digests. |

Use [JAR packaging](https://elide.help/docs/toolchain/jvm/jar), [Native Image](https://elide.help/docs/toolchain/jvm/native-image) and
[Testing](https://elide.help/docs/toolchain/testing) for exact output paths. The binary state files are managed by Elide; do not edit them.
The npm lockfile, `aube-lock.yaml`, lives at the project root, outside `.dev/`.

## Workspaces

A workspace shares dependency artifacts and build state in the root project's `.dev/`. Each member keeps compiled
classes, packaged outputs and reports in its own `.dev/`. Maven classpath files also stay per project under
`.dev/dependencies/m2/`, even though the dependency artifacts are shared.

Use `elide classpath` instead of assembling a classpath from directory contents. See
[Source sets](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths) and [Dependencies](https://elide.help/docs/toolchain/dependencies#installed-files).

## Clean and rebuild

```bash
elide build clean
elide install
elide build
```

`clean` removes the selected project's whole `.dev/`, including reports and local state. At a workspace root it
also cleans every member; when a member is selected, it cleans that member. Save reports or packaged outputs you
need before cleaning. Dependencies and outputs are recreated by later commands, which may require network access.

Project cleanup does not clear the user-wide build cache in `~/.elide/cache/entries-v2`; the next build can restore
outputs from that cache. Use `elide build --no-cache` to rebuild without cached task results. See
[Build cache](https://elide.help/docs/toolchain/build-tasks#build-cache) for local and shared cache behavior.

Exclude generated project files from version control:

```gitignore
.dev/
node_modules/
```

Commit the project's manifest, source inputs and applicable dependency lockfiles. Put durable build-extension inputs
outside `.dev/` too, so cleaning cannot remove the files required to reproduce a build.

## Elide source checkouts

The Elide repository's contributor build adds directories such as `.dev/toolchains/`, `.dev/codegen/`,
`.dev/artifacts/dist/` and `.dev/scratch/`. These belong to the repository's `./builder` and `make` workflow; ordinary
application projects do not need them. Adopted contributor worktrees can share toolchains and dependencies through
symlinks, so follow the checkout's build instructions when managing those directories.

---

# Environment and properties

URL: https://elide.help/docs/environment

> Load dotenv files and Java properties, choose configuration files explicitly, control precedence, and decrypt dotenvx-compatible values with separately supplied keys.

Elide loads `.env` files as application environment defaults and `.properties` files as Java system-property defaults.
No application dotenv library is required. Both formats support dotenvx-compatible encrypted values.

> [!NOTE] Available in Elide 1.6.2
> This guide describes the run-context support in Elide 1.6.2.

## Load configuration

Create `.env` in the directory where you invoke Elide:

```dotenv
APP_NAME=greeter
APP_PORT=8080
APP_MESSAGE="Hello from ${APP_NAME}"
```

Create `app.ts`:

```typescript
console.log(process.env.APP_MESSAGE);
console.log(process.env.APP_PORT);
```

```sh
elide run app.ts
```

```text
Hello from greeter
8080
```

An inherited environment variable takes precedence, including an empty value:

```sh
APP_PORT=9090 elide run app.ts
APP_PORT= elide run app.ts
```

The second invocation receives an empty `APP_PORT`, rather than `8080`. Read environment variables through
[`process.env`](https://elide.help/docs/env-variables), Python's `os.environ`, or the environment interface for your language.
Child processes receive the effective environment too. When an environment policy filters inherited variables,
spawned Java processes, project tasks, and Node child processes inherit only the permitted snapshot. Explicit task
or JVM environment entries are applied afterward; an explicit Node child-process `env` map replaces inheritance.
File loading does not grant additional sandbox capabilities
or broaden a manifest's environment access; existing `--allow-env` controls still apply.

## Automatic file discovery

Within each selected directory, Elide reads these files in order:

| Configuration | First | Second, overriding the first |
| --- | --- | --- |
| Environment | `.env` | `.env.local` |
| Java properties | `.properties` | `.properties.local` |

Missing automatic files are ignored. Existing files that cannot be read or parsed cause an error.
The two formats are separate: an environment variable named `app.mode` does not set the Java property `app.mode`.

By default, the launcher checks only the invocation directory. The location of a script does not change that directory.
Running `elide run services/api/app.ts` does not automatically select `services/api/.env`.

With `--project PATH`, Elide selects that project directory, or the parent directory when `PATH` names its manifest.
It first loads enclosing directories that contain `elide.pkl`, from outermost to innermost, then the selected directory.
Within each directory, the local file follows the base file. Later directories override earlier ones.
Arbitrary ancestors, the home directory, and unrelated workspace members do not contribute launcher configuration.

```sh
elide --project services/api run app.ts
```

Project tasks also use their enclosing, workspace, and member environment layers. Select a project explicitly when its
enclosing configuration must be available at startup. See [Project setup](https://elide.help/docs/projects).

Elide does not select `.env.production`, `.env.test`, `.properties.production`, or similar names automatically.
`NODE_ENV`, a named execution profile, and dotenvx profile files do not select configuration files. Choose these files
explicitly.

## Choose files explicitly

`--env-file` replaces automatic dotenv discovery. `--properties-file` independently replaces automatic properties
discovery. Repeat either flag to layer files; later arguments win for duplicate names.
Paths are relative to the invocation directory, including when `--project` is supplied.

```sh
elide --env-file .env --env-file .env.production run app.ts
elide --properties-file config/base.properties --properties-file config/production.properties run Main.java
elide --env-file config/service.env --properties-file config/service.properties run Main.java
```

Explicit files are required: a missing file is an error. Selecting `.env.production` alone does not also load `.env`
or `.env.local`. Include each file you want.

| Flag | Effect |
| --- | --- |
| `--no-env` | Disable dotenv loading. Inherited environment variables remain available. |
| `--no-properties` | Disable properties-file loading. |
| `--no-env --no-properties` | Disable both kinds of file loading. |

```sh
elide --no-env --no-properties run app.ts
```

Combining `--no-env` with `--env-file`, or `--no-properties` with `--properties-file`, is a usage error.
You can disable one format while explicitly selecting files for the other.

Standalone Java source launches also honor explicit file selections, `--no-env`, and `--no-properties`
without rediscovering automatic files.

## Precedence

Environment precedence, from lowest to highest:

1. Selected dotenv files, in discovery or argument order.
2. Inherited process environment, including empty values.
3. Explicit environment assignments for a particular task or child process, within that execution scope.

Java property precedence, from lowest to highest:

1. Selected properties files, in discovery or argument order.
2. Operator-supplied JVM `-D` assignments when Elide is running on an existing JVM.
3. Explicit Elide CLI property assignments, such as `--vm app.mode=production`.

VM-provided property defaults do not count as operator assignments. Applications receive properties before application
initialization. Child Java launches receive application property defaults before their own explicit JVM arguments.
A task with distinct VM properties runs in a separate VM; its properties do not change the build driver's global state.

## Dotenv syntax

Dotenv files support comments, quoted values, multiline values, empty values, and `${NAME}` interpolation.
Single quotes preserve literal content. Double quotes allow interpolation.

```dotenv
# Application defaults
APP_NAME=greeter
APP_MESSAGE="Hello from ${APP_NAME}"
APP_LITERAL='${APP_NAME}'
APP_EMPTY=
APP_MULTILINE="first line
second line"
APP_COMMAND='$(echo hello)'
```

`APP_LITERAL` is the literal string `${APP_NAME}`. `APP_COMMAND` is the literal string `$(echo hello)`;
Elide does not execute shell command substitutions in configuration files.

Interpolation happens while each file is parsed. It can use inherited variables and earlier assignments in that file.
It is not rerun after later files override values. If `.env` defines `APP_NAME=greeter` and
`APP_MESSAGE="Hello from ${APP_NAME}"`, then `.env.local` changes `APP_NAME` to `api`, the message still reads
`Hello from greeter`. Do not rely on interpolation across separate files.

## Java properties

For Java or Kotlin applications, create `.properties`:

```properties
app.name=greeter
app.message=Hello world
app.empty=
app.multiline=first\
  second
app.unicode=\u263A
app.literal=${APP_NAME}
```

Read these with `System.getProperty("app.name")` in Java or Kotlin. For example, save `Main.java`:

```java
class Main {
  public static void main(String[] args) {
    System.out.println(System.getProperty("app.message"));
  }
}
```

```sh
elide run Main.java
elide --vm app.message="Hello from the CLI" run Main.java
```

The first invocation prints `Hello world`; the second prints `Hello from the CLI`.
`app.multiline` is `firstsecond`; `app.unicode` is `☺`; `app.literal` stays `${APP_NAME}`.

Properties use Java syntax: `#` and `!` comments, escaped separators, continuation lines, and `\uXXXX` escapes.
Quotes are part of the value, rather than dotenv quoting. Properties do not interpolate dotenv expressions or execute
commands. For portable non-ASCII content, use Unicode escapes; the properties reader uses Windows-1252 byte decoding.

Property names must be nonempty and contain neither NUL nor `=`. Values may contain `=`, but not NUL.
The `java.*`, `elide*`, and `org.graalvm*` property namespaces are restricted, except `elide.diag.*`.
Encryption does not bypass these restrictions. `polyglot.*` settings follow the engine-option path.
Use CLI VM options for settings such as heap size; a properties file is not a JVM argument file.

When Elide runs on an already-started JVM, file loading supplies environment overlays to applications and child
processes. It does not rewrite that JVM's `System.getenv()` or retroactively change its startup settings.

## Encrypted values

Elide decrypts dotenvx-compatible `encrypted:` values in dotenv files and Java properties. Plaintext and encrypted
values can appear in the same file and follow the same precedence rules. An encrypted value replaced by a later
plaintext value, or by an inherited environment value, does not need a decryption key.

Use a compatible encryption tool to author ciphertext. Elide supplies decryption when loading configuration;
it does not provide an encryption command. For example, with dotenvx installed:

```sh
dotenvx encrypt -f .env.production
elide --env-file .env.production run app.ts
```

Choose dotenvx's local `.env.keys` storage when prompted. Its
[encryption workflow](https://dotenvx.com/docs/custody/env-keys/) keeps ciphertext in the selected dotenv file and
writes the private key to `.env.keys`. For `.env.production`, the key is named `DOTENV_PRIVATE_KEY_PRODUCTION`.
Elide still requires `--env-file .env.production`; the key's suffix does not select the file.

### Supply private keys

Elide accepts inherited `DOTENV_PRIVATE_KEY` and suffixed `DOTENV_PRIVATE_KEY_*` variables, or keys in `.env.keys`
beside selected configuration sources. Environment and properties share the same key lookup.

1. Elide checks `.env.keys` beside selected dotenv sources, then selected properties sources, in source order.
   Each directory is checked once; later key-file assignments replace earlier assignments with the same name.
2. Inherited `DOTENV_PRIVATE_KEY*` assignments override matching names from key files.
3. The available keys are tried against effective encrypted values. A key suffix does not restrict decryption to a
   particular configuration filename.

Key files are read only when an effective encrypted value needs decryption. A plaintext-only run does not require
`.env.keys`. Key lookup does not search arbitrary ancestors or your home directory.

For CI, inject the matching private-key variable through the CI secret store, then run Elide normally:

```sh
# DOTENV_PRIVATE_KEY_PRODUCTION is supplied by the CI environment.
elide --env-file .env.production run app.ts
```

Keep `.env.keys` out of version control, back it up separately, and limit access to the file.
Review configuration before committing it: encryption of some values does not mean every value is encrypted.
Avoid printing application secrets or passing literal private keys in shell commands and logs.

Entries from `.env.keys` are used only for decryption; they are not added to application configuration.
`DOTENV_PUBLIC_KEY*` entries in configuration files are metadata and are omitted from the loaded application values.
Putting `DOTENV_PRIVATE_KEY*` assignments in an application dotenv or properties file is an error.
Inherited private-key variables remain subject to ordinary inherited-environment visibility.

### Encrypted Java properties

A Java property can contain a compatible ciphertext value without quotes:

```properties
app.secret=encrypted:...
```

The ellipsis is a placeholder for actual ciphertext, not a valid encrypted value. Elide parses Java properties first,
then decrypts the decoded value using the same keys as dotenv. Do not assume the dotenvx CLI can parse or rewrite
Java properties files. Decrypted text is used as a value: it is not reparsed as configuration, interpolated, or executed.

## Commands, tests, and errors

Automatic loading applies to `run`, `serve`, `dev`, `install`, `build`, `test`, `project`, `classpath`, `publish`,
`java`, `python`, `repl`, and direct file execution. Help, version, completions, and unrelated administrative commands
skip automatic configuration discovery. Tool commands such as `javac`, `kotlinc`, and `mvn` do not automatically load
these files. Explicit file flags request configuration loading on commands that reach the application launcher.

For reproducible tests, choose files explicitly or disable both formats:

```sh
elide --env-file .env.test --no-properties test
elide --no-env --no-properties test
```

These flags do not clear inherited environment variables. Set or remove those separately in the test runner.
A resolved invocation keeps its configuration snapshot; start a new invocation to pick up changed files or keys.

Unreadable selected files, malformed syntax, forbidden entries, invalid keys, and undecryptable effective values fail
before the relevant application or task executes. Diagnostics report an error category and source path without
printing source lines, values, ciphertext, or private keys. Fix the reported source or explicitly disable its format.
No partially resolved configuration from a failed format is published.

For variables that configure Elide itself, see [Runtime environment variables](https://elide.help/docs/runtime-env-variables).
For flag details, see [CLI reference](https://elide.help/docs/cli-references).

---

# Source sets

URL: https://elide.help/docs/toolchain/source-sets

> How Elide finds a project's sources and resources: the conventional src layout, declaring source sets in elide.pkl, precedence and per-set classpaths.

A source set is a named group of sources and resources. Elide derives compile, test and packaging tasks from each.

## Conventional layout

`main` is in `src/main`, `test` in `src/test`, any other set in `src/<name>`:

| Path | Meaning |
| --- | --- |
| `src/<set>/java`, `/kotlin`, `/js`, `/ts`, `/python` | Sources, one directory per language |
| `src/<set>/resources` | Resources |

- Every language directory that exists is compiled. With none, `src/<set>` itself is the source root.
- `src` is used as `src/main`; `test` or `tests` as `src/test`.
- `main` and `test` exist when their directories do. Other sets must be declared.

This layout needs no `sources` block:

```text
src/main/kotlin/sample/Main.kt
src/main/resources/app.properties
src/test/kotlin/sample/MainTest.kt
```

`elide project info` prints the resolved sets; `(by convention)` marks paths from the layout.

## Declare source sets

```pkl
sources {
  // A glob moves only the sources.
  ["main"] = "lib/**/*.kt"

  // A block sets more properties.
  ["integrationTest"] {
    type = "test"
    paths { "it/**/*.kt" }
  }
}
```

`new Sources.SourceSetSpec { … }` (with `import "elide:Sources.pkl" as Sources`) is the long form of the entry.
Paths are project-relative globs or directories; a directory is walked recursively.

## Precedence

Each declared property replaces the convention for that property only.

| Property | Left out | Declared |
| --- | --- | --- |
| `type` | Inferred from the name | Always used |
| `paths` | The conventional layout for the name | Used verbatim |
| `resources` | `src/<name>/resources`, when present | Used verbatim |
| `dependsOn` | Test and example sets see `main` | Used verbatim; empty means nothing |

| `type` | Inferred from | Behavior |
| --- | --- | --- |
| `test` | `test`, `tests` | Run by `elide test`; resolves `testPackages`. |
| `example` | `example`, `examples` | Production set. |
| `source` | any other name | Production set. |
| `other` | — | Production set. |

Artifacts that name no sources package every production set. A declared set whose paths cover `src/main` or
`src/test` replaces that conventional set, so no file compiles twice.

## Dependencies and classpaths

Production sets resolve `packages`, `modules`, `compileOnly`, `runtimeOnly` and `processors`. Test sets add
`testPackages` and the sets they depend on. A test set with `dependsOn {}` compiles and runs without `main`'s classes
and resources, but still resolves `packages`. See [Dependencies](https://elide.help/docs/toolchain/dependencies#maven-buckets).

```bash
elide classpath                 # main:compile
elide classpath runtime         # main:runtime
elide classpath test:runtime    # [<source-set>:]<usage>
```

`elide classpath` resolves the classpath and prints it on one line, entries separated by `:`. Usages: `compile`,
`runtime`, `processor`, `modules`, `toolchain`, `provided`; anything else exits `2`. Install also writes
`.dev/dependencies/m2/{compile,runtime,test,processors}.classpath`.

For tooling, request several classpaths as JSON in one invocation:

```bash
elide classpath --json main:compile test:compile
```

The result is an object with each requested query as a key and an array of path strings as its value.
Queries resolve independently. With no query, `--json` returns `{"main:compile": [...]}`.

## Resources

On the JVM, resources are on the classpath for runs and tests and are copied into JARs.

```pkl
sources {
  ["main"] {
    resources {
      "assets/banner.txt"
      new {
        from = "config/services"
        into = "META-INF"
      }
    }
  }
}
```

A plain path is copied to the output root. `from` (a directory or file) is copied under `into`:
`config/services/app.Service` becomes `META-INF/services/app.Service`. `into` defaults to the root.

## Artifacts

```pkl
artifacts {
  ["app"] = new Jvm.Jar {}                 // every non-test source set
  ["lib"] = new Jvm.Jar { sources { "api" } }
}
```

Source and Javadoc JARs follow the same rule. A JAR's `resources` add to its sets'. See
[JAR Assembly](https://elide.help/docs/toolchain/jvm/jar).

## Languages

The file extension determines the language: `.java`, `.kt`, `.js`/`.mjs`/`.cjs`/`.jsx`,
`.ts`/`.mts`/`.cts`/`.tsx`, `.py`. A set with Java and Kotlin runs both compilers; a set with neither runs no JVM
compilation. Compiler settings for one set go in the language's block, keyed by the set's name: `jvm.java.sourceSets`
(see [Java Compiler](https://elide.help/docs/toolchain/jvm/javac#build-projects)).
Kotlin scripts (`.kts`) in a set are counted as Kotlin sources but produce no classes and are not type-checked.

---

# Dependencies

URL: https://elide.help/docs/toolchain/dependencies

> Declare Maven, npm and PyPI dependencies in elide.pkl and install Maven and npm packages with `elide install`: ecosystems, options and installed files.

Declare dependencies in `elide.pkl` and install them with `elide install`.

| Ecosystem | Enable with | Read from |
| --- | --- | --- |
| Maven | default | `elide.pkl`, or a `pom.xml` project selected with `-p` |
| npm | `--ecosystems=npm` | `elide.pkl` and `package.json` |
| PyPI | — | `dependencies.pypi` is accepted; `elide install` does not install it |

## Install dependencies

```bash
elide install                         # Maven
elide install --ecosystems=npm        # npm
elide install --ecosystems=maven,npm  # both
elide install --workspace             # every ecosystem the project declares
```

<img src="https://elide.help/assets/demos/install.gif" alt="Installing Maven and npm dependencies explicitly with Elide" width="1591" height="509" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

A `package.json` does not turn on npm; name every ecosystem CI needs. An unknown or unavailable ecosystem is a usage
error.

## Declare dependencies

```pkl
amends "elide:project.pkl"

dependencies {
  maven {
    packages {
      "com.google.guava:guava:33.4.8-jre"
    }
  }
  npm {
    packages { "react@19.0.0" }
    devPackages { "typescript@5.6.2" }
  }
  pypi {
    packages { "requests>=2" }
    optionalPackages { ["dev"] { "pytest>=8" } }
  }
}
```

For a project with only a `pom.xml`, run `elide install -p .`; see [Maven Dependencies](https://elide.help/docs/toolchain/jvm/maven).

### Maven buckets

An entry is `group:artifact:version[:classifier]`, a `MavenPackageSpec`, a local JAR path, or a `project("name")`
reference. Workspace members can omit the version and take the root's
([Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces)). Conflicts resolve nearest-first, as in Maven, unless overridden by `resolutions`.

| Bucket | Applies to |
| --- | --- |
| `packages` | Compile and runtime classpaths of production sets. |
| `devPackages` | Development time only. |
| `modules` | `--module-path` for compiles, runs, tests and native images. |
| `compileOnly` | Compile classpath only. |
| `runtimeOnly` | Runtime classpath only. |
| `processors` | Annotation-processor path; see [Maven Dependencies](https://elide.help/docs/toolchain/jvm/maven#annotation-processors). |
| `testPackages` | Test sets, in addition to their production set's dependencies. |
| `kotlinPlugins` | Kotlin compiler plugins; see [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc). |
| `exclusions` | Removed from resolution and every classpath. |
| `substitutions` | Local files replacing a coordinate on every classpath; see [reference](https://elide.help/docs/elide-pkl-reference#dependencies). |

### Maven version resolutions

Use `resolutions` to select an exact version wherever a module appears in the dependency graph:

```pkl
dependencies {
  maven {
    resolutions {
      ["org.example:library"] = "1.2.3"
    }
  }
}
```

Keys are `group:artifact`; the override applies to direct and transitive requests, including all
classifiers and packaging types, before their POMs are fetched. It does not add a dependency or
restore an excluded dependency. Version ranges, wildcards, `LATEST` and `RELEASE` are rejected.
Workspace members inherit root resolutions and can override them by key. Changing or removing a
resolution causes the dependency graph to be resolved again.

Spring Boot starters:

```pkl
dependencies {
  spring {
    version = "4.0.0"
    starter { "web"; "actuator" }
    testStarter { "test" }
  }
}
```

Each name becomes `org.springframework.boot:spring-boot-starter-<name>:<version>` in `packages` or `testPackages`.
Other Spring artifacts (`spring-boot-devtools`, `org.springframework:*`) go in `maven`; the two merge.
The [Spring Boot guide](https://elide.help/docs/toolchain/jvm/spring) shows a complete manifest for building, testing and packaging an application with Elide.

### Repositories

```pkl
dependencies {
  maven {
    repositories {
      ["company"] = "https://maven.example.com/releases"
      ["private"] {
        url = "https://packages.example.com/maven"
        credentials {
          username = read("env:MAVEN_USER")
          password = read("env:MAVEN_TOKEN")
        }
      }
    }
    localRepository = ".m2/repository"
  }
}
```

| Property | Meaning |
| --- | --- |
| `repositories[name].url` | Repository URL. |
| `repositories[name].credentials.username`, `.password` | Basic authentication. |
| `repositories[name].credentials.ntlmDomain`, `.ntlmWorkstation` | Either one selects NTLM. |
| `repositories[name].name`, `.description` | Display name and description. |
| `enableDefaultRepositories` | Include Maven Central (default `true`). |
| `localRepository` | Local Maven repository to resolve into. |

- Plain `http://` to anything but `127.0.0.0/8` fails with `Maven repository 'name' uses plain HTTP`.
  `elide build deps --allow-http-repositories` accepts it.
- `read("env:…")` needs `--allow-env`; see [Build Flags](https://elide.help/docs/toolchain/build-flags#environment-variables).
- With `enableDefaultRepositories`, Maven artifacts come from the `maven.pkg.st` proxy first, then Maven Central.
  `elide build deps --use-pkgst=false` (or `--no-use-pkgst`) uses Maven Central only; the global `--pkgst` and
  `--no-pkgst` flags do not change this.

## Maven options

| Option | Effect |
| --- | --- |
| `--slim` | Skip sources and Javadoc. |
| `--with=sources` | Also fetch sources; `javadoc` and `docs` work too. Unknown values exit 2. |
| `--direct` | Copy artifacts into the project instead of linking. |
| `--fresh` | Download every dependency again, refreshing the global cache. |

`elide build deps` runs the same resolution as a task and also takes `--offline`, `--allow-http-repositories` and
`--use-pkgst`.

## Installed files

| Path | Contents |
| --- | --- |
| `.dev/dependencies/npm/node_modules` | npm packages; `node_modules` at the project root links here. |
| `aube-lock.yaml` | npm lockfile. |
| `.dev/dependencies/m2` | Links into the standard Maven cache. |
| `.dev/dependencies/m2/{compile,runtime,test,processors}.classpath` | Resolved classpaths; see [`elide classpath`](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths). |

In a workspace, links are in the root's `.dev/dependencies/`; classpath files stay per project. There is no
cross-ecosystem lockfile; see [Build state](https://elide.help/docs/toolchain/build-tasks#build-state).

## Query dependency code

The experimental [dependency code index](https://elide.help/docs/toolchain/jvm/code-index) records types, members, and references from
resolved Maven JARs. Build it with `elide index build --layers=l1,l2,l3`, then use `resolve` to find which artifact
defines a class, `get` to inspect a type or member, and `references` to follow its code references. `used-by` finds
matching compiled local sources.

[OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) uses the same index for Java source transformations. Add recipe modules to
`devPackages`; they are development tools, separate from application dependencies.

## Implicit JVM libraries

- Java-only roots get no implicit Kotlin libraries, Metro runtime or Elide annotation API, even with a `kotlin` block.
- Kotlin roots get the libraries their `kotlin.features` enable.
- Kotlin roots also get the atomicfu runtime unless `kotlin.features.atomicfu = false`.
- Test sets get bundled JUnit unless `jvm.features.testing = false`; `elide test` then needs your own
  `junit-platform-console` for JVM tests.
- `dev.elide:elide-api` and `elide-insight` accept `latest` as a version and resolve to the bundled artifact.
- Bundled libraries link Elide's own JARs, but their sources and Javadoc come from your repositories like any other
  dependency's, so `--with=sources` attaches `kotlin-stdlib` sources too. `elide-api` and `elide-insight` have none.

The full list, with versions: [JVM APIs](https://elide.help/docs/api-jvm#projects). To use [Elide annotations](https://elide.help/docs/api-jvm-annotations) from
Java:

```pkl
dependencies {
  maven {
    compileOnly { "dev.elide:elide-api:1.0.0" }
  }
}
```

npm specifics: [NPM Installer](https://elide.help/docs/toolchain/web/npm).

Studio session defaults also apply to the embedded npm installer: `ELIDE_PKGST=1`
enables the package CDN unless explicitly overridden by CLI flags. Requests to
the HTTPS `npm.pkg.st` origin carry a valid `ELIDE_STUDIO_SESSION_ID` for internal
correlation. Other registries receive no Studio session header. The native
installer retains unchanged package content when dependency versions drift;
Elide's `.dev/dependencies/npm` layout does not require an exact whole-project
input match to reuse those packages.

---

# Build tasks

URL: https://elide.help/docs/toolchain/build-tasks

> How `elide build` derives tasks from an elide.pkl manifest and runs them in dependency order: targets, options, the build cache, build state and timing.

`elide build` derives tasks from the source sets and artifacts in `elide.pkl` and runs them in dependency order.
Tasks with unchanged inputs are skipped or restored from the cache.

## Run a build

```bash
elide build                   # run the default group
elide build compile-java-main # run one task
elide build compile           # run a group
elide build clean             # the clean target
elide build --inspect         # list tasks and their options without running
elide build jvm-test --help   # one task's options and what they mean
elide build --no-cache        # ignore cached results and build state
elide build --offline         # no network: no dependency fetches, no shared cache
elide build --workers=4       # run at most four tasks at once
```

An argument names a task or group; a leading colon (`:compile-java-main`) is optional. A target that matches nothing
fails the build.

| Group | Alias | Tasks |
| --- | --- | --- |
| `default` | — | What a plain `elide build` runs. |
| `dependencies` | `deps` | Dependency resolution and install. |
| `compilation` | `compile` | Source compilation. |
| `testing` | `test` | Tests; also run by `elide test`. |

Some tasks take options, listed by `--inspect`:

```bash
elide build test --select=class:com.example.SomeTest
elide build run --args="a b c"
```

In a [workspace](https://elide.help/docs/elide-pkl-reference#workspaces), prefix the project: `core:compile-kotlin-main`, `core:compile`,
or `core` for its default tasks. Unprefixed targets resolve in the current project, then the root. `--inspect`
groups tasks by project, and progress rows name it (`[core] Compiling Kotlin sources`).

A project can add groups — and tasks — of its own, including tasks that run ahead of the built-in ones: see
[Build extensions](https://elide.help/docs/toolchain/build-extensions).

## Options

Options are `--name` or `--name=value`, anywhere among the targets. Arguments after `--` go to the process a task
launches. `--inspect` lists every task's options; `elide build <task> --help` describes one task's own.

| Option | Effect |
| --- | --- |
| `--inspect`, `-i` | List tasks and their options without running. |
| `--no-cache` | Ignore the cache and local build state; every task runs. |
| `--offline` | No dependency downloads and no shared cache. |
| `--workers=N` | At most `N` concurrent tasks (default: processor count). `=` is required. |
| `--insights=FILE` | Run an [insight script](https://elide.help/docs/api-insight) in tasks that run programs; repeatable. |
| `-f NAME[=VALUE]` | Build flag, read as `build.flags`; see [Build Flags](https://elide.help/docs/toolchain/build-flags). |

Options are checked against the tasks before anything runs. An unknown option, a missing or unexpected value, or a
repeated option fails:

```text
Unknown option '--worker', did you mean '--workers'?
Option '--workers' requires a value, as '--workers=<value>'
```

Global flags (`-p`, `-v`, `--debug` and the rest) are exempt. Task options:
[Dependencies](https://elide.help/docs/toolchain/dependencies#maven-options), [Testing](https://elide.help/docs/toolchain/testing#options).

## Build cache

The **local** tier is always on: `~/.elide/cache/entries-v2`, one directory per key with a record and a tar of the
outputs. Restores are checked against the recorded fingerprint. Entries in an older format miss.

The **shared** tier is an HTTP cache, set up by environment variables:

| Variable | Meaning |
| --- | --- |
| `ELIDE_REMOTE_CACHE` | Endpoint URL. Unset: no shared tier. |
| `ELIDE_REMOTE_CACHE_TOKEN` | Bearer token; takes precedence over basic auth. |
| `ELIDE_REMOTE_CACHE_USERNAME`, `ELIDE_REMOTE_CACHE_PASSWORD` | Basic auth; user info in the URL also works. |
| `ELIDE_REMOTE_CACHE_PUSH` | Upload this build's outputs (default `true`). |
| `ELIDE_REMOTE_CACHE_PULL` | Download misses (default `true`). |
| `ELIDE_REMOTE_CACHE_POLICY` | `eager` (default) transfers every entry; `smart` transfers only when it saves time. |

- Local is checked first; remote hits are stored locally.
- Typical setup: CI pushes; developers set `ELIDE_REMOTE_CACHE_PUSH=false`.
- Unreachable, slow or unreadable remote entries are misses. Three transport failures in a row turn the tier off for
  the rest of the build. HTTP errors such as `404` are not transport failures; a rejected credential warns once.
- The build fails on a non-`http`/`https` URL, a password without a username, a non-boolean `PUSH`/`PULL`, or
  credentials over plain `http` to a non-loopback host.
- The cache serves executable outputs: use `https`, require authentication for writes, and limit who can write.
- `--offline` turns off the shared tier for one run; `--no-cache` turns off caching.

### `.eliderc` and the `smart` policy

Under `smart`, an entry is downloaded only when that is cheaper than rebuilding, and uploaded only when the upload
costs less than the work it saves. Costs come from `.eliderc` (`java.util.Properties` syntax): `~/.eliderc`, then
`<project>/.eliderc` over it. It describes the machine, so do not commit it.

```properties
# ~/.eliderc
network.downlink = 200mbps
network.uplink = 20mbps
network.latency = 250ms
network.stability = good        # good | fair | poor
machine.compute = fast          # slow | normal | fast, or a multiplier such as 1.5

cache.remote.policy = smart     # smart | eager (default)
cache.remote.upload-budget = 2.0
cache.remote.min-build = 500ms  # work cheaper than this is never published
```

`Mb/s` and `mbps` are megabits; `MB/s` is megabytes. Unreadable values warn and use the default.
`ELIDE_REMOTE_CACHE_POLICY` overrides `cache.remote.policy`. Under `eager`, the file has no effect.

## Build state

| File | Role |
| --- | --- |
| `.dev/elide.lock.v2.bin` | Portable per-task fingerprints, shareable across machines. Not a dependency lockfile. |
| `.dev/elide.build.bin` | Machine-local per-task fingerprints. |
| `.dev/elide.filehash.bin` | File digests keyed on size, times, inode and mode, so unchanged files are not re-read. |

- Binary files; do not edit.
- There is no dependency lockfile for every ecosystem; npm writes `aube-lock.yaml`.
- In a workspace, state is stored in the root's `.dev/` for every member; outputs stay in each project's `.dev/`.
- `--no-cache` ignores the local state file but still reads the shared one.
- `elide install` reuses resolution while the dependency list is unchanged; `--fresh` downloads every dependency
  again, refreshing the global cache.
- Each compiler's arguments are written beside its output as `<tool>.args`, one per line.

See [The .dev directory](https://elide.help/docs/toolchain/development-directory) for generated files, workspace paths and cleanup.

## Time a build

Each task prints its duration. For more:

```bash
elide build -v                                                # everything, at debug
ELIDE_LOG=dev.elide.tooling.build.telemetry=debug elide build # only the timings
```

```text
[debug] dev.elide.tooling.build.telemetry stage graph took 590us
[debug] dev.elide.tooling.build.telemetry op compile-kotlin-main · up-to-date (up-to-date) took 420us
[debug] dev.elide.tooling.build.telemetry task compile-kotlin-main (skipped: up-to-date) took 12.6ms
```

Regions are a **stage** (configuration, graph, execution, state save), a **task**, or an **operation** on a task
(`prepare`, `fingerprint`, `up-to-date`, `execute`, cache lookups and stores). Work inside `execute` is not split
out.

`ELIDE_BUILD_TELEMETRY` writes a local [Chrome trace](https://perfetto.dev/docs/visualization/large-traces) when
the build ends; nothing is uploaded:

```bash
ELIDE_BUILD_TELEMETRY=1 elide build             # .dev/telemetry/build-<stamp>.trace.json
ELIDE_BUILD_TELEMETRY=profile.json elide build  # a file you name
ELIDE_BUILD_TELEMETRY=/tmp/traces elide build   # a directory you name
```

Open it in [Perfetto](https://ui.perfetto.dev), `chrome://tracing` or [speedscope](https://speedscope.app), or:

```bash
jq -r '.traceEvents[] | select(.ph=="X") | "\(.dur/1000 | floor)ms \(.cat) \(.name)"' \
  .dev/telemetry/build-*.trace.json | sort -rn | head
```

### Restore observations and session correlation

Servers supporting Elide restore receipts may return `x-elide-recall-receipt`
when an archive download requests `x-elide-recall: 1`. The client reports the
outcome to `outcomes` beneath the configured cache endpoint after extraction
and validation. Downloading bytes alone does not count as a successful restore;
subsequent local hits do not duplicate remote observations. Reporting is best
effort and does not decide whether a build succeeds.

`ELIDE_STUDIO_SESSION_ID` supplies bounded request correlation metadata to the
configured build-cache endpoint and the HTTPS Maven Pkgst origin. It is not a
credential and does not change action keys. Authenticated or session-correlated
build-cache requests do not follow redirects, preventing metadata leakage to
another origin.

Restore reports include the original task duration as a bounded estimate, so a
server can compare likely rebuild cost with measured restore cost. That estimate
is not a billing measurement or proof of time saved.

---

# Build extensions

URL: https://elide.help/docs/toolchain/build-extensions

> Declare your own build tasks in JavaScript or TypeScript

Elide embeds a compiler, a Maven resolver, a container assembler and a test runner. It does not embed `protoc`, `shellcheck`, or whatever your project needs next. A **build extension** is how you teach your build about one — as a JavaScript or TypeScript module Elide evaluates while it configures the build.

An extension declares tasks. Each one becomes a real task in the graph: you can name it as a build target, depend on it from another task, put it in a group, and see it in `elide build --inspect`.

## Declaring an extension

List it in your manifest, relative to the project root:

```pkl
amends "elide:project.pkl"

name = "demo"

extensions {
  "tools/protoc.ts"
}
```

Extensions are declared, never discovered, so running one is always something your project asked for. A path that does not exist fails the build rather than quietly registering nothing.

A path is resolved against your project root and has to stay inside your source tree — your project root, or the workspace root when your project is a member of one, so members can share a file above their own roots (`../tools/protoc.ts`). An absolute path outside the tree, a path that climbs out of it, and a symlink that points out of it are all refused, each reported like any other bad declaration.

A declaration names one of two things, and Elide decides which from the file extension alone: an ES module — `.ts`, `.mts`, `.js`, `.mjs`, `.jsx`, `.tsx` — or a `.elx` package archive (see [Packaging an extension](#packaging-an-extension)). `.cjs` is not accepted: the contract is a default export, which a CommonJS script cannot declare, and a `.js` extension is always read as a module whatever the nearest `package.json` says. Anything else fails the build rather than being guessed at.

An entry does not have to be a path at all: it may name a package to download from a URL, npm or Maven. See [Fetching an extension](#fetching-an-extension).

## Writing one

```ts
export default ({ task }: ElideBuild) => {
  task(
    "protoc",
    {
      description: "Generate protobuf sources",
      group: "compile",
      inputs: ["proto/**/*.proto"],
      outputs: ["src/main/generated"],
    },
    (ctx) => {
      const result = ctx.exec("protoc", [
        `--kotlin_out=${ctx.layout.projectDir}/src/main/generated`,
        "proto/api.proto",
      ]);
      if (!result.ok) ctx.fail(result.stderr);
    },
  );
};
```

Then:

```bash
elide build --inspect   # protoc  Generate protobuf sources
elide build protoc      # run just that task
elide build compile     # run it with everything else in its group
```

Types ship in [`@elide-dev/types`](https://www.npmjs.com/package/@elide-dev/types) as `ElideBuild`, `ElideBuildTaskContext` and `ElideBuildTaskOptions`.

Your module's default export runs while the build is being configured, and may be `async`. Each task's action runs when the task does, and may also be `async`; the build waits for either.

## Packaging an extension

An extension that outgrows a single file ships as an archive: a zip with a manifest named `extension.json` at its root, named `.elx`. The name is not decoration — the declaration's file extension is what tells Elide it has a package, and `.elx` is the only one that does, so `tools/protoc.elx` loads and the same bytes named `tools/protoc.zip` do not.

```
protoc-tasks/
├── extension.json
├── tasks.ts
└── lib/
    └── flags.ts
```

```json
{
  "name": "protoc-tasks",
  "version": "1.0.0",
  "description": "Generates sources with protoc",
  "license": "Apache-2.0",
  "repository": "https://github.com/example/protoc-tasks",
  "homepage": "https://example.dev/protoc-tasks",
  "authors": ["Example Inc."],
  "type": "source",
  "entrypoint": "tasks.ts"
}
```

The archive's manifest requires `name` and `type`. `type` is `source` — the one kind there is — and a `source` package must also name an `entrypoint`, a path relative to the archive root; one that points outside the archive is rejected. Everything else is metadata Elide reports back to you, and keys it does not know are ignored, so a package may carry keys of its own.

### Building the package

Declare the package as an artifact and `elide build` produces it:

```pkl
amends "elide:project.pkl"

import "elide:Extensions.pkl" as Extensions

name = "protoc-tasks"
version = "1.0.0"
description = "Generates sources with protoc"

artifacts {
  ["tasks"] = new Extensions.ExtensionArchive {
    entrypoint = "tasks.ts"
    srcs { "lib/**/*.ts" }
    license = "Apache-2.0"
    repository = "https://github.com/example/protoc-tasks"
    authors { "Example Inc." }
  }
}
```

That registers a task named `package-extension-tasks`, run by a plain `elide build`, which writes `.dev/artifacts/tasks.elx`. The `extension.json` above is written for you: `name`, `version` and `description` fall back to the project's own, and `type` is always `source`.

`entrypoint` is the module whose default export declares your tasks. `srcs` are the modules it imports, as paths or glob patterns relative to the project root; the entrypoint itself is always packaged. Files keep the paths they have in your project, so relative imports resolve inside the archive exactly as they do in your checkout. Every packaged file must be inside the project once its links are resolved: a symlink pointing out of the project fails the build rather than shipping what it points at.

You can of course still build the zip yourself, from the directory holding the manifest, so that `extension.json` lands at the root:

```bash
cd protoc-tasks && zip -r ../tools/protoc.elx .
```

### A source package

`"type": "source"` means the archive carries your source, and the entrypoint's file extension decides how it is loaded — exactly as it does for a file you declare directly. A `.ts`, `.tsx`, `.mts`, `.js`, `.jsx` or `.mjs` entrypoint is evaluated as a guest module, and because Elide unpacks the archive before evaluating it, relative imports inside the package (`import { flags } from "./lib/flags.ts"`) resolve.

Nothing is bundled or compiled on the way in: a package ships the sources you wrote, and you write the same extension whether it travels as one file or as an archive — the same default export, the same `task(...)`, the same `ctx`.

### Declaring a package

Like a local extension — a path, with settings if it takes them — or as something to fetch:

```pkl
extensions {
  "tools/shellcheck.elx"
  new {
    from = "tools/protoc.elx"
    config { greeting = "hei" }
  }
}
```

Elide unpacks the archive under your build directory, in `.dev/extensions/packages/<archive>-<hash>/contents/`, and unpacks it again whenever the archive changes. An entry that would be written outside that directory is rejected rather than unpacked.

### What `--inspect` reports

`elide build --inspect` prints an `Extensions:` section covering everything your manifest declared. For each one it shows the declaration you wrote, the package's name and version, its description, what kind of extension it is — `JavaScript/TypeScript module` or `packaged extension` — its license, its repository, and the names of the tasks it declared.

```
Extensions:
  tools/protoc.elx   protoc-tasks 1.0.0
    Generates sources with protoc
    packaged extension · Apache-2.0 · https://github.com/example/protoc-tasks · Example Inc.
    tasks: protoc-generate, protoc-clean
```

Distributing the archive is up to you: attach it to a release, serve it from a URL, publish it as an npm package with whatever you already use. However it travels, a project consumes it the same way — see [Fetching an extension](#fetching-an-extension).

## Fetching an extension

An extension does not have to live in your project. A declaration that opens with one of three reserved schemes names something to download:

```pkl
extensions {
  "url:https://downloads.example.com/protoc-tasks-1.4.0.elx"
  "npm:@acme/protoc-tasks@1.4.0"
  "maven:com.acme:protoc-tasks:elx:1.4.0"
  new {
    from = "npm:@acme/codegen@2.0.1"
    config { proto = "src/proto" }
  }
}
```

Only `url:`, `npm:` and `maven:` are reserved. Everything else is a path, so `C:\tools\ext.ts` still means what it says, and a scheme Elide adds later cannot change how a manifest that already builds is read.

Past the download nothing is different. A fetched `.elx` loads as a package and a fetched `.ts` as a guest module — what it resolved to decides, not how it arrived. A `url:` must be an absolute `https` URL; cleartext `http` is refused except to a loopback host, which is there so you can test against something local. Redirects are followed — up to five hops — and every hop is held to that same rule, so a redirect cannot carry a loopback fetch out to another machine in cleartext.

### Versions are pinned

A remote version names exactly one release. `npm:tasks` and `maven:com.acme:tasks` are rejected by the manifest schema for naming none; `npm:tasks@^1.2`, `npm:tasks@latest` and `maven:com.acme:tasks:1.2.3-SNAPSHOT` are rejected for naming more than one.

That is the cache's doing. A fetched extension is stored under what you declared, so a moving version would either cost a registry round trip on every build — making `--offline` impossible — or silently freeze at whatever your first build happened to see.

### Where it is cached

Fetched artifacts land in `.dev/dependencies/extensions/remote/`, beside your resolved Maven repository and shared by a whole workspace the same way. Because the declaration is pinned, what is cached is never stale: only the first build reaches the network, and `elide build --offline` works from then on. A declaration that has not been fetched and cannot be fetched says so:

```
Build extension 'npm:@acme/protoc-tasks@1.4.0' has not been downloaded, and --offline forbids fetching it
Run the build once without --offline to populate the cache.
```

Whatever digest the source publishes is checked: npm's `dist.integrity` or `dist.shasum`, and Maven's `.sha1` sidecar. A repository that serves an artifact but no digest is fine; one that serves both and disagrees with itself fails the build.

### Pinning the bytes

A version pin says which release runs; an `integrity` pin says which bytes. Spell it as Subresource Integrity — `sha256-<base64>` or `sha512-<base64>` — beside the source it belongs to:

```pkl
extensions {
  new {
    from = "url:https://downloads.example.com/protoc-tasks-1.4.0.elx"
    integrity = "sha512-Ln7jRoUMYMK7TBZ0bNyPmrHDCgAsQ3bIt5nZeUuzpuGqBbw1zYWTPdA2tRbClC2CoRP3UExpHnCw+5kZLgP0lQ=="
  }
}
```

A `url:` is trusted on TLS and its host alone, so a pin is what makes it reproducible. It is checked before the download is cached and again on every cache hit, and an npm package runs from a tree extracted out of those same verified bytes, so neither the server nor the workspace's shared cache can change what runs behind your back. A cached file that no longer matches the pin is downloaded again and replaced; under `--offline` the build fails instead, naming the cached file. A pin stacks with whatever the registry publishes rather than replacing it: an npm or Maven digest is still checked.

Only a fetched source takes one. Pinning a path under your project is rejected — its bytes are already whatever your tree holds.

A download is bounded in size and in time: a response over 64 MiB fails, and so does a host that answers and then stalls, rather than hanging your configuration.

### npm packages

The tarball is cached once for the workspace and extracted into your project's build directory, under `.dev/extensions/npm/<name>/<version>/contents/`, and loaded from its entrypoint: the one `extension.json` names if the package ships one, otherwise `package.json`'s `main`, otherwise `index.js`. A package carrying an `extension.json` is a package in the full sense, read exactly as a `.elx` is — one that is invalid, or names a `type` this Elide does not know, fails the build rather than falling back to `main`.

Resolution walks three steps, in order: `dependencies.npm.registry` when your manifest sets one, then `$ELIDE_PKGST_NPM_ENDPOINT` — the same variable Elide's own npm resolver reads — and failing both, Elide's `npm.pkg.st` proxy, or the public registry at `registry.npmjs.org` when you pass `--use-pkgst=false`.

```pkl
dependencies {
  npm {
    registry = "https://npm.internal.example.com"
  }
}
```

### Maven artifacts

The coordinate is fetched from the repositories you already declare — `dependencies.maven.repositories`, plus Elide's proxy and Maven Central unless `enableDefaultRepositories` is off — using the credentials those repositories carry. Credentials go only to the repository's own scheme, host and port; a redirect anywhere else is followed without them. The usual `[:packaging[:classifier]]` sits between artifact and version, and a coordinate that names no packaging takes `elx`: `maven:com.acme:tasks:1.4.0` fetches `tasks-1.4.0.elx`, the same as `maven:com.acme:tasks:elx:1.4.0`. A packaging Elide cannot load (`maven:com.acme:tasks:zip:1.4.0`) is rejected as any unloadable declaration is.

Repositories are tried in order. One that answers with an error, a response that is too large or stalls, or a redirect that is refused is passed over for the next; a `.sha1` it publishes that disagrees with the artifact fails the build.

One artifact is fetched, and no dependency graph is resolved, exactly as for an archive you declare by path. An extension that needs libraries ships them inside its package.

## Configuring an extension

An extension that takes settings is declared as a block rather than a bare path, and carries them with it. Elide does not interpret them:

```pkl
extensions {
  "tools/shellcheck.ts"
  new {
    from = "tools/protoc.ts"
    config {
      version = "25.1"
      plugins = new Listing { "grpc" }
    }
  }
}
```

That block reaches that extension — and only that extension — as `config`, while it declares tasks and while they run:

```ts
export default ({ task, config }: ElideBuild) => {
  task("protoc", { description: `protoc ${config.version}` }, (ctx) => {
    const { version, plugins } = ctx.config;
  });
};
```

An extension you declared as a bare path reads an empty `config`, so checking a setting is `undefined` is all a default takes.

An extension that wants its settings typed and documented ships a Pkl module of its own, which your project copies in, imports and fills in. A manifest imports local files, the Pkl standard library and Elide's own schema — never a `package://` or other network URI — so the module lives in your project:

```pkl
import "tools/Protoc.pkl"

extensions {
  new {
    from = "tools/protoc.ts"
    config = new Protoc.Settings { version = "25.1" }
  }
}
```

Entries are distinct by path however you write them, so the same extension cannot be declared — or configured — twice.

Write a list inside a block as a `Listing` (or `List("grpc")`). Inline elements — `plugins { "grpc" }` — would reach your extension keyed by position rather than as a list, so the manifest rejects them and tells you the spelling that works.

Settings are data. A value may be a string, a boolean, a number, a `Duration`, a `DataSize` (which reaches your extension as a byte count) or a `Regex`, or a block, `Listing`, `List`, `Set`, `Map` or `Pair` of those. A `Bytes`, a class, a type alias or a function is a manifest error naming where it sits, such as `config.flags.blob`.

## Task options

| Option        | Meaning                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| `description` | Shown by `elide build --inspect`.                                                                      |
| `dependsOn`   | Task names that must complete first; a single name may be given without an array.                      |
| `before`      | Tasks this one must precede: a task name, or `deps`/`compile`/`test` for every task in that group.     |
| `group`       | `deps`, `compile` or `test` to join a built-in group; any other name mints one of your own.            |
| `default`     | Whether a bare `elide build` runs this task. Defaults to `true`.                                       |
| `inputs`      | Project-relative paths or globs whose contents decide whether the task re-runs.                        |
| `outputs`     | Project-relative paths or globs the task writes.                                                       |
| `cache`       | Whether the build cache may archive this task's outputs. Defaults to `true`.                            |
| `options`     | Command-line flags this task accepts (see below).                                                      |

`inputs` and `outputs` are one contract: declare both and Elide skips the task when nothing changed (see [Build Tasks](https://elide.help/docs/toolchain/build-tasks)); declare one or neither and it runs every build. Your extension counts as an input too — the file itself and every module it imports by relative path — so editing the entrypoint or one of its helpers re-runs the tasks it declares.

A task that declared both is also cached like Elide's own: its outputs are archived when it succeeds and restored on any later build whose inputs fingerprint the same, including in a fresh checkout. Set `cache: false` to keep the up-to-date check and skip the archive — the right call when your outputs depend on something your `inputs` do not name.

What a declaration stamps as is hashed from the mode and contents of every file it names, and your action reads the same files and the same stamps through `ctx.inputs` and `ctx.outputs` — see [The files a declaration names](#the-files-a-declaration-names).

## Flags your task accepts

A task that reads a flag should say so. Declared flags are printed by `elide build --inspect` and by `elide build <task> --help`, and checked before anything runs — so a misspelling is reported rather than silently dropped:

```ts
task(
  "publish",
  {
    options: [
      { name: "channel", description: "Channel to publish to", arity: "required" },
      { name: "tag", description: "Extra tag to push", arity: "required", repeatable: true },
      { name: "sign", description: "Sign the release", negatable: true, default: "true" },
    ],
  },
  (ctx) => {
    ctx.option("channel"); // first value, or the declared default
    ctx.values("tag"); // every value, in command-line order
    ctx.flag("sign"); // `--no-sign` reads false; absent reads the default
  },
);
```

| Field         | Meaning                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `name`        | The flag, without dashes and in kebab-case: `"dry-run"` is `--dry-run`.                                  |
| `description` | Shown by `--inspect` and `--help`.                                                                       |
| `arity`       | `"none"` is a bare flag, `"required"` needs `--flag=value`, `"optional"` takes either. Defaults to `"none"`. |
| `repeatable`  | Whether the flag may be passed more than once. Defaults to `false`.                                      |
| `negatable`   | Whether `--no-<name>` is accepted, reading as `"false"`. Defaults to `false`.                             |
| `default`     | What a read falls back to when the flag was not passed.                                                  |
| `keyed`       | Whether what the flag was passed decides what the task produces. Defaults to `true`.                     |

`--inspect` and `--help` print the declaration as it has to be typed, so the three above read `--channel=<value>`, `--tag=<value> (repeatable)` and `--sign (or --no-sign) [default: true]`.

A flag nothing declares fails the build, with the closest declared name when there is one; so does a value given to a bare flag, a required flag left bare, and a repeat of a flag that takes one value. Elide's own flags — `--verbose`, `--project`, `--offline` and the rest — are always accepted.

`ctx.option`, `ctx.flag` and `ctx.values` read through the declaration, which is what makes `--no-sign` and a default readable at all: neither is anything a command line says on its own. A name your task did not declare still reads from the command line as parsed.

A declared flag is part of what decides whether your task re-runs: the values it resolved to are recorded alongside your `inputs`, so a build under `--channel=stable` is never reported up to date — nor handed what `--channel=canary` cached — for one that ran under the other. Set `keyed: false` on a flag that changes how loudly the task talks rather than what it writes, or every build that spells it differently misses the cache for nothing. A flag your action reads without declaring decides nothing at all.

## Running before another task

`dependsOn` names what has to run first. `before` names what has to wait — including tasks you did not declare, which is what a codegen task needs:

```ts
task(
  "generate-sources",
  { before: "compile", default: false, outputs: ["src/main/generated"] },
  (ctx) => { ... },
);
```

`compile`, `deps` and `test` stand for every task in that group, which is what "before compilation" has to mean: the real keys are per-language and per-source-set (`compile-kotlin-main`, `compile-java-test`). Any other name is a single task's, and a name nothing registered fails the build instead of quietly running nothing. In a workspace, an extension a member declares selects only that member's tasks, while one the root manifest declares selects the group across every member.

An edge like this also pulls your task into any build that runs the task it precedes — `elide build compile` above runs `generate-sources` first, even though it opted out of `default`.

## Incremental builds

A running task is told what the build found stale, and can keep values for its next run:

```ts
task("codegen", { inputs: ["proto", "schema"], outputs: ["gen"] }, (ctx) => {
  for (const input of ctx.dirty.inputs) ctx.log(`changed: ${input}`);
  if (ctx.dirty.outputs.length) ctx.log("an output is missing or was edited");
  if (ctx.dirty.extension) ctx.log("this extension or one of its imports changed");

  ctx.log(`last built version ${ctx.state.get("version") ?? "(never)"}`);
  ctx.state.set("version", ctx.manifest.version);
});
```

`ctx.dirty` names only the declarations that changed; on a first run, everything you declared is listed. `ctx.state` holds strings, numbers, booleans, `null`, arrays and plain objects, keyed by name, and `get` answers `null` for a key nothing stored. A function, a symbol and `undefined` have no stored form, and a value that contains itself is refused rather than followed. A run that fails discards the task's state entirely, including what earlier runs recorded.

What a task remembers is a memo, not an input: it never decides whether the task re-runs, and it never moves the task's cache key.

## The files a declaration names

`ctx.inputs` and `ctx.outputs` are the declarations themselves, resolved and stamped — the same walk and the same digest the build ran to decide whether your task was up to date:

```ts
task("codegen", { inputs: ["proto"], outputs: ["gen"] }, (ctx) => {
  for (const file of ctx.inputs.files()) {
    ctx.log(`${file.path} ${file.size}b ${file.stamp}`);
  }

  const before = ctx.state.get("proto") ?? {};
  const after = Object.fromEntries(ctx.inputs.files().map((f) => [f.path, f.stamp]));
  for (const path of Object.keys(after)) {
    if (after[path] !== before[path]) ctx.exec("protoc", ["--kotlin_out=gen", path]);
  }
  ctx.state.set("proto", after);

  ctx.log(`produced ${ctx.outputs.stamp()}`);
});
```

`files()` lists every regular file the declarations name, project-relative and `/`-separated, sorted and without duplicates. Each entry carries `path`, `absolute`, `size`, `modified` and `stamp` — a SHA-256 over that file's mode and contents. `stamp()` is the digest over the whole set.

Both take patterns of their own, which need not be ones you declared: `ctx.inputs.files("proto/api/**/*.proto")` narrows a listing, and `ctx.inputs.stamp("proto")` is exactly the fingerprint the build recorded for that declaration. Both resolve when you call them, so reading `ctx.outputs` after writing your outputs describes what you just produced.

Stamps are content-addressed: an edit that leaves a file's size and modification time alone still changes them, and still re-runs your task. `ctx.dirty` names a declaration as a whole; a per-file stamp kept in `ctx.state`, as above, is how a task tells which of its files moved.

## Declarations the build has to compute

Some of what decides whether a task is current cannot be written in the declaration: a generated tree, a classpath another task resolved, the version of the tool you are about to run. Give the task a `prepare` hook and declare it there:

```ts
task(
  "package",
  {
    outputs: ["dist"],
    prepare: (ctx) => {
      ctx.inputs.add("gen/**/*.kt");
      ctx.inputs.value("classpath", ctx.state.of("resolve")?.get("classpath"));
      ctx.outputs.add(`dist/${ctx.manifest.version}.tgz`);
    },
  },
  (ctx) => {
    for (const changed of ctx.dirty.values) ctx.log(`${changed} changed`);
  },
);
```

What a hook adds is a declaration like any other: a pattern is stamped, named by `ctx.dirty.inputs` and hashed into the task's cache key exactly as a declared one is. `ctx.inputs.value(name, value)` declares an input that is not a file — anything the build can compute but not stat — and a change to it re-runs the task and keys its archive differently; `ctx.dirty.values` names which one changed. A task whose declaration is completed this way is tracked, cached and skipped as up to date like any other.

The hook runs on every build your task takes part in, including the ones where it turns out to have nothing to do, so keep it to deriving declarations: it has no `exec`, no `tools` and no `dirty` — that is the answer it is helping to compute — and `ctx.state` is read-only there. Returning `false` fails the task before it runs.

Your action can add **outputs** it only learns by writing them, with the same `ctx.outputs.add(...)`; they are stamped and archived with the rest when it returns. It cannot add inputs — by then the build has already decided whether to run it, so a late `ctx.inputs.add` is an error rather than a declaration that quietly does nothing.

## Passing a value to another task

Your extension's module is evaluated once per build and shared by every task it declares, so a module-level variable one task assigns is often still there for the next — but nothing guarantees it, and a fresh evaluation starts from nothing. Treat module scope as a cache, never as a channel. What a task holds in `ctx.state` is the supported way to pass a value on:

```ts
task("stage", (ctx) => {
  ctx.state.set("staged", `${ctx.layout.buildDir}/staged`);
});

task("publish", { dependsOn: "stage" }, (ctx) => {
  const stage = ctx.state.of("stage");
  if (stage === null) return ctx.skip("nothing has been staged");
  ctx.exec("rsync", [String(stage.get("staged")), "example:/srv"]);
});
```

`ctx.state.of(name)` answers a view of what that task is up to — `get`, `has` and `keys` — and `null` when it published nothing at all. A task the build skipped as up to date, or restored from the cache, answers with what it kept the last time it ran: being up to date is a statement about what it produced, and what it published is part of that. `null` means there was nothing to read — the name is not a task an extension declared, it was not in this build, it failed, or it has not run yet — while a view with no keys is a task that kept nothing. Depend on the task you read; without an edge, "has not run yet" is a race.

A value crosses as the structure it was, not as text, and the same rules as `ctx.state` apply to what can cross. Reading your own name answers what you hold right now.

## What your task is given

The object passed to your action carries the same things the build itself reads:

- `project` — name, version, description, root directory, and the workspace it belongs to.
- `manifest` — your resolved `elide.pkl`, as ordinary JavaScript data. This is exactly what `elide project export --format=json` writes, so `manifest.dependencies.maven.packages.map(...)` works as you would expect.
- `config` — the settings your manifest declared for this extension (see above), empty when it declared none.
- `layout` — `projectDir`, `buildDir`, `artifacts`, `staging` and friends, as absolute paths.
- `option(name)` / `flag(name)` / `values(name)` — the flags this invocation was run with, read through your declaration (see above); `options` is the raw parse, for anything you did not declare.
- `task` — your own declaration, as the build recorded it, including the options it declares.
- `dirty` / `state` — what changed since your task last ran, what it kept, and what other tasks in this build recorded (see above).

## Reporting

| In your action           | What the build records      |
| ------------------------ | --------------------------- |
| return, or return `true` | success                     |
| `ctx.fail(reason)`       | failure, with that reason   |
| return `false`           | failure, with no reason     |
| `ctx.skip(reason)`       | skipped, with that reason   |
| throw, or reject         | failure, with its message   |
| `ctx.exit(code, reason)` | failure exiting with `code` |

`ctx.log`, `ctx.warn` and `ctx.error` write lines attributed to your task. They are build messages, so they go to standard error along with every other build message; standard output carries only what a program you ran writes.

### Exiting with a specific status

`ctx.exit(code, …message)` fails the task and asks the build to exit with `code`. `0` succeeds instead, which is what makes this the whole pass/fail decision for a task that wraps a program:

```ts
ctx.exit(ctx.exec("shellcheck", ["scripts/build.sh"]).exitCode);
```

Reach for it when a status carries meaning a boolean would destroy. A correctness ratchet that exits 2 because the analyzer crashed and 1 because it found a new violation is only useful if the caller can still tell those apart; so is a diagnostic that exits 2 for "not supported on this host" and 1 for "found something".

The code reaches the process only when your task is the one that stopped the build — another task failing first wins. A code outside `0`-`255` wraps the way a shell reports one, and never wraps to zero.

## Running external tools

```ts
const result = ctx.exec("shellcheck", ["scripts/build.sh"], {
  cwd: "tools",            // relative paths resolve against the project root
  env: { CI: "1" },        // added on top of the inherited environment
  quiet: false,            // set true to keep the program's output out of the build log
  timeout: 30_000,         // milliseconds; the child is killed and the task fails
});

result.ok;        // exited zero
result.exitCode;  // 0, 3, …
result.stdout;    // captured up to 1 MiB, even when not quiet; the rest is streamed only
result.stderr;    // under the same cap
```

`exec` blocks until the program exits and streams its output to the build display as it arrives, attributed to your task. No shell is involved: arguments reach the program exactly as you wrote them, so nothing in a filename or a flag can be reinterpreted as shell syntax. A bare command name is looked up on the `PATH` the child will run with — the one your `env` sets, if it sets one — and a name containing a separator resolves against `cwd`. Cancelling the build kills the program and anything it started. `timeout` bounds the program you named; once it exits, output still arriving is read for one more second and then dropped, so a background process it left holding its output does not hold up your task — that process is neither waited for nor killed.

Everything guest JavaScript already has is available too — `node:fs`, `node:child_process`, `fetch` — so reach for `exec` when you want the output attributed to your task, and for `node:child_process` when you need something it does not cover. One rule comes with that: a child you give the build's own terminal (`stdio: "inherit"`) writes where the progress display is drawing, so hand it the terminal with `ctx.foreground`. A child whose output you pipe and print yourself needs nothing — your `console` output is routed through the display like any other.

### Giving a program the terminal

```ts
const code = await ctx.foreground(
  () =>
    new Promise((resolve) => {
      const child = spawn(bin, args, { stdio: "inherit" });
      child.on("close", resolve);
    }),
);
```

The progress display stops drawing for exactly as long as the function runs, and comes back however it ends — so the program's output and the display's rows never erase each other. An `async` function keeps the terminal until its promise settles, and `await ctx.foreground(...)` answers what the function answered and rethrows what it threw.

Wrap the hand-off, not the whole task: everything your task does before it spawns — resolving paths, reading files, calling `ctx.tools` — should still be showing progress. Reach for it only when something writes to the build's own descriptors, which is a child with inherited stdio or anything interactive like a REPL or a debugger. Output written with `ctx.log`, `ctx.exec`, `ctx.tools` or your task's own `console` is already linearized against the display.

## Using the built-in toolchain

Elide already carries a Kotlin compiler, `javac`, `jar`, Native Image, ktfmt and google-java-format. A task that needs one does not have to start another Elide to reach it:

```ts
// Before: a new process per compile, diagnostics as text on a stream.
const compiled = ctx.exec("elide", ["kotlinc", "-d", ".dev/classes", "-cp", cp, "src/main/kotlin"]);
if (!compiled.ok) return ctx.fail(compiled.stderr);
ctx.exec("elide", ["jar", "--create", "--file", ".dev/lib/app.jar", "-C", ".dev/classes", "."]);

// After: the same tools, in-process, with structured results.
const result = ctx.tools.kotlinc({
  sources: ["src/main/kotlin"],                 // files, directories or globs, project-relative
  out: ".dev/classes",                          // a directory, or a path ending in `.jar`
  classpath: ctx.tools.classpath(),             // the resolved compile classpath, in order
  friendPaths: [".dev/classes-core"],           // whose `internal` declarations this compile may see
  args: ["-Xjvm-default=all"],                  // any further kotlinc flags, verbatim
});
if (!result.ok) {
  const first = result.diagnostics.find((d) => d.severity === "error");
  return ctx.fail(`${first?.file}:${first?.line}: ${first?.message}`);
}

ctx.tools.jar({
  out: ".dev/lib/app.jar",
  entries: [{ from: ".dev/classes" }, { from: "LICENSE", into: "META-INF" }],
  mainClass: "com.acme.MainKt",
  manifest: { "Implementation-Version": ctx.project.version ?? "dev" },
});
```

Every call blocks until the tool returns, and answers `{ ok, exitCode, tool, diagnostics }`. Compiler and formatter diagnostics are shown in the build output exactly as a built-in compile shows them, and come back in `diagnostics` as `{ severity, message, file, line, column }`; `jar` and `nativeImage` produce text, which streams to the build log attributed to your task (pass `quiet: true` to keep it out) and leave `diagnostics` empty. Paths are project-relative unless absolute. You may write outputs anywhere, but only outputs under the project directory can be cached and restored, so keep them there when the task declares them.

- `kotlinc({ sources, out, classpath?, friendPaths?, args?, incremental?, plugins? })` — the embedded Kotlin compiler. Compiler plugins your manifest declares or enables (`kotlin.features`, `kotlin.plugins`, `mavenDependencies().kotlinPlugins`) are applied as they are for the built-in compile, and the runtimes those features provide (Metro's, for one) join the classpath with them — a plugin without its runtime fails the compiler rather than doing nothing. `plugins: false` runs the bare compiler, which is what annotation-only sources want. No `-jvm-target` is added unless you pass one in `args`.
- `javac({ sources, out, classpath?, processorPath?, args? })` — the embedded Java compiler; a `processorPath` turns annotation processing on.
- `jar({ out, entries, exclude?, date?, manifest?, mainClass?, quiet? })` — each entry is a directory (its contents), a file, or another archive whose entries are taken (`archive: true`), landing at the archive root or under `into`. `Manifest-Version` and `Created-By` are always written; `mainClass` becomes `Main-Class`.
- `nativeImage({ args, cwd?, quiet? })` — the embedded Native Image driver; relative paths in `args` anchor on `cwd`, which defaults to the project root. The builder runs as a child JVM pinned to Elide's own JDK.
- `format({ tool, files, check?, args? })` — the embedded formatters: `tool` is `"ktfmt"` for Kotlin or `"javaformat"` for google-java-format. `files` are files, directories or globs, narrowed to what the formatter accepts (`.kt`/`.kts` or `.java`); matching nothing succeeds and does nothing. Files are rewritten in place, or with `check: true` only reported, which fails the call when any file would change. Either way `changed` lists the absolute paths of the files that were not formatted, and each arrives as a diagnostic: a warning under `check`, an info for a rewrite, an error for a file that could not be read or parsed. `args` passes further flags to the formatter, such as `["--google-style"]`.
- `classpath({ sourceSet?, usage? })` — the resolved dependency classpath as absolute paths in order. `usage` is `"compile"` (default; what the compile tasks see), `"runtime"`, `"test"` (the test set's runtime classpath), `"processor"` or `"modules"`. It answers what this build has resolved, so a task reading it should `dependsOn: "maven-dependencies"`.

`ctx.tools.version` is the version of these option and result shapes — `1` today. It moves only on an incompatible change; a new optional option or result member does not move it. An extension that must run against more than one Elide branches on it.

The compilers run in-process only through the embedded toolchain. A manifest that selects a custom or managed `kotlin.toolchain`, or the external `jvm.java.compiler.mode`, gets an error from `ctx.tools.kotlinc` / `ctx.tools.javac` naming the task and the tool; drop the selection, or run that toolchain as a program with `ctx.exec`. The same is true of a distribution built without the JVM toolchain.

### Repacking an archive

`jar` reads an existing archive as a source, so stripping a dependency down and stamping it reproducibly is one in-process call rather than an `unzip` / `rm -rf` / `jar` pipeline:

```ts
ctx.tools.jar({
  out: ".dev/lib/compiler-slim.jar",
  entries: [{ from: "libs/compiler.jar", archive: true }, { from: ".dev/patched" }],
  exclude: ["com/intellij/**", "META-INF/*.SF"],
  date: "2024-01-01T00:00:00Z",
});
```

`archive: true` is never inferred from the file extension: without it, a `.jar` named by `from` is added as a single file. The source archive's own `META-INF/MANIFEST.MF` is dropped — the result carries the manifest `manifest` and `mainClass` describe, never the source's — and `into` re-roots everything else. A member whose path, after `into`, would land outside the archive (`../x`, or an absolute `/x`) fails the task rather than being written, and so does an `into` that climbs out.

`exclude` globs match the path an entry would take *inside the archive*, after `into` has re-rooted it. They are paths, not package names, so a package tree is `"kotlin/**"` and a file kind is `"META-INF/*.SF"`. A glob on the options applies to every entry whatever its source; a glob on an entry applies to that entry alone, on top of them.

`date` stamps every entry, the manifest included, at that instant, and the tool writes a root's files in sorted order — so a repack of unchanged input is byte-identical, which is what an AOT or distribution stamp needs. Without it entry times are not reproducible: an entry passed through untouched keeps its files' modification times, while an archive member, an entry with `into`, and an entry an exclude or a collision touched carry the time of the call.

Entries are packaged in the order you list them, and two of them may claim the same archive path: the last one wins, and the build warns naming the path and the source it was taken from. Nothing is merged — a `Jar` artifact declared in the manifest unions the `META-INF/services` files of its roots, `ctx.tools.jar` does not, so a task that needs that union writes the merged file itself and lists it last.

---

# Build flags

URL: https://elide.help/docs/toolchain/build-flags

> Pass build flags to Elide with `--flag` or `-f` and read them in an elide.pkl manifest to parameterize a build, such as a release mode or version number.

A build flag is a name, with an optional value, that `elide.pkl` reads when it is evaluated.

## Pass flags

```bash
elide build run --args="Hello World 🌎" --flag=RELEASE --flag=VERSION=1.2.3
elide build run --args="Hello World 🌎" -fRELEASE -fVERSION=1.2.3
```

`--flag NAME` and `-f NAME` also work, in any position. Arguments after `--` are never flags. `--args` belongs to the
`run` task; see [Build Tasks](https://elide.help/docs/toolchain/build-tasks).

Every project-aware command takes flags:

```bash
elide run -fRELEASE -fVERSION=1.2.3 -- "Hello World 🌎"
elide install --flag=RELEASE
elide format -fNO_KOTLIN
elide build -fRELEASE
elide test -fFAST
elide project export -fRELEASE    # shows the evaluated result
```

- A flag without a value (`-fRELEASE`) is **bare**: `true` to `bool(...)`, an error to `string(...)`.
- The value is everything after the first `=`, verbatim: `-fEXPR=a=b` gives `a=b`.
- A repeated flag keeps every value; scalar accessors read the last ([Repeated flags](#repeated-flags)).
- Flags need no declaration; an unknown name is absent.
- Names cannot be empty or contain `,` or `=`.

## Read flags in elide.pkl

```pkl
amends "elide:project.pkl"

local isRelease = build.flags.bool("RELEASE")

name = if (isRelease) "demo-release" else "demo-debug"
version = build.flags.stringOr("VERSION", "0.0.0")
```

| Accessor | Returns |
| --- | --- |
| `has(name)` | Whether the flag was passed, with or without a value. |
| `count(name)` | Times passed; `0` when absent. |
| `string(name)` | The value; `null` when absent; throws when bare. |
| `stringOr(name, orElse)` | The value, or `orElse` when absent. |
| `bool(name)` | `false` absent, `true` bare; `true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0` (any case); else throws. |
| `int(name)` | The value as `Int`; `null` when absent; throws if not an integer. |
| `strings(name)` | Every value in order; empty when absent; throws on a bare occurrence. |
| `stringsOr(name, orElse)` | Every value, or `orElse` when absent. |
| `ints(name)` | Every value as `Int`; empty when absent; throws if any is not an integer. |
| `bools(name)` | Every value as `Boolean`; empty when absent; bare reads `true`. |
| `raw` | `Mapping<String, String>` of effective values; bare maps to `""`. |
| `all` | `Mapping<String, List<String>>` of every value. |

Use `strings(...)` to accept one or more values. Typed accessors fail on bad input:

```text
–– Pkl Error ––
build flag `RELEASE` is not a boolean: `perhaps`
```

### Environment variables

`read("env:NAME")` sees only `PATH`, `HOME`, `USER`, `LANG`, `LC_*`, `TZ`, `CI`, `TERM`, `SHELL`, `OS`, `TMPDIR` and
`ELIDE_*`; any other variable reads as absent. Use a build flag, or allow more:

```shell
elide build --allow-env=GITHUB_SHA,JAVA_HOME
elide build --allow-env            # every variable
```

### Repeated flags

```bash
elide build -fARG=one -fARG=two -fARG='three, and a half'
```

```pkl
local args = build.flags.strings("ARG")  // List("one", "two", "three, and a half")
local first = build.flags.all["ARG"].first
local latest = build.flags.string("ARG") // "three, and a half" — scalars read the last value
```

Values keep commas, spaces, `=` and Unicode. List accessors check every element:

```text
–– Pkl Error ––
build flag `N` is not an integer: `x1`
```

### Flags inside nested blocks

Inside a nested object body, bare `build` does not resolve. Bind a module-level `local`, or use
`module.build.flags`:

```pkl
local wantsExtra = build.flags.bool("EXTRA")

dependencies {
  maven {
    packages {
      "com.google.guava:guava:33.0.0-jre"
      when (wantsExtra) {
        "com.example:extra:1.0.0"
      }
      when (module.build.flags.bool("MORE")) {
        "com.example:more:1.0.0"
      }
    }
  }
}
```

---

# Testing

URL: https://elide.help/docs/toolchain/testing

> Run JavaScript and TypeScript `node:test` files and JUnit tests with `elide test`: discovery, selecting tests, options, reports and coverage.

`elide test` runs JavaScript and TypeScript `node:test` files and JUnit tests.

```bash
elide test
```

A failing test makes the exit code non-zero.

<img src="https://elide.help/assets/demos/test.gif" alt="Discovering and running JavaScript tests with Elide" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## JavaScript and TypeScript

Tests use the `node:test` API and need no manifest. A file is a test if it matches `*.test.*`, `*.spec.*`,
`*_test.*` or `*_spec.*`, or is under `test`, `tests` or `__tests__`. Extensions: `.js`, `.mjs`, `.cjs`, `.ts`,
`.mts`, `.cts`.

Discovery skips hidden, dependency and build-output directories. It stops at any nested project (a directory with
`elide.pkl`, `package.json`, `pom.xml` or `requirements.txt`), so a workspace root finds no member tests. Name a path
to run them.

```js
import test from "node:test";
import assert from "node:assert";

test("adds two values", () => {
  assert.equal(1 + 1, 2);
});
```

## JVM tests

JVM tests run on the JUnit Platform and need an `elide.pkl`. `src/test` is the default test source set; a declared
source set of type `test` replaces it ([Source Sets](https://elide.help/docs/toolchain/source-sets)).

- Test sets get `testPackages` plus the main set's dependencies.
- Bundled JUnit libraries are added by default. `jvm.features.testing = false` removes both the JUnit compile APIs and
  the bundled runtime; a JVM test run then needs a JUnit console launcher (`junit-platform-console`) in `testPackages`,
  and fails with an error otherwise. Runs that include no JVM tests are unaffected.
- `processors` run on test sources.
- The test JVM gets `jvm.flags` and `jvm.defs` (as `-D`).
- `modules` dependencies of the test and main sets go on `--module-path` with `--add-modules=ALL-MODULE-PATH`.
- Parallel settings in a `junit-platform.properties` on the test classpath override `--concurrency`.

## Select tests

Paths, directories or globs narrow JavaScript and TypeScript tests:

```bash
elide test src/api
elide test src/api/client.test.ts
```

Path arguments skip JVM tests and print `Path filtering unsupported for JVM tests: <paths>`. `-t` matches test names
in both runners:

```bash
elide test -t 'parses .+ headers'
```

JVM tests take JUnit selectors and tag expressions:

```bash
elide test --select=class:com.example.ParserTest
elide test --select=method:com.example.ParserTest#parsesHeaders
elide test --select=package:com.example.parser   # the package and its subpackages
elide test com.example.parser                     # a dotted bare token is a package selector
elide test --include-tag=fast --include-tag=unit  # fast OR unit
elide test --exclude-tag=slow --exclude-tag=flaky # neither slow nor flaky
elide build test --select=class:com.example.ParserTest
```

<img src="https://elide.help/assets/demos/jvm-test.gif" alt="elide test — JUnit selectors on a Kotlin project" width="1591" height="873" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`--include-tag='slow & !flaky'` is one expression. Tag filters apply after selectors.

## Output and reports

Progress goes to stderr; the final tally goes to stdout:

```bash
elide test > summary.txt
elide test 2> progress.txt
```

Reporters write to `.dev/reports/tests/<language>/<source-set>/`. `testing.reports` in `elide.pkl` turns them on
without a flag:

```pkl
import "elide:Testing.pkl" as Testing

testing {
  reports { Testing.xmlReport() }
}
```

### TAP output

`--reporter=tap` makes stdout a pure TAP 13 stream:

```text
TAP version 13
# start 1: suite A > t1
# out 1: printed from inside a test
ok 1 - suite A > t1
# start 2: broken
not ok 2 - broken
  ---
  message: "expected 1 to equal 2"
  severity: "ERR_ASSERTION"
  ...
1..2
```

- `# start <id>` opens a test; its output lines are `# out <id>: <text>`. `# out: <text>` belongs to no test.
- Test points are numbered `1..N` in finishing order. Match points to tests by the `# start` line, not the number.
- A YAML block appears only on failures with details; `severity` is the runner's error code, if any.
- Stderr is not framed: `elide test --reporter=tap 2>&1` is not valid TAP.
- JVM: output is tagged with its test only while exactly one test runs. With `--concurrency` above 1 or a project
  `junit-platform.properties`, it is untagged.
- JavaScript: `console.log` inside a test, or at top level after importing `node:test`, is framed. Output before that
  import is raw. Hook output belongs to the test the hook wraps; `t.diagnostic` is framed as `# out`.

## Coverage

```bash
elide test --coverage
elide run --coverage
```

JVM coverage goes to `.dev/reports/coverage/jvm/<task>/` as HTML, XML or CSV; JavaScript and TypeScript coverage is
LCOV, in `.dev/reports/coverage/js/lcov.info` for tests and `.dev/reports/coverage/js/run/lcov.info` for runs. The
console prints one combined summary. The top-level `coverage` block collects without the flag:

```pkl
import "elide:Coverage.pkl" as Coverage

coverage {
  enabled = true
  scope = "tests"
  jvm {
    excludes { "org.example.generated.*" }
    reports {
      Coverage.xmlReport()
      Coverage.htmlReport()
    }
  }
  js {
    paths { "src" }
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `enabled` | Collect without `--coverage`. | `false` |
| `scope` | `"tests"`, `"runs"` or `"all"`; `--coverage` always covers its own task. | `"tests"` |
| `jvm.reports` | `Coverage.htmlReport()`, `xmlReport()`, `csvReport()`. | none |
| `jvm.excludes` | Class patterns (`*`, `?`) not instrumented, such as generated code. | none |
| `js.paths` | Source roots to report; empty means the whole project. | none |

With coverage, `elide run` starts a separate JVM process.

## Options

| Option | Effect |
| --- | --- |
| `-t REGEX` | Match test or enclosing-suite names. |
| `--where CEL` | JavaScript: run tests for which a [CEL](https://elide.help/docs/api-cel) expression over `name`, `parents` and `file` is true. |
| `--select=SELECTOR` | JVM: `class:`, `method:` or `package:` selector; repeatable. |
| `--include-tag=EXPR` | JVM: run tests whose tags match; repeats are ORed. |
| `--exclude-tag=EXPR` | JVM: skip tests whose tags match; repeats are ANDed. |
| `--bail[=N]` | Stop after `N` failures (default 1). |
| `--test-timeout=MS` | Default per-test timeout. |
| `--timeout DURATION` | Time limit for the whole invocation (global). |
| `--only` | Run only tests marked `.only`. |
| `--concurrency=N` | Run files or JVM classes in parallel. Default `1`; `0` is invalid. |
| `--coverage` | Collect coverage; see [Coverage](#coverage). |
| `--reporter=junit` | Write JUnit XML reports. |
| `--reporter=tap` | Write TAP 13 to stdout (and under `--reporter-outfile`). |
| `--reporter-outfile=DIR` | Report directory. |
| `--debugger[=MODE\|ADDRESS]` | Attach a debugger; see below. |
| `--debugger-host=HOST`, `--debugger-port=PORT` | JavaScript debugger address (DAP: 4711; CDP: 1337). |

| `--debugger` form | Debugs |
| --- | --- |
| bare | JVM tests over JDWP on `127.0.0.1:5005`, and JavaScript tests. |
| `=5005`, `=host:5005` | JVM tests only (JDWP). |
| `=dap`, `=cdp` | JavaScript tests only. |

Grammar: [Debugging](https://elide.help/docs/debugging). An unknown option or missing value fails before anything runs
([Build Tasks](https://elide.help/docs/toolchain/build-tasks#options)).

## Limits

- No Python test discovery; run unittest or pytest instead ([Python tests](https://elide.help/docs/python-testing)).
- JVM tests need a manifest.
- Not implemented: `node:test` snapshots, `mock.module`, watch mode, programmatic `run()`, `node:test/reporters`.

Supported API: [Node test API](https://elide.help/docs/api-node-test).

## Samples

- [TypeScript tests](https://elide.help/docs/code-samples#typescript-tests)
- [Kotlin tests](https://elide.help/docs/code-samples#kotlin-tests)
- [Filter tests with CEL](https://elide.help/docs/code-samples#filter-tests-with-cel)
- [JUnit XML in CI](https://elide.help/docs/code-samples#junit-xml-in-ci)

Start from a template:

```bash
elide init --template java        # Java app with a JUnit test
elide init --template ktjvm       # Kotlin app with a test
```

## Shared test containers

Declare disposable services in `testing.testcontainers`. Elide starts them before the project's selected
JavaScript, TypeScript, and JUnit runners, waits for readiness, and stops them when the test run finishes.
Every runner in that project receives the same connection values. This works independently of Micronaut
or any other application framework.

```pkl
amends "elide:project.pkl"
name = "database-tests"

testing {
  testcontainers {
    containers {
      ["postgres"] {
        image = "postgres:17-alpine"
        environment {
          ["POSTGRES_USER"] = "test"
          ["POSTGRES_PASSWORD"] = "test"
          ["POSTGRES_DB"] = "app"
        }
        ports { 5432 }
        wait { timeoutSeconds = 90 }
      }
    }
    environment {
      ["DATABASE_HOST"] = "${postgres.host}"
      ["DATABASE_PORT"] = "${postgres.port.5432}"
      ["JDBC_URL"] = "jdbc:postgresql://${postgres.host}:${postgres.port.5432}/app"
    }
  }
}
```

Read these values through `process.env` in JavaScript/TypeScript or `System.getenv` in Java/Kotlin.
Bindings override inherited environment variables for the test runners only. A binding can include
`${name.host}`, `${name.port.CONTAINER_PORT}`, or `${name.id}`; unknown references fail before startup.
Ports are TCP ports inside the container. Testcontainers assigns available host ports, so concurrent runs
do not need fixed port reservations. Workspace members have independent container sets.

Each container supports `image`, an optional `command` argument list, `environment`, `ports`, and `wait`:

| Wait strategy | Required settings | Behavior |
| --- | --- | --- |
| `"port"` (default) | Nonempty `ports` | Wait for exposed ports to listen |
| `"http"` | `wait.port` naming an exposed port | GET `wait.path` (default `/`), expecting `wait.status` (default `200`) |
| `"log"` | `wait.pattern` | Wait for one matching Java regular expression in container logs |

`wait.timeoutSeconds` defaults to 60. The overall `startupTimeoutSeconds` defaults to 300 and includes
image downloads and all readiness checks. Startup failures fail the test run. Container command arguments
are passed directly; use an explicit shell command inside the container if needed.

A Docker-compatible daemon and JDK 17 or newer with source-file launching support are required. Elide uses its
configured JVM toolchain and resolves Testcontainers separately from application dependencies on first
use. Docker connection settings such as `DOCKER_HOST` are inherited. This path is also used by the native
Elide CLI; Testcontainers runs in a helper JVM. It adds nothing to your application JAR or Native Image.

`elide install` and compilation do not start containers. `elide test` retains normal test selection,
reporting, and coverage behavior; `elide build test` supports containers for JVM test tasks too. Cleanup
runs after success, failure, or cancellation. The helper monitors its parent connection, and Testcontainers'
resource reaper handles orphaned Docker resources. Keep the resource reaper enabled in CI.

Session files live under `.dev/testcontainers/`. Requests containing container environment values are
deleted after the helper reads them and again during cleanup. Helper logs remain there for diagnosis;
they can contain output from the container library. On POSIX systems, session directories are private.

The `testcontainers` project sample contains JavaScript and JUnit tests against one shared HTTP container.
Run it with `elide test`. For this repository's Docker-backed integration checks, run
`make test-testcontainers JVM=yes` after a JVM build, or `make test-testcontainers` against a native build.

---

# Render Pkl configuration

URL: https://elide.help/docs/pkl-configuration

> Generate JSON, YAML, and PCF from Pkl configuration files for applications, deployment tools, and CI.

Coming in Elide 1.6.3. Evaluate a `.pkl` or `.pcf` file directly and send its rendered output to stdout.
Use this to generate application configuration, feed deployment tools, or inspect a configuration before committing it.
No Elide project is required.

## Generate JSON or YAML

Start with `config.pkl`:

```pkl
service = "api"
port = 8080
```

Choose the format your application consumes and redirect the result to a file:

```shell
elide --format=json config.pkl > config.json
elide --format=yaml config.pkl > config.yaml
```

The JSON output contains `service` and `port` with the same values and types. The explicit `run` command works too:

```shell
elide run --format json config.pkl
```

Both `.pkl` and `.pcf` inputs accept the same options. For example, convert an existing PCF configuration to JSON:

```shell
elide --format=json config.pcf > config.json
```

## Choose an output format

| Option | Output | Typical use |
| --- | --- | --- |
| `--format=json` | JSON | Application settings and JSON-consuming tools |
| `--format=yaml` | YAML | Deployment configuration |
| `--format=pcf` | Pkl Configuration Format | Inspect evaluated configuration in Pkl notation |
| No `--format` | The module's configured output; PCF by default | Honor a module's own output definition |

TOML output is not supported. An unsupported format fails with exit code `2`.

## Share configuration across files

Relative imports resolve from the input file, so a configuration can reuse nearby defaults even when invoked
from another directory. For example, place `defaults.pkl` and `config.pkl` together under `config/`:

```pkl
// defaults.pkl
port = 8080
```

```pkl
// config.pkl
import "defaults.pkl"

service = "api"
port = defaults.port
```

From the repository root, render the configuration with:

```shell
elide --format=json config/config.pkl
```

## Use the output in scripts and CI

Stdout contains only the rendered document; diagnostics and evaluation errors go to stderr. No `--quiet` flag is
needed for redirection or pipelines. For example, inspect a property with `jq` installed:

```shell
elide --format=json config.pkl | jq '.port'
```

An evaluation failure exits with code `1` and writes no rendered content to stdout. To update a file atomically,
use `--out` rather than shell redirection:

```shell
elide --format=json --out config.json config.pkl
```

`--out config.json` writes a temporary file in the destination directory and atomically replaces `config.json`
only after evaluation and writing succeed. Failures leave the existing file unchanged and exit nonzero. The
destination directory must exist and support atomic replacement. Relative paths resolve from your working directory.

Use `--out -` to explicitly select stdout:

```shell
elide --format=json --out - config.pkl
```

Document rendering rejects `--sandbox` and `--limit`; those execution controls do not apply to this command.
For all command options, see the [CLI reference](https://elide.help/docs/cli-references). To read a README or runbook in the same
terminal, see [Markdown in the terminal](https://elide.help/docs/terminal-markdown).

---

# Markdown in the terminal

URL: https://elide.help/docs/terminal-markdown

> Read READMEs, runbooks, and Markdown notes with styled headings, code panels, tables, and terminal-aware output.

Coming in Elide 1.6.3. Open a `.md` or `.markdown` file with Elide to read it as a formatted terminal document.
Use it for a repository's README, an operational runbook over SSH, or development notes without leaving the shell.
No Elide project is required.

## Read a README or runbook

```shell
elide README.md
elide docs/runbook.md
elide run notes.markdown
```

Headings establish a visual hierarchy; lists, quotes, tables, and code panels make longer documents easier to scan.
Prose wraps to the terminal width, and fenced code blocks receive syntax highlighting for recognized languages.
Code blocks are displayed, not executed.

CommonMark syntax is supported along with GitHub-style tables, strikethrough, and task lists. For example,
save this as `runbook.md`:

````markdown
# Check the service

- [x] Generate configuration
- [ ] Verify the health endpoint

```shell
curl http://localhost:8080/health
```

| Response | Next step |
| --- | --- |
| 200 | Continue deployment |
| 503 | Check application logs |
````

Then run `elide runbook.md`. Links retain their destinations, and raw HTML is displayed as text.

## Page through a long document

Elide prints the rendered document to stdout. Pipe it to a pager such as `less` when you want to scroll:

```shell
elide docs/runbook.md | less
```

Piped output is plain by default. To retain terminal colors with a pager that understands ANSI escapes:

```shell
elide --color docs/runbook.md | less -R
```

`--no-color` and the `NO_COLOR` environment variable take precedence over forced color. If `NO_COLOR` is set,
remove it from the environment before using the color example.

## Save a readable text copy

Disable colors explicitly when saving rendered notes for a log or an artifact:

```shell
elide --no-color notes.markdown > notes.txt
```

This writes the terminal rendering, including its layout, rather than converting Markdown to another document format.
The source file remains unchanged. `--quiet` also preserves the rendered output.

`--format` is for [Pkl and PCF output](https://elide.help/docs/pkl-configuration) and is rejected for Markdown files.
Document rendering also rejects `--sandbox` and `--limit`. See the [CLI reference](https://elide.help/docs/cli-references) for command options.

---

# JVM toolchain

URL: https://elide.help/docs/toolchain/jvm

> Elide's bundled JDK 25 and Kotlin 2.5: compile and run with javac, java and kotlinc, format, build projects, and call the tools from other builds.

Elide bundles JDK 25 and Kotlin 2.5.0-Beta2. Libraries and annotations available to programs: [JVM APIs](https://elide.help/docs/api-jvm).

## Compile and run

```bash
elide javac -- -d out Hello.java
elide java -- -cp out Hello

elide run Hello.kt
```

Options for the wrapped tool go after `--`. `elide run` compiles a Kotlin file and runs it with the Kotlin standard
library; `elide java` does not add it ([Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc#compile-source-files)).

## Format

```bash
elide format -- src
elide format -- -n src # check only
```

Use `elide format --install -- --jfmt` for the Java jfmt dialect with project dependencies installed before its
[type-based import pass](https://elide.help/docs/toolchain/jvm/formatting#resolve-and-rewrite-imports). Kotlin still uses ktfmt.
Per-formatter options and selections: [Formatting](https://elide.help/docs/toolchain/jvm/formatting).

## Build a project

With an `elide.pkl`:

```bash
elide install
elide build
elide test
```

Sources in `src/main/java`, `src/main/kotlin` and `src/test/…` need no configuration. JVM tests
need an `elide.pkl`. Coverage: [Testing](https://elide.help/docs/toolchain/testing#coverage).

In a terminal, each task line shows how many files it compiles. In CI, with redirected output, or under an agent, the
build prints one plain line per task.

[Micronaut](https://elide.help/docs/toolchain/jvm/micronaut) projects support automatic processors, Pkl configuration, JUnit coverage,
JVM distributions, and Native Image targets.

## Rewrite and inspect code

[OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) previews and applies recipes to main Java sources.
[Dependency code index](https://elide.help/docs/toolchain/jvm/code-index) finds class origins, inspects members, and queries references in
Maven dependencies and compiled local Java and Kotlin code. Both are experimental in 1.6.0 and use `elide.pkl`.

```bash
elide rewrite org.openrewrite.java.RemoveUnusedImports --dry-run
elide index build --layers=l1,l2,l3
elide index used-by java.util.List
```

## Compile headers and generated code

The compiler wrappers expose separate outputs for build systems that distinguish a library's compile-time API from
its implementation:

```bash
elide javac --abi-only --emit-abi java-abi.jar -- src/Api.java
elide kotlinc --abi-only -- -d kotlin-abi.jar src/Library.kt
```

Dependents can compile against these headers; execution needs the full implementation. Java headers skip method-body
compilation. Kotlin header-only compilation strips non-inline implementation bodies by default while preserving
metadata, inline code and constants needed by consumers. Full compilation can also emit a header alongside its regular
output. See [Java ABI jars](https://elide.help/docs/toolchain/jvm/javac#abi-jars) and
[Kotlin ABI jars](https://elide.help/docs/toolchain/jvm/kotlinc#abi-jars) for output flags and constraints.

For code generation, select the phase that matches the processor or input:

| Input | Command or configuration |
| --- | --- |
| Java annotation processor | `elide javac -- --processor-path …`; [processor setup](https://elide.help/docs/toolchain/jvm/maven#annotation-processors) |
| Java annotation processor over Kotlin declarations | `elide kotlinc --kapt-sources …`; [processing phase](https://elide.help/docs/toolchain/jvm/kotlinc#annotation-processors-over-kotlin) |
| KSP2 symbol processor | `elide kotlinc --ksp-output …`; [KSP outputs and compilation](https://elide.help/docs/toolchain/jvm/kotlinc#kotlin-symbol-processing) |
| C headers | `jvm.java.bindings` or `elide javac -- --jextract …`; [compile bindings in memory](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings) |

Kotlin processing commands generate outputs for a later compile; `elide build` does not schedule KSP or Java annotation
processing over Kotlin automatically, except KAPT for Android projects with `processors` declared. C header bindings
selected in a Java source set are generated and compiled by the normal project build. [Standalone jextract](https://elide.help/docs/toolchain/native/jextract) exports Java FFM sources separately.

## Existing build systems

| Build | Use |
| --- | --- |
| Maven | [Maven plugin](https://elide.help/docs/build-tools-maven), or [`elide mvn`](https://elide.help/docs/toolchain/jvm/native-maven) |
| Gradle | [Gradle plugin](https://elide.help/docs/build-tools-gradle) |
| Bazel | [`rules_elide` and persistent workers](https://elide.help/docs/build-tools-bazel) |
| Any | `elide javac -- …` and the other wrappers, or `JAVA_HOME` set to the Elide distribution |

Overview: [Build tool integration](https://elide.help/docs/build-tools).

`elide --help-all` lists every command.

## Samples

- [Java records and streams](https://elide.help/docs/code-samples#java-records-and-streams)
- [Kotlin collections](https://elide.help/docs/code-samples#kotlin-collections)
- [Kotlin tests](https://elide.help/docs/code-samples#kotlin-tests)

Start from a template:

```bash
elide init --template java        # Java app with a JUnit test
elide init --template ktjvm       # Kotlin app with a test
elide init --template workspace   # Kotlin library and app in one workspace
```

---

# Maven dependencies

URL: https://elide.help/docs/toolchain/jvm/maven

> Install Maven dependencies with `elide install`, including for projects that have only a pom.xml, and configure annotation processors in an Elide project.

Elide resolves Maven dependencies declared in `elide.pkl` or a `pom.xml`.

```bash
elide install
```

Maven is the default ecosystem. Buckets, repositories, credentials and install options:
[Dependencies](https://elide.help/docs/toolchain/dependencies).

## Projects with only a `pom.xml`

```bash
elide install -p .
```

Elide reads the POM's direct dependencies, `${property}` values and its own `dependencyManagement`. Parents and
imported BOMs are not merged; a dependency versioned only by a parent is dropped.

| POM scope | Bucket |
| --- | --- |
| `compile` | `packages` |
| `provided`, `system` | `compileOnly` |
| `runtime` | `runtimeOnly` |
| `test` | `testPackages` |

To run Maven goals, use [Native Maven](https://elide.help/docs/toolchain/jvm/native-maven).

## Inspect dependency code

In an `elide.pkl` project, the experimental [dependency code index](https://elide.help/docs/toolchain/jvm/code-index) records types,
members, and references from resolved Maven JARs. Use `elide index resolve` to find a class's defining artifact,
or `elide index references` to inspect what a dependency class uses.

[OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) uses that index to run Java recipes. Declare additional recipe modules under
`dependencies.maven.devPackages` and preview source changes with `--dry-run`.

## Annotation processors

```pkl
dependencies {
  maven {
    packages { "org.mapstruct:mapstruct:1.6.3" }
    processors { "org.mapstruct:mapstruct-processor:1.6.3" }
  }
}
```

- Processors run in `elide build` and `elide javac`, on main and test source sets.
- A changed processor JAR recompiles.
- Generated sources go to `.dev/jvm/generated-sources/<set>/java` and compile with the set.
- Processors see Java sources only, never Kotlin declarations. Kotlin compiles before Java processing, so Kotlin code
  that uses generated types must get them from an upstream source set or project.
- Project builds don't run processors over Kotlin (KAPT), except Android projects with `processors` declared; KSP is unsupported.
- `-proc:none`, `-proc:only` and `-proc:full` behave as in `javac`.

`elide javac --capabilities` reports what this Elide build supports:

```json
{
  "version": 1,
  "javaAnnotationProcessing": true,
  "kotlinSymbolProcessing": false,
  "kotlinCompilerPlugins": false
}
```

| Field | Meaning |
| --- | --- |
| `javaAnnotationProcessing` | Java annotation processors run. |
| `kotlinSymbolProcessing` | KSP processors run. |
| `kotlinCompilerPlugins` | Third-party Kotlin compiler plugins run in the embedded compiler. Built-in plugins and a [managed or custom toolchain](https://elide.help/docs/toolchain/jvm/kotlinc#choose-a-toolchain) are not affected. |

Set `ELIDE_TRACE_PROCESSORS=1` to print each processor class as it loads (`Loading processor dependency:
demo.HelloProcessor`).

---

# Micronaut

URL: https://elide.help/docs/toolchain/jvm/micronaut

> Build, test, package, and compile Java Micronaut applications with Elide, using Pkl or authored resources for configuration.

Elide 1.6.3 installs Micronaut's Java annotation processors, compiles bean definitions, and builds JVM
applications and Native Image executables. Application configuration can live in `elide.pkl` or ordinary resources.

## Start a new application

Generate a Java application with a runnable JVM distribution and an optional context test:

```shell
elide init --plain --skip-defaults --skip-run --template micronaut project_name=my-app
elide install
elide build :app
elide test
elide run
```

Run initialization in an empty project directory. Use `package=dev.acme` and `main_class=Application` to customize
Java names, or `tests=false` to omit the test. See [Project setup](https://elide.help/docs/projects) for interactive initialization.

## Declare dependencies

Use the **Micronaut Core version**, which can differ from the platform BOM version:

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm

dependencies {
  micronaut {
    version = "4.10.23"
    modules { "runtime" }
  }
}
jvm { main = "example.Application" }
artifacts {
  ["classes"] = new Jvm.Jar { name = "example" }
  ["app"] = new Jvm.JvmApplication {
    name = "example"
    from { "classes" }
  }
}
```

Create `src/main/java/example/Application.java`:

```java
package example;

import io.micronaut.context.ApplicationContext;

public final class Application {
  public static void main(String[] args) {
    try (ApplicationContext context = ApplicationContext.run()) {
      System.out.println(context.getProperty("sample.message", String.class).orElse("hello"));
    }
  }
}
```

Module names expand to `io.micronaut:micronaut-<name>:<version>`. Add `http-server-netty` for a Netty
HTTP server; `testModules` adds Core modules to test dependencies. Independently versioned libraries,
such as Micronaut Serialization and Micronaut Test, use ordinary [Maven coordinates](https://elide.help/docs/toolchain/jvm/maven).

```bash
elide install
elide build :app
elide run
```

Elide installs matching `micronaut-inject-java` and `micronaut-graal` processors. Direct Core coordinates
also activate this behavior, after workspace version pins are applied. Conflicting Core or processor versions
fail validation. Transitive-only framework dependencies and satellite coordinates cannot establish a Core version;
declare a Core module or use the shorthand.

## Configure the application in Pkl

Add this block to the manifest:

```pkl
jvm {
  micronaut {
    config {
      micronaut { application { name = "example" } }
      sample {
        message = "hello"
        number = 7
        enabled = true
        labels = new Listing { "alpha"; "beta" }
      }
    }
  }
}
```

`config` accepts arbitrary JSON-compatible objects, mappings, lists, strings, numbers, booleans, and nulls.
Pkl evaluates the values and renders `application.json`; there is no fixed list of supported Micronaut settings.
Elide installs the matching `micronaut-jackson-core` JSON loader automatically.

The generated file is placed on production classpaths and in production JARs. Editing the Pkl values invalidates
resource and JAR tasks, and downstream native builds consume the updated JAR. Micronaut's normal environment
and system-property overrides remain available. Configuration packaged into a JAR or executable is readable by
its recipients; supply deployment secrets at runtime.

## Use resources instead

Omit `jvm.micronaut` and put `application.json`, `application.yml`, or `application.properties` in
`src/main/resources`. Declare the loader required by the chosen format. For JSON:

```pkl
dependencies {
  maven {
    packages { "io.micronaut:micronaut-runtime:4.10.23" }
    runtimeOnly { "io.micronaut:micronaut-jackson-core:4.10.23" }
  }
}
```

An authored `application.json` and generated Pkl configuration cannot occupy the same resource path; Elide fails
the build with a collision message. Environment-specific resources such as `application-test.json` can coexist
with generated base configuration. [Source sets](https://elide.help/docs/toolchain/source-sets) control resource roots and destinations.

## Generated outputs

All build outputs stay under the project's build directory, `.dev/` by default:

| Output | Location |
| --- | --- |
| Java classes and processor metadata | `.dev/jvm/classes/main/java/` |
| Processor-generated Java sources | `.dev/jvm/generated-sources/main/java/` |
| Staged configuration | `.dev/staging/jvm-resources/main/` |
| JVM distribution | `.dev/artifacts/install/example/` |
| Native executable and argument record | `.dev/artifacts/native-image/` |

Micronaut generates bytecode for bean definitions and may produce no Java source files. Its `META-INF/micronaut`
and `META-INF/native-image` metadata travel with the compiled classes into the JAR. Generated output never needs
to be copied into `src/` or checked in.

## Tests and coverage

Put JUnit tests in `src/test/java`. The bundled JUnit APIs and runner work with an ordinary Micronaut context:

```java
import io.micronaut.context.ApplicationContext;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

class ConfigurationTest {
  @Test
  void readsConfiguration() {
    try (ApplicationContext context = ApplicationContext.run()) {
      assertEquals("hello", context.getRequiredProperty("sample.message", String.class));
    }
  }
}
```

```bash
elide test
elide test --coverage
```

Main resources are available to tests, and annotation processing also runs on test sources. For `@MicronautTest`,
declare `io.micronaut.test:micronaut-test-junit5` with its own compatible version in `maven.testPackages`.
[Testing](https://elide.help/docs/toolchain/testing) describes test selection, XML reports, coverage formats, and exclusions. Reports
use the normal `.dev/reports/tests/` and `.dev/reports/coverage/jvm/` directories. Coverage measures JVM execution;
it does not instrument the resulting native executable.

## Native Image

Import the artifact schema and add a target alongside the JAR and JVM application:

```pkl
import "elide:NativeImage.pkl" as NativeImage

artifacts {
  ["native"] = new NativeImage.NativeImage {
    name = "example"
    from { "classes" }
    options {
      classInit { default = "runtime" }
      linkAtBuildTime { enabled = false }
    }
  }
}
```

```bash
elide build :native
.dev/artifacts/native-image/example
```

The runtime initialization policy lets Micronaut's own metadata identify safe build-time classes. Disabling
blanket build-time linking allows Micronaut's optional integrations to remain absent. Elide includes
`application` and `bootstrap` resources, including environment variants, in JSON, YAML, and properties formats.
The matching Graal processor supplies reflection metadata for annotated application types; Micronaut's libraries
supply their own bean metadata rules. Additional third-party libraries may require their own reachability metadata.
See [Native Image](https://elide.help/docs/toolchain/jvm/native-image) for toolchain selection, flags, and custom metadata.

## Samples

The repository includes complete projects with manifests, Java beans, JUnit tests, JVM distributions, and native targets:

- [Pkl configuration](https://github.com/elide-dev/elide/tree/main/tools/smoketests/micronaut-pkl)
- [Authored JSON resources](https://github.com/elide-dev/elide/tree/main/tools/smoketests/micronaut-resources)

This integration uses Java annotation processing. Kotlin-source processing through KSP is not yet provided; kapt runs
with a [managed or custom toolchain](https://elide.help/docs/toolchain/jvm/kotlinc#choose-a-toolchain). Kotlin can consume beans compiled from Java.

---

# Spring Boot

URL: https://elide.help/docs/toolchain/jvm/spring

> Build, run and test Spring Boot applications with elide.pkl: declare starters, package a JVM distribution, and adopt an existing application.

Build Spring Boot applications with `elide build`, run them with `elide run`, and execute their JUnit tests with
`elide test`. The project manifest declares Spring starters, the application's main class and its packaged artifacts.

## Start a new application

Generate a Java application with a runnable JVM distribution and an optional context test:

```shell
elide init --plain --skip-defaults --skip-run --template spring project_name=my-app
elide install
elide build :app
elide test
elide run
```

Run initialization in an empty project directory. Use `package=dev.acme` and `main_class=Application` to customize
Java names, or `tests=false` to omit the test. See [Project setup](https://elide.help/docs/projects) for interactive initialization.

## Configure an Elide build

For a concrete starting point, use the Java [Spring REST Service sample at this revision](https://github.com/spring-guides/gs-rest-service/tree/3f4cef01152596c19bc4d37939409358812b1421/complete).
Put this manifest in its `complete/` directory. It preserves that sample's Java 17 target and Spring Boot 4.0.8
dependencies; use your own main class and dependency versions when adapting it to another application.

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm

name = "rest-service-complete"
version = "0.0.1-SNAPSHOT"

dependencies {
  spring {
    version = "4.0.8"
    starter { "webmvc" }
    testStarter { "webmvc-test" }
  }
}

jvm {
  main = "com.example.restservice.RestServiceApplication"
  target = 17
  java {
    source = 17
    release = 17
  }
}

artifacts {
  ["jar"] = new Jvm.Jar {
    name = "rest-service"
  }
  ["app"] = new Jvm.JvmApplication {
    name = "rest-service"
    from { "jar" }
    options {
      archives { "zip" }
    }
  }
}
```

## Run and test

From the directory containing `elide.pkl`:

```shell
elide install
elide build :app
elide test
elide run
```

`elide build :app` compiles the application, builds its JAR and assembles the distribution with runtime dependencies.
Use `elide build` to build every declared artifact. `elide run` launches the application's configured main class
from that distribution. For this sample, check `http://localhost:8080/greeting` from another terminal.

The distribution lives in `.dev/artifacts/install/rest-service/`, with JARs in `lib/` and start scripts in `bin/`.
Its ZIP archive is written to `.dev/artifacts/distributions/`. To launch the installed tree directly on a machine
with a compatible JDK:

```shell
.dev/artifacts/install/rest-service/bin/rest-service
```

On Windows, use `bin/rest-service.bat` inside the distribution. See [JAR assembly](https://elide.help/docs/toolchain/jvm/jar) for distribution
options, JVM flags and additional files.

JUnit tests in `src/test/java` use the production resources and test dependencies. Elide provides a JUnit runner by
default. If the application pins its own JUnit platform, disable `jvm.features.testing` and declare a compatible
`junit-platform-console` in `testPackages`; see [Testing](https://elide.help/docs/toolchain/testing).

## Dependencies and resources

`starter { "webmvc" }` expands to `org.springframework.boot:spring-boot-starter-webmvc:4.0.8` in production
dependencies. `testStarter` adds the corresponding starter to test dependencies. Use the starter names offered by
your Spring Boot version, and keep the version aligned with the original build.

Declare non-starter artifacts, such as database drivers or `spring-boot-devtools`, in the ordinary
[Maven dependency buckets](https://elide.help/docs/toolchain/dependencies#maven-buckets). Preserve the versions and scopes selected by your
original build; the shorthand only adds starter coordinates. It does not execute Spring's build plugins.

Conventional `src/main/java`, `src/main/resources` and `src/test/java` directories need no `sources` declaration.
Keep `application.properties` or `application.yml` in `src/main/resources`; Elide includes those resources on
the application's classpath and in its JAR. Use [source sets](https://elide.help/docs/toolchain/source-sets) for a different layout.

For Kotlin, also preserve the compiler version, reflection dependency and Spring/all-open plugin configuration.
The [Kotlin compiler reference](https://elide.help/docs/toolchain/jvm/kotlinc) describes compiler plugins and toolchain selection.

## Adopt an existing application

For an existing project, [`elide adopt`](https://elide.help/docs/toolchain/usage/adopt) can generate the manifest. Commit the project and run its
original build first, then start the interactive migration:

```shell
elide adopt
```

Choose **Elide build**. Review the generated main class, Java target, dependency versions and scopes, resources,
tests and artifacts. Run `elide build`, `elide test` and `elide run`, and check the application's readiness endpoint.
The [adoption guide](https://elide.help/docs/toolchain/usage/adopt) documents harness selection and non-interactive use.

Java Spring Petclinic and Spring REST Service projects are covered by the adoption evaluations. Custom plugins,
generated sources and multi-module builds need their own validation; see [Which projects it fits](https://elide.help/docs/toolchain/usage/adopt#which-projects-it-fits).

Compare resolved dependencies with `elide classpath --json main:runtime test:runtime`, and use explicit Maven
[version resolutions](https://elide.help/docs/toolchain/dependencies#maven-version-resolutions) when the application needs a particular version.

## Packaging and native images

The manifest above produces an ordinary JAR and a JVM application distribution. Spring Boot's nested-dependency
executable JAR layout comes from its [repackage goal](https://docs.spring.io/spring-boot/maven-plugin/packaging.html).
Use an external Maven or Gradle build for Spring-specific tasks such as that packaging format, build metadata,
SBOM generation or Boot container tasks.

Compiling a Spring application to a native executable also requires Spring's AOT processing and reachability
metadata. Declaring an Elide [Native Image artifact](https://elide.help/docs/toolchain/jvm/native-image) does not run those Spring build tasks.
Keep the application's configured native build and follow
[Spring's native application guide](https://docs.spring.io/spring-boot/how-to/native-image/developing-your-first-application.html)
for its AOT lifecycle and toolchain requirements.

## See also

- [JAR assembly and application distributions](https://elide.help/docs/toolchain/jvm/jar)
- [Adopt an existing project](https://elide.help/docs/toolchain/usage/adopt)
- [Dependencies](https://elide.help/docs/toolchain/dependencies) and the [manifest reference](https://elide.help/docs/elide-pkl-reference)
- [JVM toolchain](https://elide.help/docs/toolchain/jvm)

---

# Native Maven

URL: https://elide.help/docs/toolchain/jvm/native-maven

> Run Apache Maven 4 builds with `elide mvn` without a separate Maven or JDK install: flavors for plain and Spring Boot projects, modes and output.

`elide mvn` runs Apache Maven 4 builds without a separate Maven or JDK install.

For application setup, tests and packaging, see the [Spring Boot guide](https://elide.help/docs/toolchain/jvm/spring).

## Run a build

```bash
elide mvn -- package
elide mvn -- -f app/pom.xml clean install
elide mvn -- --version
```

Everything after `--` goes to Maven, except `--flavor`, `--mode`, `--yes` and `--porcelain`, which `elide mvn`
handles. The project root is the nearest `.mvn` directory above `-f`/`--file` or the working directory.

## First run

Each flavor is a one-time download, prompted on first use:

```terminaloutput
Native Maven component 'generic' is not installed. Download it now? [Y/n]
```

Images install to `lib/maven/bin/` in the Elide home. Non-interactive sessions download without asking; in a
terminal, `--yes` skips the prompt:

```bash
elide mvn -- --yes package
```

| Platform | Architecture |
| --- | --- |
| Linux | x86_64, aarch64 |
| macOS | aarch64 |
| Windows | x86_64 |

## Flavors

A flavor is the set of Maven plugins that run natively.

| Flavor | Plugins | For |
| --- | --- | --- |
| `generic` | Default lifecycle: clean, resources, compiler, surefire, jar, install, deploy | Plain Java or Kotlin projects |
| `spring@4.1.0` | Everything a [Spring Initializr](https://start.spring.io/) Boot 4.1 project uses | Spring Boot 4.1.x |
| `spring@4.0.7` | Same, for Boot 4.0 | Spring Boot 4.0.x |

Elide picks the `spring` flavor that matches the `major.minor` of the `spring-boot-starter-parent` parent or
`spring-boot-maven-plugin` version in `pom.xml` (Boot `4.1.3` → `spring@4.1.0`). Otherwise, including for `${…}`
placeholders, it uses `generic`. To override:

```bash
elide mvn -- --flavor spring@4.1.0 package
elide mvn -- --flavor=spring@4.0.7 -f app/pom.xml install
```

## Modes

`--mode=<value>` (or `-Dnmvn.mode=<value>`; the flag takes precedence) sets what runs plugins outside the flavor:

```bash
elide mvn -- --mode=mixed package
```

| Mode | Behavior |
| --- | --- |
| `native` (default) | Only flavor plugins run. A missing plugin fails early, naming the flavor that has it and suggesting `--mode=mixed`. |
| `mixed` | Flavor plugins run natively; other goals run one at a time on a JVM in the same process. |
| `legacy` | The whole build runs as plain Apache Maven on the in-process JVM, as a baseline. |

`mixed` and `legacy` download a Maven distribution into `lib/maven/` on first use. No separate JDK is needed.

### Mixed mode limits

- Each delegated goal adds about 0.2 s after a one-time startup. If most goals are delegated, pick a flavor with more
  of their plugins.
- A delegated goal's artifacts are not attached to the session. If the jar plugin is not in the flavor, run
  `package`, not `install` or `deploy`.
- Command-line plugin configuration is passed to delegated goals only as `-D` properties.

## Output

A terminal shows a status line (plugin, goal, version, module), then a phase summary and build time; failures print
the full Maven log. `--porcelain` streams Maven's own output, as do verbose, debug and non-interactive runs:

```bash
elide mvn -- --porcelain package
```

## Inspect an installed image

```bash
<elide-home>/lib/maven/bin/nmvn-generic --info
<elide-home>/lib/maven/bin/nmvn-spring-4.1.0 --info=plugins
```

`--info` prints the flavor, variant and plugins; `--info=plugins`, `--info=flavor` or `--info=variant` prints one.

## Compatibility

Native Maven reads the same `pom.xml` and follows the same lifecycle as Apache Maven 4. Plugin coverage is limited to
the published flavors. Compilation runs in-process; plugins that fork the compiler use Elide's `javac`.

---

# Java compiler

URL: https://elide.help/docs/toolchain/jvm/javac

> Compile Java 25 source with `elide javac` or in an Elide project build, without a JDK install: ABI headers, C header bindings, JAR output and compiler options.

Elide bundles `javac` for Java 25; no separate JDK is needed.

## Compile source files

```bash
elide javac -- -d out src/Hello.java
elide java -- -cp out Hello
```

<img src="https://elide.help/assets/demos/javac.gif" alt="Compiling and running Java source with Elide" width="1591" height="728" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`javac` options go after `--`. Without `-d`, class files land beside their sources. `elide javac -- -help` lists
every `javac` option.

## Elide options

Elide options go before `--`:

| Option | Purpose |
| --- | --- |
| `--jar PATH` | Pack the output into a JAR at `PATH`. |
| `--manifest FILE` | Manifest for the `--jar` output. |
| `--max-errors N` | Errors shown before the rest are counted; `0` shows all. Warnings are de-duplicated and never limited. |
| `--report-used-deps PATH` | Write the classpath entries the compiler read, supertypes included (Bazel strict deps). |
| `--jdeps PATH` | Write a Bazel `.jdeps` proto: each classpath entry explicit, implicit or unused, with the classes used from it and their SHA-256 hashes. |
| `--target-label LABEL` | Target label recorded in the `--jdeps` proto. |
| `--unused-inputs PATH` | Write the classpath entries the compile neither used nor searched (Bazel `unused_inputs_list`). |
| `--capabilities` | Print compiler capabilities as JSON. |
| `--persistent_worker` | Run as a Bazel persistent worker, singleplex or multiplex. |
| `--classpath-cache` | Worker only: reuse classpath state across compiles. `ELIDE_WORKER_CLASSPATH_CACHE=0` turns it off. |
| `--incremental` | Worker only: reuse unchanged implementation classes across requests. |
| `--abi-only` | Write only an ABI jar, to `--emit-abi`, `--jar` or `-d`, without compiling bodies. |
| `--emit-abi PATH` | Also write an ABI jar (or directory) next to the full compile. |

```bash
elide javac --jar target/app.jar -- src/Main.java src/Util.java
elide javac --jar target/app.jar --manifest src/MANIFEST.MF -- src/Main.java
```

### ABI jars

```bash
elide javac --abi-only --emit-abi header.jar -- src/Main.java src/Util.java
elide javac --emit-abi header.jar -- -d out src/Main.java src/Util.java
```

An ABI (header) jar holds the public, protected and package-private signatures, constants and annotations
that dependents compile against. It contains no implementation bodies and is a compile-time input, not a runnable JAR.
Private implementation details are omitted. A body-only edit leaves the header byte-identical unless an annotation
processor changes the generated API.

`--abi-only` compiles headers directly from source without checking method bodies. `--emit-abi` runs a header compile
alongside the full javac compile; the full compile still checks bodies and produces the runnable classes. Use separate
output paths for implementation and header output. A `.jar` destination writes an archive; another destination writes
class files to a directory.

For a library and its consumer:

```bash
elide javac --emit-abi lib-abi.jar -- -d lib-classes src/library/Api.java
elide javac -- -cp lib-abi.jar -d app-classes src/app/Main.java
elide java -- -cp app-classes:lib-classes app.Main
```

The consumer compiles against `lib-abi.jar` and runs against `lib-classes`. Classpath examples use `:` on macOS/Linux;
use `;` on Windows. Both JAR and class-directory dependency inputs work. Pass the dependency classpath explicitly with
`-cp`/`--class-path`, or set `CLASSPATH`; the header compiler does not use the current directory as an implicit classpath.

`--release`, `-source` and `-target` set the header's language/class-file level; the default is Java 25. Header compilation
resolves platform types against the bundled JDK, including when `--release` names an older JDK. It does not validate
that an API exists in that older release. Run the full javac compile with `--release` to enforce that API boundary and
check method bodies.

### Annotation processing in headers

Explicitly enabled annotation processors run during header compilation, so their generated types can be included.
Use `-processor` to name processors, or `-processorpath`/`--processor-path` to discover them. With `-proc:full` and no
processor path, discovery uses the classpath. `-proc:none` disables processing.

```bash
elide javac --abi-only --emit-abi lib-abi.jar -- \
  -cp annotations.jar --processor-path processor.jar -processor example.GenerateApi \
  src/library/Api.java
```

The processor path must include the processor's dependencies. Header processing presents declarations without
implementation bodies; processors that inspect javac implementation details or method bodies require separate
compatibility checks. `--emit-abi` runs processors independently in the header and full compiles, so a processor may
execute twice. Java annotation processing support also depends on the distribution: inspect `elide javac --capabilities`
before wiring a processor-dependent build.

## Build projects

`elide build` compiles `src/main/java` and `src/test/java`, or the [source sets](https://elide.help/docs/toolchain/source-sets) that
`elide.pkl` declares. To compile only `main`:

```bash
elide build compile-java-main
```

```pkl
jvm {
  target = 25
  java {
    release = 25
    compiler {
      mode = "embedded"
      flags { "-Xlint:all" }
    }
  }
  features {
    graalvm = false
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `jvm.target` | Bytecode target; the `--release` level when `java.release` is unset. | `"auto"` (21) |
| `jvm.java.release` | `--release` level: compile against that JDK's API only. | `"auto"` |
| `jvm.java.source` | Use `--source`/`--target` instead of `--release`; ignored when `release` is set. | `"auto"` |
| `jvm.java.compiler.mode` | `"embedded"` uses Elide's `javac`; `"external"` runs the one in `jvm.javaHome`. | `"embedded"` |
| `jvm.java.compiler.flags` | Extra `javac` flags; `--release`, `-source` or `-target` here replaces Elide's. | none |
| `jvm.java.sourceSets["<set>"].release` | `--release` level for that source set alone. | `"auto"` (the project's) |
| `jvm.java.sourceSets["<set>"].flags` | `javac` flags for that source set, after `compiler.flags`. | none |
| `jvm.javaHome` | Java home for external compiles and forked JVMs. | Elide's own |
| `jvm.debug` | Compile with `-g`. | `true` |
| `jvm.features.graalvm` | Put `org.graalvm.nativeimage`, `word` and `collections` on the compile classpath. | `false` |
| `jvm.features.automodules` | Put JARs without a module descriptor on the module path as automatic modules. | `true` |

A source set that needs different settings, such as one compiled against `java.base` alone, names them under
`sourceSets`. Naming a source set the project does not have fails the build.

```pkl
sources {
  ["desktopless"] { paths { "src/desktopless/java" } }
}
jvm {
  java {
    sourceSets {
      ["desktopless"] {
        flags { "--limit-modules"; "java.base" }
      }
    }
  }
}
```

Each compile writes its arguments to `javac.args` beside its output. Annotation processors: [Maven Dependencies](https://elide.help/docs/toolchain/jvm/maven#annotation-processors).

## C header bindings

From 1.6.2, embedded javac can generate Java FFM bindings from C headers and compile them alongside
application sources. Generated Java stays in memory unless source export is requested. For separate source generation,
filtering options and native library loading, see [jextract](https://elide.help/docs/toolchain/native/jextract).

For example, put this declaration in `native/include/example.h`:

```c
struct Point { int x; };
int sum(int a, int b);
```

Save the application as `src/main/java/NativeClient.java`; it can import generated types in the same compile:

```java
import example.ffi.NativeApi;
import example.ffi.Point;

public class NativeClient {
  public long pointSize() { return Point.sizeof(); }
  public int sum(int a, int b) { return NativeApi.sum(a, b); }
}
```

Generating and compiling these bindings needs the header, not a built implementation of `sum`. Calling `sum` at runtime
needs the native library and native access enabled. [C compiler](https://elide.help/docs/toolchain/native/cc) describes the separate C compilation
surface.

Declare named groups in `elide.pkl` and select each group in its owning Java source set:

```pkl
jvm {
  java {
    release = 25
    bindings {
      ["example"] {
        headers { "native/include/**/*.h" }
        packageName = "example.ffi"
        headerClassName = "NativeApi"
        includeDirs { "native/include" }
        libraries { "example" }
      }
    }
    sourceSets {
      ["main"] { bindings { "example" } }
    }
  }
}
```

`headers`, `packageName`, and `headerClassName` are required. `includeDirs`, `defines`, and `libraries`
default to empty lists; `useSystemLoadLibrary` defaults to `false`. Paths belong to the declaring
project, including workspace members. Globs expand in sorted order and must match a file.
A group has one owning source set; tests and other source sets inherit its classes through `dependsOn`.
Declarations alone do not select groups.

```bash
elide build
elide javac -- --bindings example -d out src/main/java/NativeClient.java
elide javac -- --jextract 'native/include/*.h' \
  --jextract-package example.ffi --jextract-class NativeApi \
  --jextract-include-dir native/include --jextract-library example \
  -d out src/main/java/NativeClient.java
```

Repeat `--bindings` to combine named groups. Repeat `--jextract`, `--jextract-include-dir`,
`--jextract-define`, and `--jextract-library` to add headers, search directories, preprocessor
definitions, and library names to an ad hoc group. `--jextract-use-system-load-library` selects
`System.loadLibrary`-based loading for that ad hoc group; the corresponding Pkl property is `useSystemLoadLibrary`.
Named and ad hoc groups can be combined; ad hoc flags do not alter named groups. These options also work inside javac
argument files.
Quote globs so Elide expands them. Ad hoc javac paths resolve against the working directory.

Builds accept the same options using `--option=value`, for example `--bindings=example`.
Add `--bindings-source-set=<name>` to choose the source set receiving
CLI additions; it can be omitted only when there is one production source set. Build CLI paths resolve
against the selected project root, including when using `--project`.

```bash
elide build --bindings=example --bindings-source-set=main
elide build --jextract='native/include/*.h' --jextract-package=example.ffi \
  --jextract-class=NativeApi --jextract-include-dir=native/include \
  --jextract-library=example --bindings-source-set=main
```

A bindings-only Java source set is valid. Keep an owning source set's selections in Pkl for normal builds; CLI selections
add to the configured groups for that invocation. Unknown groups, unmatched globs and conflicting generated type names
fail before application compilation. Generated Java participates in normal javac annotation processing, and compiling it
with `-proc:none` still works.

To export sources for an IDE:

```bash
elide build --emit-bindings
elide build bindings-main --emit-bindings
elide javac -- --bindings example --emit-bindings generated-bindings -d out src/main/java/NativeClient.java
```

The `bindings-main` target generates and exports bindings without compiling the application. Build
exports live under the project's build directory at `jvm/generated-sources/<source-set>/jextract/<group>/`.
IntelliJ export marks emitted roots as generated sources, preserving each source set's test status.
Source JARs include the generated Java. Successful exports remove stale owned files and preserve
unrelated files; failed generation retains the previous export. A direct javac export uses
`<directory>/<group>/…`, with `adhoc` as the group name for CLI header selections. Exported sources are for IDEs and
source artifacts; Elide compiles the in-memory sources rather than reading that export back in.

Each build prepares bindings again before deciding whether Java compilation is up to date. Changes in transitive
headers or preprocessor results therefore affect compilation even when the top-level header has not changed. Unchanged
generated sources allow the Java compile to remain cached.

Bindings require Java 23 or later, embedded javac, and a build with native tools enabled. Classpath
projects and single-module compilation are supported; external javac and multi-module source-path
compilation are rejected. The owning source set must contain no Kotlin: put bindings in a separate
Java source set and depend on it from Kotlin. Elide does not raise the configured Java release,
package native application libraries, or enable runtime native access automatically.

## Bazel persistent workers

`elide javac --persistent_worker` and `elide kotlinc --persistent_worker` keep one compiler warm across Bazel actions.
Rules, setup and a worked example: [Bazel](https://elide.help/docs/build-tools-bazel#persistent-workers).

Start Java incremental workers with `elide javac --persistent_worker --incremental`.
Selective compilation requires explicit `-proc:none`, `-sourcepath ""`, and a classpath without empty or wildcard
entries. Use an empty directory as the classpath when there are no dependencies. Processors, plugins, named modules,
and other unsupported configurations use full compilation with the requested flags.

Body-only edits can reuse unchanged classes; declaration, source-set, or dependency changes trigger a full compile.
Each successful request publishes complete class, jar, and requested ABI outputs, even if public outputs were deleted
between requests. Failed compilation preserves the previous outputs. State belongs to the worker: restarting it
starts a cold compile. Pass the complete source list on every request.

## Samples

- [Java records and streams](https://elide.help/docs/code-samples#java-records-and-streams)

Start from a template:

```bash
elide init --template java        # Java app with a JUnit test
```

---

# Kotlin compiler

URL: https://elide.help/docs/toolchain/jvm/kotlinc

> Compile Kotlin 2.5 with `elide kotlinc` or in an Elide project build, with built-in compiler plugins such as serialization and Metro, and ABI jars.

Elide bundles Kotlin 2.5.0-Beta2. A runtime-only distribution reports that `kotlinc` needs the full distribution.

## Compile source files

```kotlin
// Hello.kt
fun main() = println("Hello!")
```

```bash
elide kotlinc -- -d out Hello.kt
elide java -- -cp out HelloKt
```

<img src="https://elide.help/assets/demos/kotlinc.gif" alt="Compiling and running Kotlin source with Elide" width="1591" height="546" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

`kotlinc` options go after `--`; Elide options go before it. `elide kotlinc --help` lists Elide's,
`elide kotlinc -- -help` lists `kotlinc`'s.

`elide java` does not add the Kotlin standard library, so code that calls it (`listOf`, `joinToString`) fails there:

```kotlin
fun main() = println(listOf("Hello", "Kotlin").joinToString(" "))
```

| Command | Result |
| --- | --- |
| `elide kotlinc -- -d out Hello.kt` then `elide java -- -cp out HelloKt` | `NoClassDefFoundError: kotlin/collections/CollectionsKt` |
| `elide kotlinc -- -include-runtime -d hello.jar Hello.kt` | Compilation fails |
| `elide run Hello.kt` | `Hello Kotlin` |
| `elide build` with a [`Jvm.JvmApplication`](https://elide.help/docs/toolchain/jvm/jar#runnable-application-distributions) artifact | Start script with the standard library in `lib/` |

## Elide options

| Option | Purpose |
| --- | --- |
| `--incremental` | Keep incremental state in `.dev/artifacts/kotlinc/incremental/`, keyed by output path. |
| `--incremental-cache-dir DIR` | Store incremental state in `DIR`. |
| `--plugins LIST` | Enable exactly these built-in plugins: `metro`, `serialization`, `atomicfu`, `power-assert`, `compose`. |
| `--metro`, `--no-metro` | Force the Metro DI plugin on or off. |
| `--compose`, `--no-compose` | Force the opt-in Compose compiler plugin on or off; requires a Compose runtime dependency when enabled. |
| `--tests` | Enable the test plugins (power-assert). |
| `--max-errors N` | Errors shown; `0` shows all. Warnings are de-duplicated and never limited. |
| `--report-used-deps PATH` | Write the classpath entries the compiler read, supertypes included (Bazel strict deps). |
| `--jdeps PATH` | Write a Bazel `.jdeps` proto: each classpath entry explicit, implicit or unused, with the classes used from it and their SHA-256 hashes. |
| `--target-label LABEL` | Target label recorded in the `--jdeps` proto. |
| `--persistent_worker` | Run as a Bazel persistent worker, singleplex or multiplex. |
| `--abi-only` | Write only an ABI jar to `-d`, skipping code generation for non-inline bodies. |
| `--unused-inputs PATH` | Write the classpath entries the compile neither used nor searched (Bazel `unused_inputs_list`). |
| `--toolchain-home DIR` | Run the compiler from an absolute Kotlin distribution directory, instead of the embedded compiler. |
| `--toolchain-classpath PATHS` | Run a managed compiler with its exact absolute jar classpath, separated by the platform path separator. Mutually exclusive with `--toolchain-home`. |
| `--report-abi PATH` | Atomically publish the selected compiler's complete opaque classpath snapshot after successful compilation. The path must be absolute. |

With the bundled compiler, `--incremental` can be combined with `--emit-abi` to publish a complete header on every
successful request, including requests with no implementation changes. Header generation performs a complete pass;
retain the implementation output directory together with its incremental cache. Pass the complete source list on
each request. A failed header compile leaves the previous header unchanged.

### Selected-toolchain workers

Persistent-worker requests select their compiler before `--`, using either `--toolchain-home` or
`--toolchain-classpath`. The worker keeps one isolated JVM per selection; it never adds Elide's embedded
compiler or plugin jars to that JVM. Compiler arguments and version-matched `-Xplugin` paths follow `--`.
A missing or incompatible selected compiler fails the request rather than falling back to the embedded compiler.

Managed classpaths must include the compiler's runtime dependencies; source/runtime dependencies still belong
in the compiler's `-classpath`. The worker uses the distribution's JDK to source-launch its compiler adapter.

Selected Kotlin 2.2.21 workers use that compiler's FIR incremental runner and classpath snapshots.
`--incremental` requires a directory output, not a jar. In persistent incremental requests,
`--transactional-incremental` preserves healthy compiler caches and class files after a source error when
the compiler confirms rollback; `--warm-incremental` runs two additional source-change rounds to warm the
incremental path. ABI reports are compiler-version-specific opaque bytes, not ABI jars, and failed compiles
leave the previous report unchanged.

For kapt, submit plain requests without `--incremental`: first `aptMode=stubs`, then, if processing is needed,
`aptMode=apt`. Keep the same handwritten Kotlin and Java snapshot arguments and private `stubs` directory
for both requests. Kapt's apt-only mode skips Kotlin analysis and collects the saved stubs itself; replacing
the compiler arguments with the stub files drops handwritten Java inputs. Keep generated `sources` and
`classes` directories private too, and compile generated sources separately after successful processing.

### ABI jars

```bash
elide kotlinc --abi-only -- -d header.jar src/**/*.kt
elide kotlinc -- -d app.jar --emit-abi header.jar src/**/*.kt
```

The jar holds public and protected signatures, `@Metadata`, ABI-relevant `inline` bodies, `const` values and
default-argument markers, including declarations that compiler plugins generate, such as kotlinx.serialization's
`$serializer`. The ABI output is a compile-time input; run programs against the full implementation classes and
runtime dependencies.

`--abi-only` writes only the ABI jar. Body stripping is enabled by default: the compiler still analyzes the sources,
but skips most lowering and code generation for non-inline bodies. It retains bodies needed by consumers, including
`inline` functions. This mode does not replace a full compile when validating a release.

`--emit-abi PATH`, after `--`, writes a header alongside a full compile. Either output can be a `.jar` or a directory.
The header-only mode avoids implementation-generated synthetic members that can appear in a header from a full compile,
so the two modes need not produce identical bytes for the same sources. Body-only edits leave the stripped header
unchanged; edits to `inline` bodies, constants or signatures can change it.

```bash
elide kotlinc --abi-only -- -jvm-target 21 -d lib-abi.jar Library.kt
elide kotlinc -- -jvm-target 21 -cp lib-abi.jar -d consumer.jar Consumer.kt
elide kotlinc -- -jvm-target 21 -d lib.jar Library.kt
```

Use `lib.jar` at runtime, along with the Kotlin standard library and other runtime dependencies. Passing the header
alone to `elide java` does not provide an implementation.

For mixed Kotlin/Java inputs, both ABI modes include Java declarations in the header. The Java header resolves against
the Kotlin header and the supplied classpath; `-jvm-target` sets its class-file target. A normal full Kotlin compile
reads `.java` files for resolution but does not emit their implementation classes: compile those separately with
`elide javac`. Java annotation processors are not run by this mixed-source header step.

`ELIDE_KOTLINC_ABI_STRIP=0` disables body stripping for `--abi-only`, running full code generation before keeping the
header. This is a diagnostic fallback and does not turn the output into a runnable implementation. Workers accept the
setting per request.

## Built-in compiler plugins

Elide ships the plugins below, each pinned to the compiler that loads them. A
project toggles them in the manifest; `elide kotlinc` takes `--plugins LIST` or
the matching `--<name>` / `--no-<name>` flag.

| Plugin | Manifest switch | Default |
| --- | --- | --- |
| kotlinx.serialization | `kotlin.features.serialization` | On |
| AtomicFU | `kotlin.features.atomicfu` | On |
| Power-Assert | `kotlin.features.powerAssert` | On |
| Metro (DI) | `kotlin.features.metro` | On for `elide build`, explicit for `elide kotlinc` |
| Compose | `kotlin.features.compose` | Off; `defaultPlugins` does not turn it on |

`kotlin.features.defaultPlugins = false` turns off the default suite.

### Compose

Compose is opt-in because the Compose compiler fails any module whose classpath
has no Compose runtime, whether or not the sources declare `@Composable`. Enable
it alongside a Compose runtime dependency, which Elide does not supply:

```pkl
kotlin {
  features {
    compose = true
  }
}
```

`elide kotlinc` reads the same switch, so the two agree for one project; pass
`--compose` (or `--plugins=compose`) to request it without a manifest, and
`--no-compose` to force it off.

Plugin options pass through `kotlin.plugins`, keyed by the compiler plugin id:

```pkl
kotlin {
  plugins {
    ["androidx.compose.compiler.plugins.kotlin"] {
      ["reportsDestination"] = "build/compose-reports"
    }
  }
}
```

Like AGP's debug variant, `elide build` adds `sourceInformation=true` for modules
that are compiled for a debug Android application, so previews and inspectors can
locate each composable call. A module is debug when it declares an application
(`Android.AndroidApk` or `Android.AndroidAab`) with `release = false`. A module that declares no
application is debug when a workspace project that depends on it, directly or
through other members, declares one. Other modules keep the compiler default, so
release APKs carry no source information. A `sourceInformation` entry in
`kotlin.plugins` takes precedence, and `elide kotlinc` never adds the option.

## Build projects

`elide build` compiles Kotlin source sets found by convention or declared in `elide.pkl`.

```pkl
kotlin {
  apiLevel = "auto"
  languageLevel = "auto"
  compilerOptions {
    allWarningsAsErrors = true
    optIn { "kotlin.time.ExperimentalTime" }
    freeCompilerArgs { "-Xcontext-parameters" }
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `kotlin.apiLevel`, `kotlin.languageLevel` | `"2.2"` … `"2.5"`, `"latest"` or `"stable"`. | `"auto"` |
| `compilerOptions.optIn` | Markers passed as `-opt-in`. | none |
| `compilerOptions.progressiveMode`, `.extraWarnings`, `.allWarningsAsErrors`, `.suppressWarnings`, `.verbose` | The matching `kotlinc` switches. | `false` |
| `compilerOptions.freeCompilerArgs` | Extra compiler arguments. | none |
| `compilerOptions.apiVersion`, `.languageVersion`, `.jvmTarget` | Per-compile versions; `"auto"` follows the project. | `"auto"` |
| `compilerOptions.javaParameters` | Emit parameter metadata for Java reflection. | `false` |
| `compilerOptions.jvmTargetValidationMode` | `"ERROR"`, `"WARNING"` or `"IGNORE"` on Kotlin/Java target mismatch. | `"ERROR"` |
| `compilerOptions.noStdlib`, `.noJdk` | Drop the stdlib or JDK from the classpath. | `false` |
| `compilerOptions.includeRuntime` | Unsupported: `true` fails the Kotlin compile. Package with a `Jvm.JvmApplication` artifact. | `false` |
| `compilerOptions.incremental` | Incremental project builds. | `true` |

Each compile writes its arguments to `kotlinc.args` beside its output.

### Plugins and features

| `kotlin.features` | Effect | Default |
| --- | --- | --- |
| `kotlinx` | KotlinX libraries on Kotlin dependency roots. | `true` |
| `defaultPlugins` | Built-in plugin suite. | `true` |
| `serialization` | kotlinx.serialization plugin and runtime. | `kotlinx && defaultPlugins` |
| `coroutines` | kotlinx.coroutines runtime. | `kotlinx` |
| `atomicfu` | kotlinx.atomicfu plugin and runtime. | `kotlinx && defaultPlugins` |
| `powerAssert` | Power Assert plugin. | `defaultPlugins` |
| `metro` | Metro DI plugin. | `defaultPlugins` |
| `compose` | Opt-in Compose compiler plugin; requires an explicit Compose runtime dependency. | `false` |
| `reflection` | Implicit `kotlin-reflect`. | `true` |
| `testing` | Kotlin test libraries on test sets. | `true` |

```pkl
kotlin {
  features {
    metro = false
  }
  plugins {
    ["org.jetbrains.kotlinx.serialization"] {
      ["mode"] = "json"
    }
  }
}

dependencies {
  maven {
    kotlinPlugins { "com.example:my-compiler-plugin:1.0.0" }
  }
}
```

- Each `plugins` entry becomes `-P plugin:<id>:<key>=<value>`, sorted by id and key.
- Third-party plugins go in the `kotlinPlugins` bucket and need a `ManagedKotlinToolchain` or
  `CustomKotlinToolchain`. The embedded compiler warns `Custom Kotlin compiler plugins are not supported when using the
  embedded compiler, plugins will not be applied` and compiles without them.
- A built-in plugin missing from the distribution is skipped, with its options, and warns.
- Implicit Kotlin libraries go only to dependency roots with Kotlin sources. `reflection = false` drops
  `kotlin-reflect`; `compilerOptions.noStdlib = true` drops it and the stdlib. Declared dependencies stay.
- `project("core").friend()` exposes a sibling's `internal` declarations; see
  [Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).
- A source set sees the `internal` declarations of the sets it depends on in the same project: every set named in its
  `dependsOn` (`main` for a test set that leaves it out), along with the sets those depend on.

### Choose a toolchain

```pkl
import "elide:Kotlin.pkl" as Kotlin

kotlin {
  toolchain = "embedded"                                       // the default
  // toolchain = new Kotlin.ManagedKotlinToolchain { version = "2.4.0" }
  // toolchain = new Kotlin.CustomKotlinToolchain { path = "/opt/kotlinc" }
}
```

| Toolchain | Behavior |
| --- | --- |
| `"embedded"` | Elide's bundled Kotlin. |
| `ManagedKotlinToolchain` | Downloads that version (prereleases too) with its stdlib, reflect, test libraries and Kotlin plugins. KotlinX, Metro and other third-party versions are unchanged; check they match. |
| `CustomKotlinToolchain` | A local Kotlin distribution; built-in plugins it lacks are skipped. |

The toolchain applies to project builds; `elide kotlinc` always uses the bundled compiler.

Project builds don't run annotation processors or KSP over Kotlin sources, except KAPT for Android projects with
`processors` declared: Kotlin code that uses generated types must get them from an upstream source set or project.
`elide kotlinc --kapt-sources` and `--ksp-output` (below) do this for command-line and Bazel builds.

## Annotation processors over Kotlin

```bash
elide kotlinc --kapt-sources gen.srcjar --kapt-classes gen.jar --processorpath dagger-compiler.jar -- \
  -cp deps.jar src/**/*.kt src/**/*.java
```

`--kapt-sources` runs Java annotation processors instead of compiling, so Kotlin code can use what they generate:
compile again with the generated sources added. Processors see the Kotlin declarations as classes from an ABI header,
with no stub generation, and the Java sources as sources. References to classes processors have yet to generate don't
stop processing; where one appears in a signature, processors see `Any?`, where KAPT shows `error.NonExistentClass`.

| Option | Purpose |
| --- | --- |
| `--kapt-sources PATH` | Write generated sources to this srcjar. |
| `--kapt-classes PATH` | Write generated classes and resources to this jar. |
| `--kapt-stubs PATH` | Write the Kotlin header processors read to this jar. |
| `--processorpath PATHS` | Processor classpath. |
| `--processors LIST` | Processor classes to run; otherwise discovered on the processor path. |
| `--processor-option K=V` | Processor option, like `javac -AK=V`; repeatable. |

## Kotlin Symbol Processing

```bash
elide kotlinc --ksp-output gen --processorpath moshi-kotlin-codegen.jar:moshi.jar -- -cp moshi.jar src/**/*.kt
```

`--ksp-output` (or either jar option) runs KSP2 symbol processors instead of compiling, then compile again with the
generated sources added.
KSP2 runs in the bundled toolchain and uses its Kotlin version. Supply KSP2 processors on `--processorpath` with each
processor's dependencies; Elide supplies the Kotlin standard library and KSP runtime. Providers are discovered through
`META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider` in those JARs. `--processors` selects
Java annotation processors for the separate `--kapt-sources` mode; it does not select KSP providers.

| Option | Purpose |
| --- | --- |
| `--ksp-output DIR` | Write generated Kotlin to `DIR/kotlin`, Java to `DIR/java`, resources to `DIR/resources`, classes to `DIR/classes`. |
| `--ksp-sources PATH` | Write generated Kotlin and Java sources to this srcjar. |
| `--ksp-classes PATH` | Write generated classes and resources to this jar. |
| `--processorpath PATHS` | Processor classpath. |
| `--processor-option K=V` | Processor option; repeatable. |

KSP options go before `--`; compiler source, classpath and target options go after it. The following example assumes a
processor JAR that generates `example.AppGenerated` from `src/App.kt`:

```bash
elide kotlinc --ksp-output gen --processorpath processor.jar:processor-deps.jar \
  --processor-option mode=production -- \
  -jvm-target 21 -cp annotations.jar src/App.kt
elide kotlinc -- -jvm-target 21 -cp annotations.jar -d app.jar \
  src/App.kt gen/kotlin/example/AppGenerated.kt
```

The first command only processes symbols; `-d` does not request an application compile in that mode. Add every generated
source needed by the second command. If the processor generates Java, pass those sources for Kotlin resolution and
compile them separately with `elide javac`, using the Kotlin output on its classpath. Copy generated resources into the
application's packaged resources; they are not compiled Kotlin sources.

Use archive outputs when a build system needs explicit processing artifacts:

```bash
elide kotlinc --ksp-sources gen.srcjar --ksp-classes gen.jar \
  --processorpath processor.jar:processor-deps.jar -- -cp annotations.jar src/App.kt
```

Either archive option activates KSP even without `--ksp-output`. The sources archive contains generated Kotlin and Java;
the classes archive contains classes and resources emitted by processors, not compiled application classes. Supplying
`--ksp-output` as well keeps the directory outputs too. KSP2 processing, Java annotation processing and Kotlin compiler
plugins are separate phases; project `kotlin.plugins` configuration does not schedule KSP. Project builds do not yet
run this processing phase automatically.

## Samples

- [Kotlin collections](https://elide.help/docs/code-samples#kotlin-collections)
- [Kotlin tests](https://elide.help/docs/code-samples#kotlin-tests)

Start from a template:

```bash
elide init --template ktjvm       # Kotlin app with a test
```

---

# Formatting

URL: https://elide.help/docs/toolchain/jvm/formatting

> Format Java and Kotlin with `elide format`, which runs the bundled google-java-format (or the Netflix jfmt dialect) and ktfmt, or run `elide javaformat` or `elide ktfmt` alone.

Elide bundles google-java-format 1.37.0, Netflix jfmt 0.9.0 and ktfmt 0.65. `elide format` runs the Java and Kotlin
formatters; `elide javaformat` and `elide ktfmt` run one.

```bash
elide format -- src
elide javaformat -- Hello.java src/main/java
elide ktfmt -- Hello.kt src/main/kotlin
```

<img src="https://elide.help/assets/demos/format.gif" alt="Formatting Java and Kotlin source files with Elide" width="1591" height="1128" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

Files and directories go after `--` and are rewritten in place. Each file is reported as unchanged, rewritten, would
be rewritten, or failed to parse. `javaformat` also accepts `-i`:

```bash
elide javaformat -- -i Hello.java
```

## Check formatting

`-n` or `--dry-run` after `--` writes nothing and exits 1 if a file would change. `--set-exit-if-changed` is
accepted; there is no `--check`.

```bash
elide format -- -n src
elide javaformat -- -n src/main/java
elide ktfmt -- -n src/main/kotlin
```

In check mode, two Elide options (before `--`) report what would change:

```bash
elide format --list-files -- -n src
elide format --list-diffs -- -n src
elide format --list-diffs=5 -- -n src
```

| Option | Output |
| --- | --- |
| `--list-files` | Paths that would change, one per line on stdout. |
| `--list-diffs=N` | Unified diffs when at most `N` files fail, otherwise paths. Use `=N`, not a separate value. |

Both work on `javaformat` and `ktfmt` too.

## Formatter flags

Everything after `--` is passed to the formatter, including argument files and style switches (`--google-style`,
`--kotlinlang-style`, `--aosp`):

```bash
elide ktfmt -- --google-style @kotlin-sources.txt
```

`elide javaformat --help` and `elide ktfmt --help` show Elide's options and how to show the formatter's help.

## Select project sources

With no paths after `--`, `elide format` formats the Java and Kotlin sources of the current project:

```bash
elide format
elide format --install -- --jfmt
elide format --install -- --jfmt -n
```

`--install` is an Elide option on `elide format`, before `--`. It runs the dependency installation step first and stops
if installation fails. Use it when jfmt needs project dependency types to resolve imports. To run only the Java
formatter with those dependencies, install first and name the Java sources:

```bash
elide install
elide javaformat -- --jfmt src/main/java
```

## jfmt dialect

`--jfmt` formats Java with [jfmt](https://github.com/Netflix/jfmt) instead of google-java-format: 4-space blocks,
8-space continuations, no column limit, braces around every statement body, and static imports after ordinary ones.

```bash
elide javaformat -- --jfmt src/main/java
elide format -- --jfmt -n src
```

Selecting jfmt changes Java formatting only; `elide format` still uses ktfmt for Kotlin files.

jfmt is a fixed style, so `--jfmt` cannot be combined with `--aosp`, `--fix-imports-only` or the `--skip-*` flags.

### Resolve and rewrite imports

Like upstream `jfmt`, Elide first runs jfmt's import pass over the files of a run: wildcard imports are expanded to the
types used and qualified type names are shortened. The pass attributes the files together with javac, so their
dependencies must be resolvable. Where upstream then fails the run, Elide warns, shows javac's errors and formats the
files without the pass. Name the dependencies with javac's options (`--class-path`, `--module-path`, `--release` and the
rest jfmt accepts). Without `--class-path`, each file is attributed against the class path `elide install` exported for
the project it belongs to; `elide format --install` runs `elide install` first, which returns quickly when nothing needs
installing. Classes from files outside the run resolve through the source roots the files' package declarations imply,
unless `--source-path` names others. Standard input is formatted without the pass, as upstream does.

For example, a file using `List` from `import java.util.*;` and declaring a field as
`java.time.Instant created = java.time.Instant.now();` receives explicit imports for `List` and `Instant`, and uses
`Instant` in the field declaration and initializer. This needs type resolution; ordinary whitespace formatting does not.
When the pass reports missing types, install the owning project's dependencies or pass an explicit classpath and rerun
to obtain the import rewrites. Formatting can otherwise succeed with the warning and leave those imports unresolved.

With no files named, `--source-path` selects every Java source under it, as `jfmt --source-path` does, in place of the
project's sources; `--module-source-path` only sets where the pass looks for sources.

```bash
elide javaformat -- --jfmt --class-path libs/widgets.jar src/main/java
elide format --install -- --jfmt
```

### Format a selection

`--lines`, `--offset` and `--length` select part of one file, as they do for google-java-format. jfmt formats only the
selected code, then sorts imports and removes unused ones over the whole file. Passes that rewrite the whole file are
skipped for a selection: the import pass above, adding braces around statement bodies, and repeating until the output
is stable.

```bash
elide javaformat -- --jfmt --lines 10:24 src/main/java/demo/Wild.java
elide javaformat -- --jfmt --offset 120 --length 80 src/main/java/demo/Wild.java
```

Line ranges are one-based and inclusive; offsets and lengths count characters. A selection is not a guarantee that
imports stay untouched: unused-import removal and import ordering still apply to the entire file. Run without selection
flags when you want the type-based import pass and brace insertion as well.

---

# OpenRewrite

URL: https://elide.help/docs/toolchain/jvm/rewrite

> List, preview and apply OpenRewrite recipes to Java sources with elide rewrite, add recipe dependencies, and use the code index to select files before parsing.

`elide rewrite` runs OpenRewrite recipes against an Elide project's main Java sources. Use it to automate source
changes, preview the diff, and apply the same recipe from the terminal or CI.

Experimental in 1.6.0; recipe compatibility hardening is planned for 1.6.1.

## Preview and apply a recipe

Run these commands from a project with an `elide.pkl` and Java sources:

```bash
elide rewrite --list
elide rewrite org.openrewrite.java.RemoveUnusedImports --dry-run
elide rewrite org.openrewrite.java.RemoveUnusedImports
elide test
```

`--list` prints available recipe names and display names. `--dry-run` prints the proposed diff without changing
source files. Omit it to apply the changes, then run your tests. Dependency resolution, indexing, and compilation
can still write build state during a dry run.

For a minimal project, create `elide.pkl`:

```pkl
amends "elide:project.pkl"

name = "rewrite-demo"
```

And `src/main/java/demo/Main.java`:

```java
package demo;

import java.util.List;

public class Main {
  public static void main(String[] args) {
    System.out.println("Hello");
  }
}
```

The `RemoveUnusedImports` recipe removes the unused `List` import. The preview leaves the file unchanged; after
applying it, a second run has no changes to make.

## Add recipe modules

Declare recipe JARs in `dependencies.maven.devPackages`. Replace the illustrative coordinate below with your
recipe module's published coordinate and version:

```pkl
dependencies {
  maven {
    devPackages {
      "com.example:rewrite-recipes:1.0.0"
    }
  }
}
```

Run `elide rewrite --list` again to discover the module's recipes. Elide discovers recipe classes and declarative
YAML recipes packaged under `META-INF/rewrite/` in those JARs. Select a declarative recipe by its declared name;
there is no CLI option to load a loose YAML file from the project directory.

Recipes run in the order named on the command line:

```bash
elide rewrite org.openrewrite.java.RemoveUnusedImports org.openrewrite.java.format.AutoFormat --dry-run
```

Elide resolves the recipe libraries separately from the project's application dependencies. Choose recipe modules
compatible with the bundled OpenRewrite 8.90.4; declaring a module that requests a newer core does not upgrade the
runner's core version.

## How the index is used

Elide's [code index](https://elide.help/docs/toolchain/jvm/code-index) supplies dependency type and member information to the Java parser
and the catalog used to discover recipes. A rewrite builds the needed dependency index layers automatically.

Before rewriting, Elide compiles the main Java and Kotlin sources and indexes their references. For supported
explicit type and method preconditions, it uses those references and source tokens to select candidate Java files
before OpenRewrite parses them. OpenRewrite still evaluates the recipe's preconditions on the selected files.

Filtering supports literal type and method searches in declarative preconditions and optional precondition
metadata supplied by recipe modules. Unsupported patterns or incomplete index data retain the full source set.
Recipes that need a project-wide scan also parse the full source set. A smaller candidate set reduces parsing
work, but compilation and indexing have their own cost.

To skip the compilation and filtering step:

```bash
elide rewrite org.openrewrite.java.RemoveUnusedImports --dry-run --no-prefilter
```

This parses every main Java source and still uses the dependency index for type information. It is useful when
comparing a filtered run or attempting a repair on sources that do not compile. `--list` also skips main-source
compilation.

## Options

| Option | Effect |
| --- | --- |
| `--list` | List available recipes and exit. |
| `--dry-run` | Print diffs without applying source changes. |
| `--no-prefilter` | Skip main-source compilation and candidate filtering. |
| `--offline` | Use locally available dependencies; fail if required artifacts are missing. |

The first run can download both project dependencies and recipe libraries. Prepare them with an online run before
using `--offline`. An unknown recipe exits `1`; invalid command usage exits `2`.

## Scope and limits

- Input files come from the main Java source set. Kotlin sources contribute compiled references, but are not
  rewritten; test source sets are not rewrite inputs.
- Recipes that read annotation values on dependency types are unsupported. Dependency type information also omits
  annotation defaults and parameter/type annotations.
- Workspace sibling JARs and dependencies supplied as filesystem paths are not included in the indexed dependency
  type information used by the parser.
- Recipe compatibility varies. Inspect the dry-run diff and run tests after applying changes.

## Maven, Gradle and Bazel projects

These commands use an `elide.pkl` project definition. The [Maven, Gradle and Bazel integrations](https://elide.help/docs/build-tools)
select compilers and other tools inside those builds; they do not import their dependency graphs into
`elide rewrite` or add a rewrite goal, task, or rule.

To use this workflow alongside an existing build, define the relevant source sets, target version, repositories,
and dependencies in an `elide.pkl`, or use [Adopt an existing project](https://elide.help/docs/toolchain/usage/adopt). Keep that definition in
sync with the build you use to test the result.

For code inspection without modifying sources, see [Dependency code index](https://elide.help/docs/toolchain/jvm/code-index).

---

# Dependency code index

URL: https://elide.help/docs/toolchain/jvm/code-index

> Build and query Elide's Maven dependency code index: resolve class origins, inspect types and members, and find outbound references or local Java and Kotlin callers.

`elide index` answers questions about code in your resolved Maven dependencies and compiled main Java and Kotlin
sources: which dependency defines a class, what a class references, and which local source files use a type or
member. [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) uses the same index for dependency types and candidate file selection.

Experimental in 1.6.0; compatibility hardening is planned for 1.6.1.

## Build the index

Run from an Elide project with `elide.pkl`:

```bash
elide index build --layers=l1,l2,l3
elide index status
```

`build` resolves dependencies, builds the requested dependency layers, and compiles the main Java and Kotlin
sources to refresh the local reference index. `status` reports the layers available for each resolved Maven
artifact; it does not list local classes.

For example, a project using Guava can declare:

```pkl
amends "elide:project.pkl"

name = "index-demo"

dependencies {
  maven {
    packages { "com.google.guava:guava:33.4.8-jre" }
  }
}
```

Add `src/main/java/demo/Main.java`:

```java
package demo;

import com.google.common.collect.ImmutableList;

public class Main {
  public static void main(String[] args) {
    System.out.println(ImmutableList.of());
  }
}
```

After building the index, the following queries inspect this dependency and its use in the project.

## Find the dependency that defines a class

```bash
elide index resolve com.google.common.collect.ImmutableList
```

The first result is the class address on the main compile classpath:

```text
maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList
```

If other indexed artifacts on that classpath define the same class, subsequent lines begin with `shadows` and name
those addresses. Resolution follows classpath order. If an earlier artifact lacks the required type index, the
command reports the missing layer instead of guessing which definition wins.

To print filesystem classpath entries, use [`elide classpath`](https://elide.help/docs/toolchain/source-sets#dependencies-and-classpaths).
The code index identifies definitions and code references; it does not print the transitive dependency path that
introduced an artifact.

## Inspect types and members

```bash
elide index get maven:com.google.guava:guava:33.4.8-jre
elide index get maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList
elide index get 'maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList#of()'
```

The artifact query lists indexed types. A type query prints its kind, visibility, supertypes, and archive entry;
a member query prints the matching member's kind, visibility, static/instance status, and JVM descriptor.

| Address | Identifies |
| --- | --- |
| `maven:group:artifact:version` | A resolved Maven artifact. |
| `maven:group:artifact:version/package.Type` | A type in that artifact. |
| `maven:group:artifact:version/package.Type#method(java.lang.String,int)` | A method, selected by parameter types. |
| `maven:group:artifact:version/package.Type#FIELD` | A field. |
| `local:project-name/package.Type` | A compiled local type, for `references`. |

Use binary type names (`package.Outer$Inner` for a nested class). Method keys omit the return type; constructors
use `<init>(...)`. Quote addresses with parentheses, `#`, or `$` to keep the shell from interpreting them.

## Follow outbound references

```bash
elide index references maven:com.google.guava:guava:33.4.8-jre/com.google.common.collect.ImmutableList
elide index references local:index-demo/demo.Main
```

`references` prints `type` and `member` lines for the types and members referenced by that compiled class. It takes
a type address, not a member address. In a local address, the project name is `name` from `elide.pkl` (or `project`
when unnamed).

## Find local uses

```bash
elide index used-by com.google.common.collect.ImmutableList
elide index used-by 'com.google.common.collect.ImmutableList#of'
elide index used-by 'com.google.common.collect.ImmutableList#of()'
```

`used-by` searches the compiled main-source reference index and prints matching package-relative source files,
such as `demo/Main.java`. A bare method name matches its overloads; a parameter list selects a signature. Results
are sorted and deduplicated. No matches produce no output and exit successfully.

The query covers local Java and Kotlin classes, not every dependency's callers. References erased during
compilation, unused imports, comments, and reflective uses named only by strings can be absent. Rebuild the index
after changing sources; a query does not compile them or refresh local references.

## Layers and refresh behavior

| Layer | Indexed information | Used by |
| --- | --- | --- |
| `l0` | Artifact entries and metadata | Artifact status and recipe discovery. |
| `l1` | Types, visibility, supertypes, and annotations | Type queries and class resolution. |
| `l2` | Fields, methods, constructors, and signatures | Member queries and rewrite type information. |
| `l3` | Outbound type and member references | Dependency `references` queries. |

`elide index build` defaults to dependency layers `l0,l1`. `--layers` selects layers to add; `l0` is always included,
and layers already built are retained. Include `l1,l2` together for member queries. The local reference index is
refreshed by `build` independently of the selected dependency layers.

Queries read existing index data. They may resolve project dependencies, but do not build missing index layers.
`get`, `references`, and `resolve` exit `1` for an unknown address or name. A missing required layer exits `2` and
prints a build command. Use `--offline` to prevent remote dependency downloads; required artifacts must already
be available locally.

Dependency index data lives under `.dev/dependencies/index/`, keyed by artifact content and index format version.
Local reference data lives under the project's build directory. Ordinary compilation does not request all index
layers; build them explicitly, or let a consumer such as OpenRewrite request what it needs.

## Scope and build-tool integration

The dependency index covers resolved Maven JARs without classifiers. npm, PyPI, arbitrary filesystem JAR paths,
and workspace sibling outputs are not dependency-index inputs. `resolve` searches indexed Maven artifacts on the
main compile classpath; it does not resolve local classes or JDK classes. Local addresses currently support
`references`, while `used-by` searches the local index by type/member name.

The commands use an `elide.pkl` project definition. Using Elide's compiler through the [Maven plugin](https://elide.help/docs/build-tools-maven),
[Gradle plugin](https://elide.help/docs/build-tools-gradle), or [Bazel rules](https://elide.help/docs/build-tools-bazel) does not populate this index from those
tools' dependency graphs. Define the matching sources and dependencies in an Elide project to use these queries.

See [Dependencies](https://elide.help/docs/toolchain/dependencies) for dependency declarations, and [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) for
applying recipes with the index.

---

# JAR assembly

URL: https://elide.help/docs/toolchain/jvm/jar

> Create, list and extract JARs with `elide jar`, and build JARs, sources and Javadoc JARs and runnable application distributions in an Elide project.

Elide creates and reads JAR files directly with `elide jar`, and builds them as project artifacts.

## Create, list and extract

`jar` options go after `--`:

```bash
elide jar -- --create --file app.jar -C out .                              # create
elide jar -- --list --file app.jar                                         # list
elide jar -- --extract --file app.jar --dir extracted                      # extract
elide jar -- --create --file app.jar --main-class com.example.Main -C out . # executable JAR
elide jar -- -help
```

## Compile and create a JAR

```bash
elide javac --jar target/app.jar -- src/Main.java src/Util.java
elide javac --jar target/app.jar --manifest src/MANIFEST.MF -- src/Main.java
```

## Project artifacts

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm

artifacts {
  ["app"] = new Jvm.Jar {
    name = "app"
    options {
      entrypoint = "com.example.Main"
    }
  }
}
```

`elide build` writes `.dev/artifacts/jar/<name>/`. The JAR holds every non-test source set's classes and resources.

### `Jvm.Jar`

| Property | Meaning | Default |
| --- | --- | --- |
| `name` | File name; `"app"` and `"app.jar"` both give `app.jar`. | the artifact key |
| `sources` | Source sets to package; empty means every non-test set. | none |
| `from` | Other workspace members' JARs to unpack into this one, each built first: `from { project("x") }`. Their manifests are dropped; their dependencies join this project's exported and published POM. | none |
| `resources` | Extra files: paths or `new { from = …; into = … }`. | none |
| `manifest` | Extra `META-INF/MANIFEST.MF` attributes. | none |
| `manifestFile` | Manifest file to use instead of a generated one. | — |
| `excludes` | Entries to omit: a pattern with `/ * ? [ ]` is a path glob; a dotted name is a package prefix. | none |
| `options.entrypoint` | `Main-Class`. | `jvm.main` |
| `options.compress` | Compress entries. | `true` |
| `options.defaultManifestProperties` | Add `Implementation-*` attributes. | `true` |
| `main` | Not read when packaging; use `options.entrypoint`. | — |
| `dependsOn` | Artifacts to build first. | none |

```pkl
artifacts {
  ["app"] = new Jvm.Jar {
    sources { "main" }
    excludes {
      "com.example.internal"   // a package and its subpackages
      "**/*.proto"             // a path glob
    }
    manifest {
      ["Implementation-Vendor"] = "Example"
    }
    resources {
      "LICENSE.txt"
      new { from = "config"; into = "META-INF/config" }
    }
  }
}
```

### Sources and Javadoc JARs

```pkl
artifacts {
  ["sources"] = new Jvm.SourceJar {
    classifier = "sources"
    excludes { "**/internal/**" }
  }
  ["javadoc"] = new Jvm.JavadocJar {
    windowTitle = "Example API"
    links { "https://docs.oracle.com/en/java/javase/25/docs/api/" }
    groups {
      ["Core"] { "com.example.core" }
    }
  }
}
```

| `Jvm.SourceJar` | Meaning |
| --- | --- |
| `sources` | Source sets to package; empty means every non-test set. |
| `classifier` | Inserted before the extension (`app-sources.jar`). |
| `includes`, `excludes` | Path globs over the sources. |

| `Jvm.JavadocJar` | Meaning |
| --- | --- |
| `sources` | Source sets to document; empty means every non-test set. |
| `groups` | Package groups: title to package list. |
| `links` | External documentation URLs. |
| `excludes` | Patterns to leave undocumented. |
| `windowTitle`, `docTitle` | Window and document titles. |
| `generator` | `"auto"` (default): Dokka when the sources include Kotlin, `javadoc` otherwise. `"javadoc"` or `"dokka"` picks one. |

Sources that include Kotlin are documented with [Dokka](https://kotlinlang.org/docs/dokka-introduction.html) instead of
`javadoc`, covering the Java beside them too; `generator = "javadoc"` documents only the Java files. Dokka runs as a
separate JVM process. Elide resolves its jars from Maven the first time a Kotlin javadoc JAR is built and caches them in
the local Maven repository, so that first build needs network access. On every build, Dokka also fetches the package
lists behind its links to the JDK, the standard library and `links`; `--offline` skips those lookups. Dokka reads
`sources`, `links` and `excludes` (an excluded package and its subpackages are left out); `groups` and the titles apply
to `javadoc` only, and Elide warns when titles are set for Dokka.

## Runnable application distributions

A `Jvm.JvmApplication` is a runnable tree, like Gradle's `application` plugin: runtime JARs in `lib/`, start scripts
in `bin/`, and optional archives.

```pkl
artifacts {
  ["dist"] = new Jvm.JvmApplication {
    from { "app" }
    entrypoint = "com.example.Main"
    defaultJvmArgs { "-Xmx512m" }
    contents {
      new { from = "config"; into = "etc" }
    }
    options {
      archives { "zip"; "tar" }
    }
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `from` | JAR artifacts with the app's code; empty means every declared JAR, or a JAR of the project's classes. | none |
| `name` | Directory and start-script name. | the artifact key |
| `entrypoint` | Main class. | `jvm.main` |
| `defaultJvmArgs` | JVM options in the scripts, after `jvm.flags`. | none |
| `executableDir` | Directory for the scripts. | `"bin"` |
| `contents` | Extra files in the root, in the same form as source-set resources. | none |
| `options.unixStartScript`, `options.windowsStartScript` | Generate each script. | `true` |
| `options.archives` | `"zip"` and/or `"tar"` (gzip). | none |
| `dependsOn` | Artifacts to build first. | none |

| Output | Path |
| --- | --- |
| Install tree | `.dev/artifacts/install/<name>/` |
| Archives | `.dev/artifacts/distributions/` |

- `elide run` launches the installed tree with the scripts' JVM options.
- Scripts also read `JAVA_OPTS` and `<NAME>_OPTS` (`sample-app` → `SAMPLE_APP_OPTS`).
- The POSIX script follows symlinks to itself; on Windows, run the script directly or via `PATH`.
- `name`, `version` (when archiving) and each `into` must be valid file names on every platform: no `/`, `\`,
  `:*?"<>|`, control characters, trailing dot or space, or Windows device names such as `NUL`. Invalid names fail the
  build before it writes.

Workspace members use a sibling's `Jvm.Jar` with `project("core")`; see
[Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).

---

# Maven publishing

URL: https://elide.help/docs/toolchain/jvm/publishing

> Publish JVM libraries with `elide publish`: install into the local Maven repository, deploy to Nexus, Artifactory or GitHub Packages, and release to Maven Central with signatures and checksums, no plugins.

`elide publish` builds a library's JARs, writes a POM for its consumers and publishes them to a Maven repository: the
local one by default, a team repository with `--to`, or Maven Central through the Central Publisher Portal. Maven,
Gradle and other Elide projects then depend on it like any other artifact. The `publishing` block in `elide.pkl`
configures it; there are no plugins to add.

| Target | Command | Needs |
| --- | --- | --- |
| Local Maven repository | `elide publish` | `groupId`, `version`, one `Jar` |
| A team repository | `elide publish --to internal` | Credentials in the environment |
| Maven Central | `elide publish --to central` | Portal token, `gpg`, POM metadata, sources and javadoc JARs |
| Nowhere (check first) | `elide publish --dry-run` | Nothing |

## Install locally

A publication needs a `groupId`, the project's `version` and one `Jvm.Jar` artifact:

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm

name = "greeter"
version = "1.0.0"
description = "Greets people."

artifacts {
  ["lib"] = new Jvm.Jar {}
}

publishing {
  maven {
    groupId = "dev.example"
  }
}
```

```bash
elide publish
```

Elide builds the JAR (reusing up-to-date outputs), writes the POM and installs both as `dev.example:greeter:1.0.0`
under `~/.m2/repository`, with `maven-metadata-local.xml`. The `artifactId` defaults to the project name. Reinstalling
the same version replaces it, so a consumer on the same machine picks up each change. From Maven:

```xml
<dependency>
  <groupId>dev.example</groupId>
  <artifactId>greeter</artifactId>
  <version>1.0.0</version>
</dependency>
```

From Gradle:

```kotlin
repositories { mavenLocal() }
dependencies { implementation("dev.example:greeter:1.0.0") }
```

From another Elide project:

```pkl
dependencies {
  maven {
    packages { "dev.example:greeter:1.0.0" }
  }
}
```

A local install needs no network and no credentials. `localRepository` installs somewhere else; a relative path
resolves against the manifest.

## Check before publishing

```bash
elide publish --dry-run
```

`--dry-run` stages the POM and JARs under `.dev/staging/publish/maven` with Maven file names
(`greeter-1.0.0.jar`, `greeter-1.0.0-sources.jar`, `greeter-1.0.0.pom`) and lists them. It signs them when signing is
on, and for Maven Central also writes the bundle, so it shows exactly what a real run would send. Nothing is written
to a repository.

## What goes in the POM

The POM describes the library for its consumers, not the build: coordinates, the `pom` metadata and dependencies,
with no `<build>`, `<repositories>` or local paths.

| `elide.pkl` | Published POM |
| --- | --- |
| `packages`, `modules` | `compile` dependencies |
| `runtimeOnly` | `runtime` dependencies |
| `compileOnly`, `devPackages`, `processors`, `kotlinPlugins`, `testPackages` | Left out |
| Versionless `exclusions` | An `<exclusion>` on every dependency |
| A workspace project | That project's publishing coordinates |
| A `Jar.from` sibling | Its `packages`, `modules` and `runtimeOnly`, unless already listed |
| A local JAR path | An error: consumers can't resolve it |

> [!NOTE] Kotlin libraries
> The POM also lists what Elide adds to a Kotlin project's classpath without a declaration, because consumers need it
> at run time: `kotlin-stdlib` and `kotlin-reflect` at the project's Kotlin version, and the runtimes
> `kotlin.features` turns on (coroutines, serialization). Turn a feature off, set `kotlin.compilerOptions.noStdlib`, or
> declare the dependency yourself to pin another version.

By default a publication holds every `Jar`, `SourceJar` and `JavadocJar` the project declares; `artifacts` picks a
subset by artifact name. It must contain exactly one `Jar`, and each classifier once. A `JavadocJar` over Kotlin
sources is generated with Dokka (see [JAR assembly](https://elide.help/docs/toolchain/jvm/jar#sources-and-javadoc-jars)).

## Publish to a team repository

Name the repository under `repositories`, then publish to it by name:

```pkl
publishing {
  maven {
    groupId = "dev.example"
    repositories {
      ["internal"] = "https://repo.example.dev/releases"
    }
  }
}
```

```bash
export ELIDE_MAVEN_INTERNAL_USERNAME=ci
export ELIDE_MAVEN_INTERNAL_PASSWORD="$REPO_TOKEN"
elide publish --to internal
```

Credentials come from `ELIDE_MAVEN_<NAME>_USERNAME` and `ELIDE_MAVEN_<NAME>_PASSWORD`, where `<NAME>` is the
repository name in upper case with every other character turned into `_` (`my-repo` → `ELIDE_MAVEN_MY_REPO_…`), so
the manifest holds no secrets. Every file is uploaded with `.md5`, `.sha1`, `.sha256` and `.sha512` checksums, and
`maven-metadata.xml` is updated. This works with Nexus, Artifactory, GitHub Packages and any repository that accepts
Maven uploads. A plain `http://` URL other than localhost is refused without `--allow-http-repositories`.

## Sign with gpg

```pkl
publishing {
  maven {
    signing { gpg { keyName = "0123ABCD" } }   // `signing {}` uses gpg's default key
  }
}
```

With `signing` set, a remote publish signs every file with the `gpg` binary (`<file>.asc`). A local install signs only
with `--sign`; `--no-sign` turns signing off. `gpg-agent` asks for the passphrase; in CI, set `ELIDE_GPG_PASSPHRASE`
and Elide passes it to `gpg` through loopback pinentry. Elide never reads the key itself. If `gpg` is missing or fails,
nothing is published.

## Release to Maven Central

Maven Central needs POM metadata, sources and javadoc JARs, signatures and a release version. A complete library:

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm
import "elide:Publishing.pkl" as Publishing

name = "greeter"
version = "1.0.0"
description = "Greets people."

artifacts {
  ["lib"] = new Jvm.Jar {}
  ["sources"] = new Jvm.SourceJar {}
  ["javadoc"] = new Jvm.JavadocJar {}
}

publishing {
  maven {
    groupId = "dev.example"
    pom {
      name = "Greeter"
      url = "https://github.com/example/greeter"
      licenses { new { name = "Apache-2.0"; url = "https://www.apache.org/licenses/LICENSE-2.0" } }
      developers { new { id = "jdoe"; name = "J. Doe" } }
      scm { url = "https://github.com/example/greeter" }
    }
    repositories {
      ["central"] = new Publishing.CentralPortal {}
    }
  }
}
```

Create a user token in the [Central Publisher Portal](https://central.sonatype.com) and publish:

```bash
export ELIDE_MAVEN_CENTRAL_USERNAME=<token user>
export ELIDE_MAVEN_CENTRAL_PASSWORD=<token password>
elide publish --to central
```

Before building anything, Elide checks Central's requirements and reports everything missing at once: the POM's
`name`, `description`, `url`, `licenses`, `developers` and `scm.url`, a `SourceJar`, a `JavadocJar`, and a version that
isn't a `-SNAPSHOT`. The POM's `description` defaults to the project's. Central always signs, with `gpg`'s default key
unless [`signing`](#sign-with-gpg) picks one, so `--no-sign` is refused.

Elide uploads one signed, checksummed bundle and waits for the Portal to validate it. By default
(`publishingType = "USER_MANAGED"`) you then release the deployment in the Portal; Elide prints its page. With
`publishingType = "AUTOMATIC"` the Portal releases it once validated. A failed validation prints the Portal's errors.
`--no-wait` returns right after the upload.

## Workspaces

In a [workspace](https://elide.help/docs/elide-pkl-reference#workspaces), set the shared configuration once in the root `elide.pkl`:

```pkl
import "elide:Publishing.pkl" as Publishing

publishing {
  maven {
    groupId = "dev.example"
    pom { url = "https://github.com/example/greeter"; scm { url = "https://github.com/example/greeter" } }
    repositories { ["central"] = new Publishing.CentralPortal {} }
  }
}
```

Members inherit everything except `artifactId` and `artifacts`, which stay per project; a member's own settings win
field by field, and repositories merge by name.

| Run | Publishes |
| --- | --- |
| `elide publish` at the root | Every project |
| `elide publish` in a member | That member and every workspace project its POM depends on |
| `elide publish core util` | Exactly `core` and `util`; workspace projects they depend on must already be in the target |
| `elide publish --skip-existing` | Every selected project whose version isn't in the target yet |

Every project is built, staged and signed before any is published, so a failure there publishes nothing. To Maven
Central, every project goes into one deployment that the Portal validates and releases together. `--skip-existing`
also reruns a release that failed partway: it leaves out what already made it, and never skips a snapshot.

## In CI

```yaml
- run: elide publish --to central --skip-existing
  env:
    ELIDE_MAVEN_CENTRAL_USERNAME: ${{ secrets.CENTRAL_USERNAME }}
    ELIDE_MAVEN_CENTRAL_PASSWORD: ${{ secrets.CENTRAL_PASSWORD }}
    ELIDE_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
```

Import the signing key into the runner's `gpg` keyring in an earlier step. See [Continuous integration](https://elide.help/docs/installation/ci-cd)
to install Elide on the runner.

## Reference

- [`elide publish`](https://elide.help/docs/cli-references#publish): every flag.
- [`publishing`](https://elide.help/docs/elide-pkl-reference#publishing): every manifest property.
- [POM export](https://elide.help/docs/build-tools-export): print a `pom.xml` for the build instead of publishing.

---

# Native Image

URL: https://elide.help/docs/toolchain/jvm/native-image

> Compile a JVM application to a native executable or shared library with `elide native-image` or an Elide project artifact, or compile it to WebAssembly.

Native Image compiles a JVM application ahead of time to a standalone executable or shared library.

## Compile from the command line

```bash
elide native-image -- -cp app.jar com.example.Main
```

Compiler arguments go after `--`; `elide native-image -- --help` lists them. Reflection, resources, JNI and proxies
need reachability metadata. The final link needs a C toolchain on the host.

## Project artifact

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm
import "elide:NativeImage.pkl" as Native

artifacts {
  ["app-jar"] = new Jvm.Jar {
    sources { "main" }
  }
  ["app"] = new Native.NativeImage {
    from { "app-jar" }
    entrypoint = "com.example.Main"
    type = "binary"
    options {
      optimization = "2"
      flags { "-H:+ReportExceptionStackTraces" }
    }
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `from` | JAR artifact keys (not paths); empty means every declared JAR, or a JAR of the project's classes. | none |
| `name` | Output file name. | the project name |
| `entrypoint` | Main class. | `jvm.main` |
| `moduleName` | Launch module for modular JARs; see below. | module holding the entrypoint |
| `type` | `"binary"` (executable) or `"library"` (shared library). | `"binary"` |
| `options` | Compiler options; see below. | — |
| `dependsOn` | Artifacts to build first. | none |

Output goes to `.dev/artifacts/native-image/`, with the final arguments in `native-image.args`.

### Compiler options

| `options` property | Meaning | Default |
| --- | --- | --- |
| `optimization` | `"auto"`, `"b"` (quick build), `"s"`, `"0"` … `"4"`. | `"auto"` |
| `driverMode` | `"embedded"` (Elide's compiler) or `"external"` (`native-image` from `GRAALVM_HOME`/`JAVA_HOME`). | `"embedded"` |
| `verbose` | Verbose compiler output. | `false` |
| `linkAtBuildTime.enabled` | Link everything at build time. | `true` |
| `linkAtBuildTime.packages` | Packages to link at build time when `enabled` is `false`. | none |
| `classInit.default` | Default class initialization: `"buildtime"` or `"runtime"`. | `"buildtime"` |
| `classInit.buildtime`, `classInit.runtime` | Classes or packages initialized at build or run time. | none |
| `exclusions.all` | Coordinates kept off both paths. | the compiler's own JARs |
| `exclusions.classpath`, `exclusions.modulepath` | Coordinates kept off one path. | none |
| `pgo.enabled` | Apply profiles when present. | `true` |
| `pgo.profiles` | Profile files. | none |
| `pgo.instrument` | Build an instrumented image that records profiles. | `false` |
| `pgo.sampling` | Use sampling profiles. | `false` |
| `pgo.autoprofile` | Auto-profile features. | `false` |
| `features` | Compiler feature classes to enable. | none |
| `flags` | Extra `native-image` flags; a changed file named in a flag triggers a rebuild. | none |
| `cflags`, `ldflags` | Extra C compiler and linker flags. | none |
| `defs` | System properties for the image build. | none |

The top-level `nativeImage { }` block accepts the same options but does not apply them; set each artifact's `options`.

### Modular applications

If a JAR in `from` has a `module-info.class`:

- Modular JARs and the `dependencies.maven.modules` bucket go on `--module-path` with
  `--add-modules=ALL-MODULE-PATH`; everything else stays on the class path.
- The binary launches with `--module <module>/<entrypoint>`, 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 Java or Kotlin to a WebAssembly module and JavaScript loader with Elide's WebImage artifact: prerequisites, backends, hosts and compiler options.

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 goes 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).

Target guides: [Browser WASM](https://elide.help/docs/toolchain/web/wasm) and [Edge WASM](https://elide.help/docs/toolchain/edge/wasm).

### 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
<!doctype html>
<html lang="en">
  <meta charset="utf-8" />
  <title>Hello WebImage</title>
  <body>
    <p>Open the browser console to see the application output.</p>
    <script src="./hello.js"></script>
  </body>
</html>
```

```bash
elide dev --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 `native-image` from `GRAALVM_HOME` or `JAVA_HOME`; that installation must
  support the WebAssembly backends.
- `-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.

## 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 rejects the WebAssembly backend | Point `GRAALVM_HOME` or `JAVA_HOME` at an installation whose `native-image` supports it, or use `driverMode = "embedded"`. |
| 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 Docker or OCI container image from a JAR or native executable as an Elide project artifact, loaded into the local daemon or written as a tarball.

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 before the build.

---

# Embedded C compiler and linker via LLVM

URL: https://elide.help/docs/toolchain/native/cc

> Use embedded Clang and LLVM to compile freestanding C17 into object files or LLVM IR, or link and invoke a native function in memory through ORC LLJIT.

`elide cc` embeds Clang compilation and LLVM's ORC LLJIT execution pipeline. Compile one freestanding C17
translation unit for the current host, emit an object file or textual LLVM IR, or link and invoke a native
function in memory. These operations require no separate compiler installation.

> [!NOTE] Frontend scope
> Native tools are part of Elide 1.6.2. The initial CLI exposes object output, LLVM IR
> output and in-memory JIT execution. It does not expose executable or shared-library output, system headers,
> include paths, library selection or cross-compilation.

## Compile a C source file

`answer.c`:

```c
long long answer(void) {
  return 42;
}
```

Compile it to a native object file:

```bash
elide cc -- -c answer.c -o answer.o
```

`answer.o` is a host-native relocatable object. To produce an executable or shared library from it, pass it
to a full compiler driver or linker; the current `cc` CLI does not expose those output modes.

Without `-o`, Elide writes the source basename with an `.o` extension in the current working directory:
`elide cc -- -c src/answer.c` produces `./answer.o`.

## Inspect LLVM IR

Select both `-S` and `-emit-llvm` to write textual LLVM IR:

```bash
elide cc -- -S -emit-llvm answer.c -o answer.ll
```

Without `-o`, the output is `answer.ll` in the current directory. `-S` alone does not emit assembly, and
`-c -emit-llvm` does not emit bitcode; these combinations are rejected.

## Invoke a native function

Compile the same source to LLVM IR, JIT-compile and link it in memory, then invoke `answer`:

```bash
elide cc -- --run answer answer.c
```

```terminaloutput
42
```

The entry point must be defined with the C calling convention, no arguments, no varargs and an LLVM `i64`
return type, represented here by `long long`. `int`, floating-point, pointer and `void` return types are
rejected for the entry point.

Elide prints the signed 64-bit result and exits successfully. The returned value does not become the shell
exit status: returning `42` still gives exit status `0`. `--run` creates no object or executable file and
cannot be combined with `-c`, `-S`, `-emit-llvm` or `-o`.

ORC LLJIT owns compilation, in-memory linking and symbol lookup for that invocation. The JIT and its code
are released after the call; functions and native addresses do not persist across commands. The CLI does
not expose argument passing or external library loading. Native code executes with the process's privileges;
invalid memory access or other native faults can terminate the process.

## Options

Pass compiler arguments after `--`:

| Option | Behavior |
| --- | --- |
| `-c` | Write a native object file. |
| `-S -emit-llvm` | Write textual LLVM IR. |
| `-o PATH` | Set the object or IR output path. |
| `--run SYMBOL` | Compile, link in memory and invoke a no-argument function returning `long long`. |
| `--help`, `-h` | Show the embedded compiler's help. |

```bash
elide cc -- --help
```

Exactly one source file and one output mode are required. Other compiler-driver options, including `-I`,
`-D`, `-l`, `-O` and `--target`, are not accepted. The command refuses to overwrite its source with its output.

## Headers and toolchain boundaries

The embedded compiler uses freestanding C17 with standard include discovery disabled. Write self-contained
translation units; installed host headers and bundled Native Image sysroots are not exposed through `cc`.
Adding `SDKROOT` does not enable system includes in this command.

Elide also packages a full Clang driver, LLD and target resources for
[Native Image](https://elide.help/docs/toolchain/jvm/native-image). That driver handles Native Image's C compilation and final
executable or shared-library link; `elide cc -- --run` uses ORC LLJIT for in-memory linking. On macOS,
Native Image requires an explicit `SDKROOT` until the distribution includes an Apple SDK. The freestanding
examples above need no Apple SDK.

To generate Java bindings for an existing C library, use [jextract](https://elide.help/docs/toolchain/native/jextract), or compile
bindings directly with [Java C header bindings](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings).

## Availability

| Elide distribution | Embedded `cc` |
| --- | --- |
| macOS arm64 | Supported. |
| Dynamically linked Linux amd64 or arm64 | Supported. |
| Fully static Linux / musl Elide | Not included. |
| Windows | Not included. |

The supported distributions include native tools alongside the JVM toolchain and load the compiler payload
when needed. A custom build made with `--no-jvm-toolchain` omits both. Having JVM tools on Windows or a fully
static build does not imply that `cc` or `jextract` is available.

A dynamically linked Linux Elide can still build a musl-targeted Native Image when its distribution includes
the appropriate sysroot; that is separate from running native tools inside a fully static Elide binary.

---

# C header bindings

URL: https://elide.help/docs/toolchain/native/jextract

> Generate Java Foreign Function and Memory API bindings from C headers with elide jextract, then compile and run them against a native shared library.

`elide jextract` reads C headers and generates Java source files using Java's Foreign Function and Memory
(FFM) API. It embeds OpenJDK jextract and shares Elide's Clang/LLVM native library with
the [embedded C compiler and linker](https://elide.help/docs/toolchain/native/cc), so generation needs no separate jextract, JDK or
libclang installation.

> [!NOTE] Distribution support
> Native tools are part of Elide 1.6.2. They are included on macOS arm64 and dynamically
> linked Linux amd64/arm64, and omitted on Windows, fully static Elide builds and custom builds using
> `--no-jvm-toolchain`.

Use this command when you want generated `.java` files to inspect, distribute or compile separately.
For an Elide Java project, [C header bindings in the Java compiler](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings)
can generate and compile bindings in memory from Pkl declarations or ad hoc `elide javac` options.

## Generate Java source

Save a small library interface as `native/answer.h`:

```c
int answer(void);
```

Generate its Java bindings:

```bash
elide jextract -- --output generated \
  --target-package example.ffi \
  --header-class-name NativeApi \
  native/answer.h
```

The output includes `generated/example/ffi/NativeApi.java` and any supporting sources needed by the
bindings. The header's `answer` declaration becomes a Java accessor such as `NativeApi.answer()`.
Generation produces source code, not a native library, class files or JNI wrappers. It does not load
the application library, so its implementation does not need to be present at this step.

Without `--output`, sources go in the current directory. Without `--target-package`, they use the unnamed
package. Without `--header-class-name`, jextract derives a class name from the header filename, such as
`answer_h` for `answer.h`. Supply an explicit header class name when passing multiple headers.

## Configure parsing and select declarations

Pass jextract's arguments after `--`; its own help lists the full interface:

```bash
elide jextract -- --help
```

| Option | Purpose |
| --- | --- |
| `--output PATH` | Directory for generated Java sources. |
| `-t PACKAGE`, `--target-package PACKAGE` | Package for generated classes. |
| `--header-class-name NAME` | Generated header class name. |
| `-I DIR`, `--include-dir DIR` | Add a C header search directory; repeat for multiple directories. |
| `-D NAME=VALUE`, `--define-macro NAME=VALUE` | Define a preprocessor macro; repeat as needed. |
| `--include-function NAME` | Select a function for generation. |
| `--include-constant NAME` | Select a macro or enum constant. |
| `--include-struct NAME`, `--include-union NAME` | Select a struct or union. |
| `--include-typedef NAME`, `--include-var NAME` | Select a typedef or global variable. |
| `-l LIBSPEC`, `--library LIBSPEC` | Add a shared library to the generated runtime lookup. |
| `--use-system-load-library` | Use `System.loadLibrary` or `System.load` for those libraries. |

For example, add a library's include directory, set a macro and select one function:

```bash
elide jextract -- --output generated -t example.ffi \
  --header-class-name NativeApi \
  -I native/include -D ANSWER_API_VERSION=1 \
  --include-function answer native/answer.h
```

The standalone command also reads Clang arguments from `compile_flags.txt` in the current working directory,
one argument per line. This differs from the integrated Java compilation path, which uses its declared
binding configuration. Elide passes jextract's diagnostics and exit status through; a failed extraction
does not yield usable bindings.

## Call a shared library

Suppose `native/libanswer.so` on Linux, or `native/libanswer.dylib` on macOS, exports the implementation:

```c
int answer(void) {
  return 42;
}
```

The library must be built for the machine running the Java application. Obtain it from the library's build
or package, or compile `native/answer.c` with a separate full C compiler:

```bash
# Linux
clang -shared -fPIC native/answer.c -o native/libanswer.so

# macOS
clang -dynamiclib native/answer.c -o native/libanswer.dylib
```

These are external compiler commands. `elide cc` exposes object/IR output and in-memory JIT linking;
its current CLI does not expose shared-library output.

Regenerate the bindings with an explicit library path. On Linux:

```bash
elide jextract -- --output generated -t example.ffi \
  --header-class-name NativeApi \
  -l :./native/libanswer.so native/answer.h
```

On macOS, use `-l :./native/libanswer.dylib` instead. The leading `:` marks a path rather than a logical
library name. A relative library path is resolved when the generated code runs, so run this example from
the directory containing `native/`.

Save this caller as `Main.java`:

```java
import example.ffi.NativeApi;

public class Main {
  public static void main(String[] args) {
    System.out.println(NativeApi.answer());
  }
}
```

Compile the generated sources and caller with Elide's bundled Java 25 compiler, then enable native access
when running them:

```bash
elide javac -- -d out generated/example/ffi/*.java Main.java
elide java -- --enable-native-access=ALL-UNNAMED -cp out Main
```

```terminaloutput
42
```

`ALL-UNNAMED` applies to this classpath example. For a named module, enable native access for the module
containing the generated bindings. Native access is needed by the generated FFM code at runtime;
successful generation and Java compilation do not establish that the shared library can be loaded.

## Library discovery and memory ownership

By default, `-l answer` generates a `SymbolLookup.libraryLookup` for the platform-mapped library name, such
as `libanswer.so` or `libanswer.dylib`. Its discovery follows the platform loader's rules.
`-l :PATH` embeds the path instead. Repeat `-l` for multiple libraries. The generated lookup also falls back
to the class loader's symbols and the native linker's default symbols.

For Java's `java.library.path` lookup, generate with `--use-system-load-library -l answer`, then supply
`-Djava.library.path=./native` to the Java launcher. This emits `System.loadLibrary("answer")`; a path
library specification instead uses `System.load` and requires an absolute path. Header include directories
set with `-I` do not configure runtime library discovery.

Elide does not package the application library with generated sources or JARs. Keep the matching shared
library and its dependencies available at runtime. Generating FFM bindings also does not automatically
register those calls for an arbitrary Native Image application.

Generated bindings expose native pointers through `MemorySegment` and provide layouts for supported C
types. They do not infer ownership rules: use an appropriate `Arena` for Java-managed native allocations,
keep allocations and callback stubs alive while C uses them, and release library-owned memory through the
library's documented API. Native code runs with the process's privileges, and incorrect lifetimes or ABI
mismatches can crash the process.

## Headers and platform limits

Elide supplies jextract's builtin Clang headers. Library-specific headers and their dependencies still need
to be available through the supplied paths and include directories. This is a C header generator; C++
interfaces need a C-compatible API. Review warnings about unsupported declarations rather than assuming
every header construct becomes a Java type. Opaque structs can remain usable as pointer handles even when
their layouts cannot be generated.

The macOS distribution does not include an Apple SDK. SDK-dependent headers require a compatible installed
SDK and appropriate include configuration. Elide's packaged Native Image compiler/sysroot configuration
is a separate facility; it does not make every host header available to jextract. The self-contained header
above requires no system SDK.

---

# Python toolchain

URL: https://elide.help/docs/python-toolchain

> What Elide's Python toolchain covers in 1.6.0: the optional Python component, running scripts and modules, pyproject.toml entry points, virtual environments, tests, and what is not available.

Python support is experimental. Elide runs Python 3.13 with its standard library and optional package tooling.
Python formatting and test discovery under `elide test` remain unavailable.

| Task | Command | Status |
| --- | --- | --- |
| Add Python to an install | `elide setup python` | Available |
| Run a script, `-c` or `-m` | `elide python ...`, `elide run app.py` | Available |
| Run a `pyproject.toml` entry point | `elide run NAME` | Available |
| Use packages from a virtual environment | `VIRTUAL_ENV=.venv elide python app.py` | Available |
| Run unittest or pytest | `elide python -m unittest`, `elide python -m pytest` | Available |
| Install PyPI packages | `elide install --ecosystems=pypi`, `elide uv install` | Requires the Python component and pytools |
| Discover Python tests | `elide test` | Not available |
| Format, LSP, `elide init` template | | Not available |

## Add Python

Python is an optional component:

```bash
elide setup python
```

Without it, Python commands print `Python support is not installed. Run 'elide setup python' to add it.` and exit `2`.
See [Python with Elide](https://elide.help/docs/python) for channels and package-manager installs.

## Run Python

`elide python` takes the same arguments as `python`; `elide run` and a bare `elide app.py` run `.py` files too:

```bash
elide python app.py --name Elide
elide python -m json.tool input.json
elide run app.py
```

Interpreter flags (`-I`, `-B`, `-u`, `-W`, ...) are listed in [Python with Elide](https://elide.help/docs/python#interpreter-options).

## Run project scripts

`elide run NAME` runs a `[project.scripts]` entry point from the `pyproject.toml` in the current directory. No
`elide.pkl` is needed.

```toml
# pyproject.toml
[project]
name = "greet"
version = "0.1.0"
requires-python = ">=3.13"

[project.scripts]
greet = "greet.cli:main"
```

```python
# greet/cli.py
import sys


def greeting(name: str) -> str:
    return f"Hello, {name}!"


def main() -> int:
    print(greeting(sys.argv[1] if len(sys.argv) > 1 else "world"))
    return 0
```

```bash
elide run greet Elide
```

```terminaloutput
Hello, Elide!
```

`elide greet Elide` does the same. Arguments after the name go to `sys.argv`, and the function's integer return value
is the exit code. A file named `greet`, an `elide.pkl` script or a `package.json` script of the same name wins; see
[Project setup](https://elide.help/docs/projects#add-a-script).

## Packages

Use `elide install --ecosystems=pypi` for declared dependencies, or `elide uv install PACKAGE`.
Packages go into the project's automatic environment with no activation. See
[Packages and virtual environments](https://elide.help/docs/python-packages).

## Tests

Run unittest or pytest through `elide python -m`; see [Python tests](https://elide.help/docs/python-testing). `elide test` runs JavaScript,
TypeScript and JUnit tests only.

## Samples

- [Python calling JavaScript](https://elide.help/docs/code-samples#python-calling-javascript)
- [JavaScript importing Python](https://elide.help/docs/code-samples#javascript-importing-python)
- [Python script](https://elide.help/docs/code-samples#python-script)

`elide init` has no Python template.

## Known limitations

- **C extensions**: some C extension modules do not load.
- **pip**: not bundled; `elide python -m pip` fails with `No module named pip`.
- More: [Python with Elide](https://elide.help/docs/python#known-limitations).

---

# Packages and virtual environments

URL: https://elide.help/docs/python-packages

> Install Python packages into an Elide project's automatic environment.

The native Elide launcher uses pytools, Elide's optional Python package tooling library. Install it with
`elide setup python`; use `elide setup python --force` to repair an older or incomplete installation.

Each project has an automatic package environment at `.dev/dependencies/pypi/site-packages`.
Elide adds it to Python's import path without activation or `VIRTUAL_ENV`.

```bash
elide uv install attrs
elide python -c 'import attrs; print(attrs.__version__)'
```

To install dependencies declared in `pyproject.toml`, `requirements.txt`, or `elide.pkl`:

```bash
elide install --ecosystems=pypi
```

`elide install --workspace` includes all declared ecosystems. A plain `elide install` retains
its Maven default.

## Package operations

`elide uv` accepts `install`, `sync`, `compile`, `check`, `list`, `freeze`, and `show`. The optional
`pip` namespace is also accepted, for example `elide uv pip install attrs`.

```bash
elide uv compile requirements.in --generate-hashes --output-file requirements.txt
elide uv sync requirements.txt
elide uv list
elide uv check
```

`compile` locks requirements; this surface does not yet expose uv's project `lock`,
`run`, runtime download, or runtime management commands. `sync` removes packages absent from the
requirements file. Clearing an environment with an empty file requires uv's explicit
`--allow-empty-requirements` option.

`check` validates the project package directory using uv’s dependency, Python-version, and wheel
compatibility diagnostics. It returns 1 for incompatible or missing dependencies.

Use `elide --project PATH uv ...` to select a project. Elide owns the interpreter and destination;
uv's interpreter and target settings do not redirect installation to another environment.
Index, offline, hash-verification, and cache options remain available. Source builds are disabled;
only compatible wheels can be installed. Native CPython wheels cannot substitute for GraalPy wheels.

## Isolated tools

Run a Python console script without installing its dependencies into your project:

```bash
elide uv tool run --from 'httpie==3.2.4' http --help
elide uv tool run --from PACKAGE --with EXTRA_PACKAGE COMMAND ARGS...
elide uv tool list
elide uv tool uninstall ENVIRONMENT_KEY
elide uv tool prune
elide uv tool prune --all
elide uv tool dir
```

Tool options precede `COMMAND`; everything after it is passed through to the tool. `--from` defaults
to the command name. Only compatible wheels are supported; tools requiring unsupported native
extensions or source builds will fail explicitly. This is an Elide-managed tool runner, not the
unrestricted upstream uv tool interface.

Elide runs console entrypoints with its own Python interpreter and preserves your working directory,
arguments, and exit status. Tool dependencies are isolated from project packages, `PYTHONPATH`, and
external virtual environments, including interpreter re-execution. Tools still have normal user
permissions; dependency isolation is not a security sandbox.

Environments live under `$ELIDE_HOME/python/tools`, or the existing Elide user data directory
(`$XDG_DATA_HOME/elide`, falling back to `~/.local/share/elide`). Cache keys include the Elide runtime
identity, package requirements, and index options. Pin requirements for reproducibility; use
`tool run --refresh` to resolve again, including after changing a local wheel at the same path.
`--offline`, `--no-index`, `--index-url`, and `--find-links` are supported.

The cache defaults to **2 GiB** and **30 days since last use**. Each run evicts expired entries and
least-recently-used inactive environments as needed. Set `ELIDE_PYTHON_TOOLS_MAX_BYTES` to adjust the
size limit. Oversized installs are discarded; active environments are protected, so a full cache of
running tools can reject a new install. Size is checked during cache operations, not enforced as a
filesystem quota while arbitrary tool code runs.

`tool list` shows environment keys, byte sizes, and requirements. `tool uninstall KEY` removes one
inactive environment. `tool prune` applies expiry and size limits; `tool prune --all` purges every
inactive environment. The runner avoids a second persistent uv download cache and removes incomplete
staging data on the next cache operation. Cleanup never touches project environments.

## External virtual environments

`VIRTUAL_ENV` remains supported for importing compatible Python 3.13 packages from an external
virtual environment. The project's own packages take precedence over that environment. This is
optional; it is not needed for packages installed through Elide.

Python support remains experimental. The LLVM-driven GraalPy native-extension builder is not yet
implemented. pip is not bundled; use the package commands above.

---

# Python tests

URL: https://elide.help/docs/python-testing

> Run Python tests on Elide with unittest from the standard library or pytest from a virtual environment; `elide test` does not discover Python tests in 1.6.0.

`elide test` does not discover Python tests in 1.6.0; in a Python-only directory it prints `No tests found.` and exits
`0`. Run the test runner as a module instead. The exit code is the runner's, so a failing test fails the command.

The examples test this module:

```python
# greet/cli.py
import sys


def greeting(name: str) -> str:
    return f"Hello, {name}!"


def main() -> int:
    print(greeting(sys.argv[1] if len(sys.argv) > 1 else "world"))
    return 0
```

`greet/` and `tests/` each contain an empty `__init__.py`.

## unittest

unittest ships with the standard library:

```python
# tests/test_cli.py
import unittest

from greet.cli import greeting


class GreetingTest(unittest.TestCase):
    def test_names_the_caller(self):
        self.assertEqual(greeting("Elide"), "Hello, Elide!")
```

```bash
elide python -m unittest discover -s tests -t .
```

```terminaloutput
.
----------------------------------------------------------------------
Ran 1 test in 0.001s

OK
```

## pytest

Install pytest into a Python 3.13 virtual environment ([Packages and virtual environments](https://elide.help/docs/python-packages)), then run
it with `VIRTUAL_ENV` set:

```bash
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python pytest
```

```python
# tests/test_greeting.py
from greet.cli import greeting


def test_default_name():
    assert greeting("world") == "Hello, world!"
```

```bash
VIRTUAL_ENV=.venv elide python -m pytest -q
```

pytest collects both files and ends with:

```terminaloutput
2 passed in 0.03s
```

## In CI

Add the Python component after installing Elide (`elide setup python`), then run the same commands; see
[Continuous Integration](https://elide.help/docs/installation/ci-cd#example-workflow).

---

# Web toolchain

URL: https://elide.help/docs/toolchain/web

> Run JavaScript and TypeScript with Elide, serve files during development, process web assets, install npm packages and configure web builds in elide.pkl.

Run, serve, build and install dependencies for JavaScript and TypeScript projects.

## 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 public   # dev server on 127.0.0.1:3000; pages reload when files change
```

<img src="https://elide.help/assets/demos/dev-server.gif" alt="Running the Elide development server and reloading a changed page" width="1591" height="691" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

Page reload applies to directories, not to a script passed to `elide dev`. `--host` and `--port` set the address,
`--no-watch` turns off watching, and `--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` | Declared ECMAScript edition: a year `2015` … `2025`, `"stable"` or `"latest"`. `elide project info` shows it; it does not change which syntax runs or how code is built ([JavaScript language](https://elide.help/docs/javascript-language)). | `"stable"` |

## Project builds

To build a site with `elide build`, declare a [static-site artifact](https://elide.help/docs/toolchain/web/static-site). To compile Java or
Kotlin for the browser, see [Browser WASM](https://elide.help/docs/toolchain/web/wasm).

---

# npm installer

URL: https://elide.help/docs/toolchain/web/npm

> Install npm packages with `elide install --ecosystems=npm`: Elide reads package.json and the npm block in elide.pkl, and links packages into node_modules.

Elide installs npm packages and links them into the project's `node_modules`.

```bash
elide install --ecosystems=npm
```

<img src="https://elide.help/assets/demos/npm-install.gif" alt="Installing an npm dependency and running a project with Elide" width="1591" height="764" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

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 with Elide's StaticSite artifact: render Markdown, process scripts and stylesheets, compress images and copy other files.

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. | `"<prefix>_/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.

## Samples

Start from a template:

```bash
elide init --template web-simple  # static site
elide init --template web-demo    # static site with TypeScript and Markdown
```

---

# Browser WASM

URL: https://elide.help/docs/toolchain/web/wasm

> Compile Java or Kotlin to WasmGC with Elide: build a WebAssembly module and JavaScript loader, load it from a web page, and check browser support.

A [WebImage](https://elide.help/docs/toolchain/jvm/webimage) artifact with `backend = "wasm-gc"` compiles Java or Kotlin to WasmGC: a
WebAssembly module whose objects live in the browser's garbage-collected heap, plus a JavaScript loader that fetches
and starts it. To run an existing `.wasm` file with Elide, 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.

## Build

```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 WasmGC");
  }
}
```

```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 = "browser"
  }
}
```

```bash
elide build
```

Output goes to `.dev/artifacts/native-image/`:

| File | Deploy | Hello-world size |
| --- | --- | --- |
| `hello.js` | Yes: the loader. | 110 KB |
| `hello.js.wasm` | Yes: the module. | 1.3 MB (480 KB gzipped) |
| `hello.js.wat` | No: text form, for inspection. | 32 MB |
| `hello.js.map` | Optional: emitted with `sourceMap = true`. | |

| Property | Browser value |
| --- | --- |
| `backend` | `"wasm-gc"` (the default). |
| `runtime` | `"browser"`, or `"generic"` to keep Node support in the same loader. |
| `autoRun` | `true` (default) runs `main` when `hello.js` loads. |

Other properties and compiler options: [WebImage](https://elide.help/docs/toolchain/jvm/webimage#choose-a-backend-and-host).

## Load it in a page

Put `index.html` next to the bundle:

```html
<!doctype html>
<html lang="en">
  <meta charset="utf-8" />
  <title>Hello WasmGC</title>
  <body>
    <script src="./hello.js"></script>
  </body>
</html>
```

```bash
elide dev --no-tui --port 8000 .dev/artifacts/native-image
```

Open `http://localhost:8000/`; `Hello from WasmGC` appears in the browser console.

- The loader requests the module at its own URL plus `.wasm`, so keep `hello.js` and `hello.js.wasm` in the same
  directory.
- Load it with a classic `<script>`. With `type="module"` the loader requests the page's URL plus `.wasm` instead.
- Serve over HTTP or HTTPS; `file://` URLs do not work.
- `System.out` writes to the browser console.

To deploy, copy `hello.js`, `hello.js.wasm` and the page to any static host.

## Browser support

WasmGC bundles need WebAssembly garbage collection and exception handling with `exnref`:

| Browser | Minimum version |
| --- | --- |
| Chrome, Edge | 137 |
| Firefox | 131 |
| Safari | 18.4 |

An older browser rejects the module with a `CompileError` when the page loads. To serve hosts without WasmGC, see
[Edge WASM](https://elide.help/docs/toolchain/edge/wasm).

---

# Edge WASM

URL: https://elide.help/docs/toolchain/edge/wasm

> Build linear-memory WebAssembly from Java or Kotlin with Elide: bundle sizes, host requirements, and which runtimes run the output.

A [WebImage](https://elide.help/docs/toolchain/jvm/webimage) artifact with `backend = "wasm-lm"` compiles Java or Kotlin to WebAssembly for
JavaScript hosts that compile WebAssembly at runtime. The module keeps its heap and garbage collector in linear memory,
so the host needs no WasmGC support. Like the [browser build](https://elide.help/docs/toolchain/web/wasm), it starts through its JavaScript
loader; it is not a WASI module or component, and it does not deploy to Cloudflare Workers.

## Build

Prerequisites match the [browser build](https://elide.help/docs/toolchain/web/wasm#prerequisites): Binaryen's `wasm-as` on `PATH`, and code
that meets the [Native Image requirements](https://elide.help/docs/toolchain/jvm/native-image).

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as jvm
import "elide:NativeImage.pkl" as nativeImage

name = "hello-edge"

artifacts {
  ["app-jar"] = new jvm.Jar {
    sources { "main" }
  }
  ["edge"] = new nativeImage.WebImage {
    from { "app-jar" }
    name = "hello"
    entrypoint = "Hello"
    backend = "wasm-lm"
    runtime = "node"
  }
}
```

```bash
elide build
node .dev/artifacts/native-image/hello.js
```

Without a manifest:

```bash
elide javac -- -d classes Hello.java
elide native-image -- --tool:wasm-lm -cp classes -o hello Hello
```

| Property | Edge value |
| --- | --- |
| `backend` | `"wasm-lm"`. |
| `runtime` | `"node"` for Node-compatible APIs; `"generic"` also detects browser APIs. |
| `autoRun` | `true` (default) runs `main` when `hello.js` loads. |

## Output and size

| File | Deploy | Hello-world size |
| --- | --- | --- |
| `hello.js` | Yes: the loader. | 42 KB |
| `hello.js.wasm` | Yes: the module. | 2.1 MB (660 KB gzipped) |
| `hello.js.wat` | No: text form, for inspection. | 38 MB |
| `hello.js.map` | Optional: emitted with `sourceMap = true`. | |

A linear-memory module is larger than the [WasmGC build](https://elide.help/docs/toolchain/web/wasm) of the same program, which uses the
host's garbage collector.

## Host requirements

| Requirement | Reason |
| --- | --- |
| WebAssembly exception handling with `exnref` | The module uses it. |
| Compiling WebAssembly from bytes at runtime | The loader reads `hello.js.wasm` and compiles it on start. |
| Node `fs` or `fetch` | The loader reads the module through one of them. |

| Host | Runs the bundle |
| --- | --- |
| Node.js 25+ | Yes: `node hello.js`. |
| Bun | Yes: `bun hello.js`. |
| Cloudflare Workers | No: Workers compile only modules bundled at deploy time and reject the loader's runtime compile with `Wasm code generation disallowed by embedder`. |
| WASI hosts (Fastly Compute, Wasmtime) | No: the module imports from its JavaScript loader, not WASI. |

---

# IDE integration

URL: https://elide.help/docs/ide

> Work on Elide projects in VS Code, IntelliJ IDEA, Zed or any LSP or DAP editor: project sync, code intelligence, run, test and debug from the editor, and coding agents over MCP.

Elide projects open in VS Code and IntelliJ IDEA with their dependencies, source sets, run targets, tests and
debugger wired to the `elide` CLI. The Zed extension and other editors use `elide lsp` for Java and the Debug Adapter
Protocol to debug JavaScript, TypeScript and Python.

## Choose your editor

| Editor | Install | Guide |
| --- | --- | --- |
| VS Code 1.105+ | `code --install-extension elide-*.vsix` | [VS Code extension](https://elide.help/docs/vscode) |
| IntelliJ IDEA 2025.3+ | Plugin repository `https://plugins.elide.dev/intellij` | [IntelliJ IDEA plugin](https://elide.help/docs/intellij) |
| Zed | [Elide extension](https://github.com/elide-dev/zed) | [Zed extension](https://elide.help/docs/zed) |
| Neovim, Helix, any LSP or DAP client | `elide lsp`, `--debugger=dap` | [Other editors](https://elide.help/docs/connect-ide) |

## What each editor gets

| Feature | VS Code | IntelliJ IDEA | Zed | LSP or DAP client |
| --- | --- | --- | --- | --- |
| Project sync from `elide.pkl` | Yes | Yes | Classpath | Classpath |
| Kotlin code intelligence | Yes | Yes | No | No |
| Java code intelligence | Yes | Yes | Yes | Yes |
| JavaScript, TypeScript, Python debugging | No | No | Elide adapter | DAP |
| Run entrypoints and tasks | Yes | Yes | No | No |
| Tests in the IDE's runner | Yes | Yes | No | No |
| JVM debugging | Yes | Yes | No | No |
| Native Image debugging | GDB | GDB, LLDB | No | No |
| Coverage view | Yes | Yes | No | No |
| New project from a template | Yes | Yes | No | No |
| `elide.pkl` completion | No | Pkl plugin | No | No |

## In the editor

1. Open a folder with `elide.pkl`. The editor syncs its dependencies and source sets.
2. Code intelligence resolves project and library symbols, with library sources attached.
3. Run and debug entrypoints from code lenses or gutter icons; runs go through `elide run`.
4. Tests run through `elide test` and report per test in the IDE's test view.

## Embedding in a custom editor

The experimental embedding SDK provides a C/C++ ABI for opening sessions, exchanging Cap'n Proto
messages, and releasing response buffers. SDK builds include matching libraries, `include/elide.h`,
schemas, examples, and a `README.md` integration guide. Keep the files from one SDK together.
Archives are named `elide.embed.<platform>.tgz` or `.zip` where available.

Discover installed language services before initializing LSP. SDK-owned compiler workers provide
Java and JavaScript/TypeScript completion, hover, cross-file navigation, rename, and diagnostics.
These services have been tested on macOS Apple Silicon. Kotlin project semantics and rename are
not yet available through this SDK. Compiler workers read project files and dependencies; they
are separate from restricted execution kernels and do not provide OS isolation.

## Related

- [Debugging](https://elide.help/docs/debugging): CDP, DAP and JDWP debuggers for every language.
- [Agentic engineering](https://elide.help/docs/agentic-engineering): `elide mcp` and the docs MCP server for coding agents in your editor.
- [Project setup](https://elide.help/docs/projects): the `elide.pkl` manifest the editors read.

---

# VS Code extension

URL: https://elide.help/docs/vscode

> The Elide extension for VS Code 1.105 or newer: project sync for Kotlin and Java code intelligence, the Elide sidebar, code lenses, tests, debugging, tasks and settings.

The Elide extension turns any folder with an `elide.pkl` into a VS Code project: it syncs dependencies and source sets
into the Kotlin language server, and runs, tests and debugs through the `elide` CLI.

## Requirements

| Requirement | Notes |
| --- | --- |
| VS Code 1.105 or newer | Desktop VS Code or a remote/server build with a local filesystem. |
| Elide 1.5 or newer | Found through `elide.home`, `$ELIDE_HOME`, the install locations, then `PATH`. Elide 1.6 needs extension 0.6.0 or newer. |
| **Kotlin by JetBrains** | `JetBrains.kotlin-server`; installed with the extension. Finish its first-run prompt. |
| A JDK | For code intelligence; set `elide.jdk.home` or `$JAVA_HOME`. |

The extension needs a trusted workspace: a sync runs the workspace's `elide` CLI.

## Install

```bash
curl -LOJ "https://plugins.elide.dev/vscode/files?id=elide.elide"
code --install-extension elide-*.vsix
```

**Help → Get Started → Get started with Elide** walks through install, project, sync, run and test.

## Sync a project

Opening a folder with `elide.pkl` syncs it: Elide resolves the manifest, installs dependencies when the lockfile is
stale, and writes `workspace.json` for the Kotlin language server. Add `workspace.json` to `.gitignore`.

| Status bar | Meaning |
| --- | --- |
| **Elide** with a check | In sync |
| **Elide** with a spinner | Syncing |
| **Elide: out of date** | `elide.pkl` or the resolved dependencies changed |
| **Elide**, error-colored | Sync failed; **Elide: Show Output** has the CLI log |

Click the status bar item for the Elide menu: sync, run a command, run all tests, open `elide.pkl` or the output.
When `elide.pkl` changes, the extension asks to reload (`elide.sync.onManifestChange`).

## The Elide sidebar

The **Elide** view in the activity bar lists each project:

| Group | Rows | Actions |
| --- | --- | --- |
| Entrypoints | `jvm.main`, `entrypoint` and `scripts` entries | Run, Debug |
| Tasks | `build`, `test`, `install`, and **Build targets** from `elide build --inspect` | Run, Debug on targets that take `--debugger` |
| Source sets | Each source set and its roots | |
| Dependencies | Resolved libraries | Reveal in the file manager |

## Code intelligence

Kotlin and Java completion, navigation and diagnostics come from the Kotlin language server, which imports the synced
`workspace.json`: one module per source set, every library with its sources, the JDK and the manifest's Kotlin options.

- Sources jars are installed for declared Maven packages, so **Go to Definition** opens library code
  (`elide.install.classifiers`).
- The JDK comes from `elide.jdk.home`, then `jvm.javaHome`, `$JAVA_HOME`, or an installed JDK matching `jvm.target`.
- A checkout can keep an IntelliJ `.idea` directory: the extension sets `intellij.buildTool` to `json` in the
  workspace settings, so each editor reads its own model.

## Run

Code lenses run what the project declares:

| Where | Lenses |
| --- | --- |
| Above a JVM `main` function | **Run with Elide**, **Debug with Elide** |
| `jvm.main` and `entrypoint` in `elide.pkl` | **Run**, **Debug** |
| `scripts` entries | **Run script** |
| `artifacts` entries | **Build**; Native Image binaries also **Run** and **Debug** |

Runs are VS Code tasks of type `elide`; compiler errors become Problems on the reported file and line.

| Command | Effect |
| --- | --- |
| `Elide: Run Elide Command…` | Run `build`, `test`, `install` or `run <entrypoint>` as a task. |
| `Elide: Sync Project(s)` | Sync again. |
| `Elide: Show Menu` | The status bar menu. |
| `Elide: New Project…` | Create a project from a template of the installed CLI. |
| `Elide: Add Workspace Member…` | Create a project inside this one and add it to `workspace.members`. |
| `Elide: Open generated Kotlin LSP workspace` | Open `workspace.json`. |
| `Elide: Show Output` | Show the CLI output and the sync log. |

In `.vscode/tasks.json`:

```jsonc
{ "type": "elide", "command": "test", "args": ["src/api"], "options": { "bail": 3 } }
```

| Field | Value |
| --- | --- |
| `command` | `build`, `run`, `test` or `install` |
| `args` | Positional arguments: build targets, test paths, the entrypoint |
| `options` | CLI options: `{ "no-cache": true }` adds `--no-cache`; `false` drops an inherited one |
| `flags` | `-f NAME[=VALUE]` build flags |
| `programArgs` | Arguments after `--` |
| `env`, `project` | Environment; project root relative to the workspace folder |

## Test

JUnit tests in the test source sets appear in the **Testing** view, with gutter icons on each class and method. A run
calls `elide test --reporter=tap` for the selection and reports each test as it finishes; a failure shows its
assertion message and links to the failing line.

The **Debug** profile runs the same tests under the debugger.

**Run with Coverage** runs the selection with `--coverage` and shows the result in the editor gutter and the **Test
Coverage** view: JavaScript and TypeScript from LCOV, Java and Kotlin from a JaCoCo XML report. Request the XML report in
`elide.pkl`:

```pkl
import "elide:Coverage.pkl" as Coverage

coverage {
  jvm {
    reports { Coverage.xmlReport() }
  }
}
```

## Debug

**Debug with Elide** starts `elide run --debugger` and attaches to it. Breakpoints in Kotlin and Java sources stop the
program; ending the session stops Elide.

In `.vscode/launch.json`:

```jsonc
{
  "type": "elide",
  "request": "launch",
  "name": "Elide: Run (debug)",
  "entrypoint": "src/main/kotlin/shop/Main.kt"
}
```

| Field | Value |
| --- | --- |
| `command` | `run` (default), `test`, or `build` with `targets` |
| `entrypoint` | File, script or entrypoint; empty uses the manifest's |
| `args` | Program arguments |
| `elideArgs`, `options`, `flags`, `env`, `project` | As for tasks |

`elide.debug.adapter` picks the debugger: `intellij` (default, from the Kotlin extension) or `java`
([Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug)). The debugger
listens on port `5005`, so one session runs at a time. For CDP and DAP debugging of JavaScript, TypeScript and Python,
see [Debugging](https://elide.help/docs/debugging#attach-a-debugger).

### Native Image

Launch type `elide-native` builds a Native Image artifact and debugs the binary under GDB, through the **C/C++**
extension (`ms-vscode.cpptools`):

```jsonc
{ "type": "elide-native", "request": "launch", "name": "Elide: Debug Native Image", "artifact": "bin" }
```

Add `-g` to the artifact's `options.flags` in `elide.pkl` for source-level breakpoints; debug info is emitted on Linux
only. `program` debugs an existing binary, `build: false` skips the build.

## Workspaces

A manifest with `workspace.members` syncs as one build. Each member is a project in the sidebar, the Testing view,
tasks and launch configurations, and code intelligence follows `project("name")` dependencies between members without
a build. Opening a member's directory offers to open the workspace root. See
[Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).

## 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. |
| `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.install.classifiers` | `["sources"]` | Extra jars per Maven package: `sources`, `docs`. |
| `elide.flags` | `[]` | `-f NAME[=VALUE]` flags for every invocation, sync included. |
| `elide.build.options` | `{}` | Default options for `elide build`; `elide.run.options`, `elide.test.options` and `elide.install.options` likewise. |
| `elide.codeLens.enabled` | `true` | Show the Run and Debug code lenses. |
| `elide.debug.adapter` | `"intellij"` | `intellij` or `java`. |
| `elide.debug.nativeMiMode` | `"auto"` | `gdb`, `lldb` or `auto` for Native Image sessions. |
| `elide.debug.miDebuggerPath` | `""` | GDB or `lldb-mi` binary for Native Image sessions. |

---

# IntelliJ IDEA plugin

URL: https://elide.help/docs/intellij

> The Elide plugin for IntelliJ IDEA 2025.3 or newer: import projects and workspaces, run configurations, gutter actions, test results, coverage, debugging and the Elide distribution setting.

The Elide plugin imports a directory with `elide.pkl` the way IntelliJ IDEA imports a Maven or Gradle build, and runs,
tests and debugs through the `elide` CLI.

## Requirements

| Requirement | Notes |
| --- | --- |
| IntelliJ IDEA 2025.3 or newer | Community or Ultimate, with the bundled Java and Kotlin plugins. Kotlin code on Elide 1.6 needs IntelliJ IDEA 2026.2 or newer, whose Kotlin plugin reads Kotlin 2.5 libraries. |
| Elide | Found through the project's **Elide distribution** setting. Elide 1.6 needs plugin 0.9.3 or newer. |
| A JDK registered in the IDE | For JVM projects. |
| **Pkl** plugin (optional) | Completion, navigation and inspections in `elide.pkl`. |

## 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
`elide.pkl` editing. Plugin ZIPs are also attached to each
[GitHub release](https://github.com/elide-dev/intellij/releases).

## 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 and documentation 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, their modules and the build targets under **Tasks**, runnable
  from the tree.

**File → New → Project → Elide** creates a project from the templates `elide init` offers.

### Workspaces

A manifest declaring `workspace.members` imports as one project. Every member gets its own modules, classpath and
JDK, and a `project("name")` dependency becomes a module dependency, so the IDE compiles and navigates across members.
Only the root is linked; editing a member's manifest reloads the workspace. See
[Workspaces](https://elide.help/docs/elide-pkl-reference#workspaces).

## Run

Create an **Elide** run configuration. Its command line takes anything the CLI accepts, with completion for
commands, flags, entrypoints and the project's build tasks:

```text
run
test -t 'MyTest'
build -- --flag-for-the-tool
serve --port 8080
```

| Gutter icon on | Actions |
| --- | --- |
| A Kotlin or Java `main` function | Run, Debug |
| A JUnit test class or method | Run, Debug |
| `jvm.main`, `entrypoint` and `scripts` in `elide.pkl` | Run, Debug (Pkl plugin) |
| `artifacts` entries in `elide.pkl` | Build; a Native Image binary also Run, Debug (Pkl plugin) |

**Run Anything** (double Ctrl) accepts `elide …`. `elide build` reports to the **Build** tool window as a step tree
with timings and compiler diagnostics; other commands report to **Run**.

## Test

An `elide test` configuration reports into the test runner: a tree with pass, fail and skip states, timings, output
and jump to source for JVM tests.

**Run with Coverage** adds `--coverage` and loads the JaCoCo and LCOV reports into the coverage view, including
reports from runs started outside the IDE.

## Debug

**Debug** on an Elide run or test configuration adds `--debugger` and attaches the IDE's JVM debugger on port `5005`.
It debugs JVM code; for JavaScript, TypeScript and Python use the CDP or DAP debugger in
[Debugging](https://elide.help/docs/debugging#attach-a-debugger).

**Run Native Image** and **Debug Native Image** on a Native Image artifact build it and run or debug the binary with
GDB or LLDB. Debugging needs the **Native Debugging Support** plugin (IntelliJ IDEA Ultimate) and `-g` in the
artifact's `options.flags`; images carry debug info on Linux only.

## Settings

**Settings → Build, Execution, Deployment → Build Tools → Elide**:

| Setting | Effect |
| --- | --- |
| **Elide distribution** | *Auto-detect* or a custom path. |
| **Native Image debugging** | Debugger (*Auto*, *GDB* or *LLDB*) and the GDB executable. |

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` |

---

# Zed extension

URL: https://elide.help/docs/zed

> The Elide extension for Zed: `elide lsp` as a Java language server, an Elide debug adapter for JavaScript, TypeScript and Python, and debugging from Zed tasks.

The [Elide extension for Zed](https://github.com/elide-dev/zed) adds `elide lsp` as a Java language server and an
`Elide` debug adapter for JavaScript, TypeScript and Python. Any Zed task that runs `elide run` or `elide test` also
shows up in the debugger's **Debug** tab.

## Requirements

| Requirement | Why |
| --- | --- |
| Elide 1.6.0 or newer on `PATH` | The extension runs `elide`; set another path in settings. |
| Zed's [Java extension](https://github.com/zed-extensions/java) | It defines the Java language. |
| The [Pkl extension](https://github.com/Moshyfawn/pkl-zed) | Highlights `elide.pkl`. Optional. |
| `elide setup python` | Only to debug Python. |

## Install

Install it as a dev extension, which needs Rust through `rustup`:

```bash
git clone https://github.com/elide-dev/zed elide-zed
```

In Zed, open **Extensions**, choose **Install Dev Extension** and select the `elide-zed` directory.

## Java language server

Name `elide` in the Java `language_servers` list of `settings.json`. To use it instead of jdtls:

```json
{
  "languages": {
    "Java": { "language_servers": ["elide", "!jdtls", "..."] }
  }
}
```

`["elide", "jdtls"]` keeps both; `["!elide", "..."]` turns Elide off. The server reads the workspace root Zed sends,
and an `elide.pkl` there makes it an Elide project, so dependencies resolve. It provides diagnostics, completion,
hover, navigation, rename, formatting, code actions, inlay hints and semantic tokens; see
[Other editors](https://elide.help/docs/connect-ide#java-language-server) for the full list.

To run a specific binary or pass extra flags:

```json
{
  "lsp": {
    "elide": {
      "binary": { "path": "/opt/elide/bin/elide", "arguments": ["lsp"] }
    }
  }
}
```

`arguments` replaces the default `["lsp"]`.

## Debugging

Open the debugger with `debugger: start` (F4) and pick a scenario from `.zed/debug.json`, a task from the **Debug**
tab, or **Launch** with the `Elide` adapter. `launch` starts `elide run --debugger=dap` (or `elide test` with
`"command": "test"`) and connects; `attach` connects to a program already listening:

```json
[
  { "label": "Debug app.ts", "adapter": "Elide", "request": "launch", "program": "app.ts" },
  { "label": "Debug this file", "adapter": "Elide", "request": "launch", "program": "$ZED_FILE" },
  { "label": "Debug tests", "adapter": "Elide", "request": "launch", "command": "test", "args": ["app.test.ts"] },
  { "label": "Attach", "adapter": "Elide", "request": "attach", "tcp_connection": { "host": "127.0.0.1", "port": 4711 } }
]
```

| Launch field | Meaning |
| --- | --- |
| `program` | File to run, relative to `cwd`. |
| `args` | Arguments after `program`. |
| `cwd` | Working directory; defaults to the worktree root. |
| `env` | Extra environment variables. |
| `command` | `run` (default) or `test`. |
| `elideArgs` | Elide flags before `program`, such as `["--max-mem=512m"]`. |
| `host`, `port` | DAP listener; defaults to `127.0.0.1` and a free port (`4711` to attach). |

Program output appears in the debug console. To attach, start the program yourself:

```bash
elide run --debugger=dap app.py
```

To make Elide the default debugger for a language's gutter and new-process modal:

```json
{ "languages": { "TypeScript": { "debuggers": ["Elide"] } } }
```

### Limits

- Java and Kotlin debugging (JDWP) isn't offered: Zed debugs Java only through the Java extension.

## Related

- [IDE integration](https://elide.help/docs/ide): what each editor gets.
- [Other editors](https://elide.help/docs/connect-ide): `elide lsp` and DAP from Neovim, Helix and other clients.
- [Debugging](https://elide.help/docs/debugging): CDP, DAP and JDWP debuggers for every language.

---

# Other editors

URL: https://elide.help/docs/connect-ide

> Use Elide's Java language server, `elide lsp`, and its Debug Adapter Protocol server from Neovim, Helix or any LSP or DAP client: setup, root detection and the features each provides.

`elide lsp` is a Java language server on stdio. Any editor with an LSP client can use it; VS Code, IntelliJ IDEA
and Zed have their own integrations ([VS Code](https://elide.help/docs/vscode), [IntelliJ IDEA](https://elide.help/docs/intellij), [Zed](https://elide.help/docs/zed)).

## Java language server

```bash
elide lsp
```

Set it as the server command for the `java` language and start it from the project directory. Without a workspace
root from the client, the server uses the directory it was started in. Inside an Elide project it reads the
project's classpath, so dependencies resolve.

| Feature | LSP request |
| --- | --- |
| Diagnostics | `publishDiagnostics`, pull diagnostics |
| Completion, signature help | `completion`, `signatureHelp` |
| Hover, inlay hints | `hover`, `inlayHint` |
| Navigation | definition, declaration, type definition, implementation, references |
| Hierarchies | call and type hierarchy |
| Symbols | document and workspace symbols |
| Editing | rename, formatting, code actions, code lens |
| Display | semantic tokens, folding, selection ranges, highlights |

Formatting follows Google Java Format, as `elide javaformat` does.

### Neovim

Neovim 0.11 or later, in `init.lua`:

```lua
vim.lsp.config("elide", {
  cmd = { "elide", "lsp" },
  filetypes = { "java" },
  root_markers = { "elide.pkl" },
})
vim.lsp.enable("elide")
```

Opening a Java file under a directory with `elide.pkl` starts the server; `:checkhealth vim.lsp` lists the client.

### Helix

In `~/.config/helix/languages.toml`:

```toml
[language-server.elide]
command = "elide"
args = ["lsp"]

[[language]]
name = "java"
roots = ["elide.pkl"]
language-servers = ["elide"]
```

`hx --health java` shows `✓ elide` with the binary's path when `elide` is on `PATH`.

## Debug Adapter Protocol

Elide serves the Debug Adapter Protocol (DAP) for JavaScript, TypeScript and Python. Start the program with
`--debugger=dap`; Elide listens on `127.0.0.1:4711` and waits for a client to attach:

```bash
elide run --debugger=dap app.ts
elide test --debugger=dap app.test.ts
```

Point any DAP client at that address with an `attach` request; breakpoints, stepping, variables and the debug console
work as in other DAP adapters. `--debugger-port` and `--debugger-host` change the address. Java and Kotlin programs
use JDWP instead (see [Debugging](https://elide.help/docs/debugging)).

### Neovim (nvim-dap)

```lua
local dap = require("dap")
dap.adapters.elide = { type = "server", host = "127.0.0.1", port = 4711 }
for _, lang in ipairs({ "javascript", "typescript", "python" }) do
  dap.configurations[lang] = {
    { type = "elide", request = "attach", name = "Attach to Elide" },
  }
end
```

Run `elide run --debugger=dap` in a terminal, then `:DapContinue` and pick **Attach to Elide**.

## Coding agents

Agents in your editor connect to Elide over MCP: `elide mcp` for the project and `https://elide.help/mcp` for these
docs. See [Agentic engineering](https://elide.help/docs/agentic-engineering).

---

# Build tool integration

URL: https://elide.help/docs/build-tools

> Use Elide's javac, kotlinc, dependency resolver and JDK from inside an existing Maven, Gradle or Bazel build, without migrating to elide.pkl.

Keep your build tool and use Elide where it runs: as the Java and Kotlin compiler, the dependency resolver, or the JDK.

| Build tool | Integration | Elide compiles | Page |
| --- | --- | --- | --- |
| Maven | `dev.elide:elide-maven-plugin` | Java, Kotlin | [Maven plugin](https://elide.help/docs/build-tools-maven) |
| Gradle | `dev.elide.settings` + `dev.elide` plugins | Java | [Gradle plugin](https://elide.help/docs/build-tools-gradle) |
| Bazel | `rules_elide` module, persistent workers | Java, Kotlin | [Bazel](https://elide.help/docs/build-tools-bazel) |
| Any | `elide project export --format=pom`, `elide mvn` | Java, Kotlin | [POM export and native Maven](https://elide.help/docs/build-tools-export) |
| Any | `JAVA_HOME` set to the Elide distribution | Java | [Build the POM](https://elide.help/docs/build-tools-export#build-the-pom) |

## Integrate or migrate

| | Integrate (this section) | Migrate ([`elide adopt`](https://elide.help/docs/toolchain/usage/adopt)) |
| --- | --- | --- |
| Build definition | Stays `pom.xml`, `build.gradle.kts` or `BUILD.bazel` | Becomes `elide.pkl` |
| Build commands | `mvn`, `./gradlew`, `bazel` | `elide build`, `elide test` |
| What Elide replaces | The compiler, resolver or JDK | The whole build |
| Undo | Remove the plugin or rule | Keep the old build until the new one passes |

## Call the tools directly

Every Elide tool takes the wrapped tool's arguments after `--`, so any build that can run a command can use it:

```bash
elide javac -- -d out -cp lib/guava.jar src/Hello.java
elide kotlinc -- -d out src/Greeter.kt
elide jar -- --create --file app.jar -C out .
```

Per-tool options: [Java compiler](https://elide.help/docs/toolchain/jvm/javac), [Kotlin compiler](https://elide.help/docs/toolchain/jvm/kotlinc),
[JAR assembly](https://elide.help/docs/toolchain/jvm/jar).

## OpenRewrite and dependency queries

Elide also provides experimental [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) and
[dependency code index](https://elide.help/docs/toolchain/jvm/code-index) commands. They read an `elide.pkl` project definition, including
its source sets and Maven dependencies. Compiler integration alone does not connect a Maven, Gradle, or Bazel
dependency graph to those commands.

To use them alongside an existing build, define matching sources, target version, repositories, and dependencies
in `elide.pkl`, or [adopt the project](https://elide.help/docs/toolchain/usage/adopt). Run recipe previews with `elide rewrite ... --dry-run`,
then validate any applied changes with the build's usual tests.

## Publish for Maven and Gradle consumers

A library built with Elide publishes to the local Maven repository, a team repository or Maven Central with
`elide publish`, so Maven and Gradle builds depend on it like any other artifact. See
[Maven publishing](https://elide.help/docs/toolchain/jvm/publishing).

---

# Maven plugin

URL: https://elide.help/docs/build-tools-maven

> Compile Java and Kotlin in an existing Maven build with Elide's javac and kotlinc: the elide-maven-plugin, the Kotlin drop-in, and the compilerId-only setup.

Adding `dev.elide:elide-maven-plugin` to a `pom.xml` makes the build compile Java with `elide javac` and Kotlin
with `elide kotlinc`. Maven keeps dependency resolution, tests, packaging and every other plugin.

## Requirements

| | Version |
| --- | --- |
| Maven | 3.9 or later |
| JDK running Maven | 11 or later |
| Elide | 1.6 or later |

Elide must be on `PATH`, or set `<executable>` (see [Configuration](#configuration)).

## Choose an artifact

| Artifact | Use when | Compiles |
| --- | --- | --- |
| `elide-maven-plugin` | New setup, Java and Kotlin | Java and Kotlin |
| `elide-kotlin-maven-plugin` | The build already uses `kotlin-maven-plugin` | Kotlin; Java through `maven-compiler-plugin` |
| `elide-java-compiler` | Only Java, keeping `maven-compiler-plugin` as is | Java |

All three are in Maven Central under `dev.elide`, version `1.0.0`.

## Install

```xml
<build>
  <plugins>
    <plugin>
      <groupId>dev.elide</groupId>
      <artifactId>elide-maven-plugin</artifactId>
      <version>1.0.0</version>
      <extensions>true</extensions>
    </plugin>
  </plugins>
</build>
```

`<extensions>true</extensions>` is required: it replaces the default compile bindings. With it, the plugin adds
`src/main/kotlin` and `src/test/kotlin` as source roots and a `kotlin-stdlib` dependency when the POM declares none.

To replace `kotlin-maven-plugin` in place, change its coordinates to `dev.elide:elide-kotlin-maven-plugin:1.0.0` and keep
its configuration; it accepts the same parameters.

For Java only, without a new plugin:

```xml
<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.15.0</version>
  <dependencies>
    <dependency>
      <groupId>dev.elide</groupId>
      <artifactId>elide-java-compiler</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
  <configuration>
    <compilerId>elide</compilerId>
  </configuration>
</plugin>
```

## Goals

With extensions on, the goals bind to the lifecycle; nothing needs an `<execution>`.

| Goal | Phase | Runs |
| --- | --- | --- |
| `elide:kapt` | `process-sources` | Skipped unless annotation processors are configured |
| `elide:compile-kotlin` | `compile` | `elide kotlinc` on main sources |
| `elide:compile` | `compile` | `elide javac` on main sources, after Kotlin |
| `elide:test-kapt` | `process-test-sources` | Skipped unless annotation processors are configured |
| `elide:test-compile-kotlin` | `test-compile` | `elide kotlinc` on test sources |
| `elide:test-compile` | `test-compile` | `elide javac` on test sources |

`elide-kotlin-maven-plugin` has the same goals without the Java ones, under the prefix `elide-kotlin`.

## Configuration

Every `maven-compiler-plugin` and `kotlin-maven-plugin` parameter applies (`<release>`, `<compilerArgs>`, `<args>`,
`<jvmTarget>`, …). One parameter is added:

| Parameter | Default | Effect |
| --- | --- | --- |
| `executable` | `elide` on `PATH` | Path to the `elide` binary |

```xml
<plugin>
  <groupId>dev.elide</groupId>
  <artifactId>elide-maven-plugin</artifactId>
  <version>1.0.0</version>
  <extensions>true</extensions>
  <configuration>
    <executable>/opt/elide/bin/elide</executable>
  </configuration>
</plugin>
```

With `elide-java-compiler`, set `<executable>` in the `maven-compiler-plugin` configuration instead.

## Example

A project with a Kotlin object, a Java main class and a JUnit test:

```text
pom.xml
src/main/kotlin/com/example/Greeter.kt
src/main/java/com/example/Hello.java
src/test/java/com/example/GreeterTest.java
```

```xml
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>hello</artifactId>
  <version>1.0.0</version>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.13.4</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>dev.elide</groupId>
        <artifactId>elide-maven-plugin</artifactId>
        <version>1.0.0</version>
        <extensions>true</extensions>
      </plugin>
      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.4</version>
      </plugin>
    </plugins>
  </build>
</project>
```

```bash
mvn package
```

```terminaloutput
[INFO] Added kotlin-stdlib dependency, version 2.3.21
[INFO] --- elide:1.0.0:kapt (default-kapt) @ hello ---
[INFO] No annotation processors configured, skipping kapt
[INFO] --- elide:1.0.0:compile-kotlin (default-compile-kotlin) @ hello ---
[INFO] ✅  Kotlin sources compiled to `classes` (1.3s)
[INFO] --- elide:1.0.0:compile (default-compile) @ hello ---
[INFO] Compiling 1 source file with elide [forked debug release 21] to target/classes
[INFO] --- elide:1.0.0:test-compile (default-test-compile) @ hello ---
[INFO] Compiling 1 source file with elide [forked debug release 21] to target/test-classes
[INFO] --- surefire:3.5.4:test (default-test) @ hello ---
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] --- jar:3.5.0:jar (default-jar) @ hello ---
[INFO] Building jar: target/hello-1.0.0.jar
[INFO] BUILD SUCCESS
```

## OpenRewrite and dependency queries

For projects with an `elide.pkl`, see [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) and
[Dependency code index](https://elide.help/docs/toolchain/jvm/code-index). The compiler plugin does not add rewrite or code-index goals
or pass Maven's resolved dependency graph to those commands. See
[the project setup boundary](https://elide.help/docs/build-tools#openrewrite-and-dependency-queries) before using them alongside Maven.

## Limits

- kapt does not run: a `kapt` execution with annotation processors configured fails.
- Kotlin compiler plugins (`<compilerPlugins>`) other than all-open, no-arg, sam-with-receiver, assignment and Lombok
  fail with a compiler error.
- The added `kotlin-stdlib` is version 2.3.21; declare `kotlin-stdlib` yourself to pick another.
- Each compile runs a new `elide` process; there is no shared compiler daemon between modules.

To run the whole Maven build natively instead, see [POM export and native Maven](https://elide.help/docs/build-tools-export). To leave Maven,
see [Adopt an existing project](https://elide.help/docs/toolchain/usage/adopt).

---

# Gradle plugin

URL: https://elide.help/docs/build-tools-gradle

> Compile Java in an existing Gradle build with `elide javac`: the dev.elide settings and project plugins, runtime selection, persistent compilers, formatting tasks and dependency export.

The `dev.elide.settings` and `dev.elide` plugins make Gradle's `JavaCompile` tasks run `elide javac`, and add
formatting and dependency-export tasks. Gradle keeps dependency resolution, tests and packaging.

## Requirements

| | Version |
| --- | --- |
| Gradle | 7.6.4 or later |
| JDK running Gradle | 17 or later |
| Plugins | 1.2.0, from Maven Central |
| Elide | 1.6 |

## Install

`settings.gradle.kts` adds Maven Central to the plugin repositories and selects the Elide runtime for the whole build:

```kotlin
import dev.elide.gradle.ElideRuntimeMode

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

plugins {
    id("dev.elide.settings") version "1.2.0"
}

elide {
    runtime {
        mode = ElideRuntimeMode.MANAGED
        version = "1.6.0"
    }
}
```

Each project that should compile with Elide applies `dev.elide`, with no version:

```kotlin
// build.gradle.kts
plugins {
    id("dev.elide")
    java
}

elide {
    compiler = true
}
```

On Gradle 7.6, configure the settings extension with `configure<dev.elide.gradle.ElideSettingsExtension> { runtime { … } }`.

## Runtime selection

| `mode` | Uses |
| --- | --- |
| `AUTO` (default) | `runtime.executable` if set, then `elide` on `PATH` if it reports at least `version`, then the managed runtime |
| `PATH` | `elide` on `PATH`; fails if it is older than `version` |
| `MANAGED` | Downloads `version` once into `<GRADLE_USER_HOME>/caches/dev.elide/runtimes/`, verifies its SHA-256, reuses it offline |

```kotlin
elide {
    runtime {
        mode = ElideRuntimeMode.PATH
        executable = layout.projectDirectory.file("tools/elide")
    }
}
```

Managed downloads cover Linux x86_64 and arm64, macOS arm64 and Windows x86_64. Applying the plugin downloads and runs
nothing; the runtime is prepared when a task needs it.

## Configuration

Project `elide { }` block:

| Property | Default | Effect |
| --- | --- | --- |
| `compiler` | `true` | Compile `JavaCompile` tasks with `elide javac` |
| `persistentCompiler` | `false` | Keep up to four `elide javac` workers warm for the rest of the build |
| `dependencyMode` | `LEGACY` | `GRADLE`: Gradle owns resolution; `install` must stay off |
| `install` | `false` | Run `elide install` from `elide.pkl` before compiling |
| `maven` | `true` | With `install`, add `.dev/dependencies/m2` as a Maven repository |
| `manifest` | `elide.pkl` | Manifest `install` reads |

Gradle properties override the block for a run, in both directions:

| Property | Effect |
| --- | --- |
| `elide.builder.javac.enable=false` | Compile with stock `javac` |
| `elide.builder.maven.install.enable=true` | Force `elide install` on |

```bash
./gradlew build -Pelide.builder.javac.enable=false
```

## Tasks

| Task | Does |
| --- | --- |
| `prepareElideRuntime` | Downloads and verifies the managed runtime |
| `elideInstall` | Runs `elide install`; skipped unless `install = true` |
| `elideCheckFormat` | Fails when `.java`, `.kt` or `.kts` files under `src/` need formatting; changes nothing |
| `elideFormat` | Formats them in place |
| `elideExportDependencies` | Writes resolved coordinates and SHA-256 per source set to `build/elide/dependencies/` |

`compileJava` and `compileTestJava` keep their task types, so incremental compilation and the build cache work as
usual.

## Example

```text
settings.gradle.kts
build.gradle.kts
src/main/java/com/example/HelloWorld.java
src/test/java/com/example/HelloWorldTest.java
```

```kotlin
// build.gradle.kts
plugins {
    id("dev.elide")
    java
    application
}

application {
    mainClass = "com.example.HelloWorld"
}

repositories {
    mavenCentral()
}

elide {
    compiler = true
}

dependencies {
    implementation("com.google.guava:guava:33.4.8-jre")
    testImplementation("org.junit.jupiter:junit-jupiter:5.13.4")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
}
```

With the `settings.gradle.kts` from [Install](#install):

```bash
./gradlew clean build run
```

```terminaloutput
> Task :prepareElideRuntime UP-TO-DATE
> Task :elideInstall SKIPPED
> Task :clean
> Task :compileJava
> Task :jar
> Task :run
Hello, World!
> Task :compileTestJava
> Task :test
> Task :build
BUILD SUCCESSFUL in 5s
Configuration cache entry stored.
```

The first run downloads Elide in `prepareElideRuntime`; later runs reuse it.

## OpenRewrite and dependency queries

For projects with an `elide.pkl`, see [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) and
[Dependency code index](https://elide.help/docs/toolchain/jvm/code-index). The Gradle plugin does not add rewrite or code-index tasks;
`elideExportDependencies` exports coordinates and checksums, but its output is not an input to `elide index`.
See [the project setup boundary](https://elide.help/docs/build-tools#openrewrite-and-dependency-queries) before using these commands
alongside Gradle.

## Limits

- Only Java compilation goes through Elide. Kotlin (`compileKotlin`) uses the Kotlin Gradle plugin's compiler.
- `persistentCompiler` does not support `forkOptions.jvmArgs`.
- `MANAGED` is unavailable on Intel macOS; use `PATH` there.
- `elideFormat` covers sources under `src/` only.

---

# Bazel

URL: https://elide.help/docs/build-tools-bazel

> Compile, test and format Java and Kotlin in Bazel with rules_elide, swap rules_kotlin's builder, or call `elide javac` and `elide kotlinc` as persistent workers from your own rules.

`rules_elide` is a Bazel module with Java and Kotlin rules that compile through `elide javac` and `elide kotlinc`
running as persistent workers. It downloads Elide itself; no JDK or Kotlin toolchain is needed.

## Requirements

| | Version |
| --- | --- |
| Bazel | 8 or 9, with Bzlmod |
| `rules_elide` | 0.7.0 |
| Elide | 1.6.0-rc.2 (the default) |
| Platforms | Linux x86_64 and arm64, macOS arm64 |

## Install

```python
# MODULE.bazel
bazel_dep(name = "rules_elide", version = "0.7.0")

elide = use_extension("@rules_elide//elide:extensions.bzl", "elide")
elide.install(version = "1.6.0-rc.2")
use_repo(elide, "elide_toolchains")
register_toolchains("@elide_toolchains//:all")
```

`elide.install()` downloads the Elide release for the host and checks it against a pinned hash; `version` must be one
the module lists. To use an Elide you installed yourself:

```python
elide.use(local_path = "/opt/elide")
```

## Rules

Load from `@rules_elide//elide:defs.bzl`.

| Rule | Does |
| --- | --- |
| `elide_java_library` | Compiles `.java` sources into a JAR |
| `elide_java_binary` | Library plus a launcher (`bazel run`) |
| `elide_java_test` | Library plus a JUnit Platform launcher (`bazel test`) |
| `elide_kotlin_library` | Compiles `.kt` and mixed `.kt`/`.java` sources |
| `elide_kotlin_binary`, `elide_kotlin_test` | As the Java variants, for Kotlin |
| `elide_format` | `bazel run` target that formats sources in place (Java or Kotlin, one per target) |
| `elide_native_image` | Native binary from JVM targets |

Every compile rule returns `JavaInfo`, so `java_library`, `kt_jvm_library` and `rules_jvm_external` targets mix freely
in `deps`. Test rules need `org.junit.platform:junit-platform-console-standalone` in `runtime_deps`.

Full attribute reference: [rules_elide docs](https://github.com/elide-dev/rules_elide/tree/main/docs).

## Example

```text
MODULE.bazel
BUILD.bazel
src/Greeter.java
src/App.kt
src/GreeterTest.java
```

```python
# MODULE.bazel
module(name = "hello")

bazel_dep(name = "rules_elide", version = "0.7.0")
bazel_dep(name = "rules_jvm_external", version = "7.1")

elide = use_extension("@rules_elide//elide:extensions.bzl", "elide")
elide.install(version = "1.6.0-rc.2")
use_repo(elide, "elide_toolchains")
register_toolchains("@elide_toolchains//:all")

maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
maven.install(
    artifacts = [
        "org.junit.jupiter:junit-jupiter-api:5.13.4",
        "org.junit.platform:junit-platform-console-standalone:1.13.4",
    ],
)
use_repo(maven, "maven")
```

```python
# BUILD.bazel
load("@rules_elide//elide:defs.bzl", "elide_java_library", "elide_java_test", "elide_kotlin_binary")

elide_java_library(
    name = "greeter",
    srcs = ["src/Greeter.java"],
)

elide_kotlin_binary(
    name = "app",
    srcs = ["src/App.kt"],
    main_class = "AppKt",
    deps = [":greeter"],
)

elide_java_test(
    name = "greeter_test",
    srcs = ["src/GreeterTest.java"],
    test_class = "GreeterTest",
    runtime_deps = ["@maven//:org_junit_platform_junit_platform_console_standalone"],
    deps = [
        ":greeter",
        "@maven//:org_junit_jupiter_junit_jupiter_api",
    ],
)
```

```bash
bazel build //...
bazel run //:app
bazel test //:greeter_test
```

```terminaloutput
INFO: 35 processes: 12 internal, 16 linux-sandbox, 7 worker.
INFO: Build completed successfully, 35 total actions

Hello, Bazel

//:greeter_test                                                 PASSED in 2.0s
Executed 1 out of 1 test: 1 test passes.
```

## Persistent workers

The compile rules run `elide javac --persistent_worker` and `elide kotlinc --persistent_worker`: one warm process per
tool serves every compile action, accepting concurrent requests and compiling them one at a time. `bazel shutdown`
stops them.

To compile each target in a new process (for example under remote execution):

```bash
bazel build --@rules_elide//elide:use_workers=false //...
```

### Workers from your own rules

Without `rules_elide`, any rule can run Elide as a worker. Bazel adds `--persistent_worker` itself; the rule passes
arguments in a parameter file:

```python
# elide.bzl
def _elide_javac_impl(ctx):
    out = ctx.actions.declare_directory(ctx.label.name + "_classes")
    args = ctx.actions.args()
    args.add("-d", out.path)
    args.add_all(ctx.files.srcs)
    args.use_param_file("@%s", use_always = True)
    args.set_param_file_format("multiline")
    ctx.actions.run(
        executable = ctx.executable._elide,
        arguments = ["javac", args],
        inputs = ctx.files.srcs,
        outputs = [out],
        mnemonic = "ElideJavac",
        execution_requirements = {"supports-workers": "1", "supports-multiplex-workers": "1"},
    )
    return [DefaultInfo(files = depset([out]))]

elide_javac = rule(
    implementation = _elide_javac_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = [".java"]),
        "_elide": attr.label(default = "//tools:elide", executable = True, cfg = "exec", allow_single_file = True),
    },
)
```

```python
# BUILD.bazel
load(":elide.bzl", "elide_javac")

elide_javac(
    name = "hello",
    srcs = glob(["src/*.java"]),
)
```

```bash
mkdir -p tools && ln -s "$(command -v elide)" tools/elide
echo 'exports_files(["elide"])' > tools/BUILD.bazel
bazel build //:hello
```

```text
Target //:hello up-to-date:
  bazel-bin/hello_classes
INFO: 2 processes: 1 internal, 1 worker.
```

For `javac`, pass `["javac", "--classpath-cache", args]` to reuse parsed classpath JARs between requests. A `kotlinc`
rule takes the same form, without `--classpath-cache`.

## Keep `kt_jvm_*` targets

`register_elide_kotlin_toolchain` from `@rules_elide//elide/kotlin:toolchain.bzl` replaces the builder of a
`rules_kotlin` toolchain, so existing `kt_jvm_library`, `kt_jvm_binary` and `kt_jvm_test` targets compile with Elide
without BUILD changes. Targets with annotation processors fall back to the stock `rules_kotlin` builder. Setup:
[KotlinBuilder shim](https://github.com/elide-dev/rules_elide/blob/main/docs/kotlin_builder.md).

## OpenRewrite and dependency queries

For projects with an `elide.pkl`, see [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) and
[Dependency code index](https://elide.help/docs/toolchain/jvm/code-index). These commands do not consume Bazel's `JavaInfo` or its target
graph, and the rules listed above do not add a rewrite or code-index target. See
[the project setup boundary](https://elide.help/docs/build-tools#openrewrite-and-dependency-queries) before using them alongside Bazel.

## Limits

- Windows is not supported.
- `elide.install` accepts only versions listed in the module; use `elide.use` for others.
- Kotlin compiler plugins from external JARs (the `plugins` attribute of `elide_kotlin_*` rules) other than all-open,
  no-arg, sam-with-receiver, assignment and Lombok fail with a compiler error.

---

# POM export and native Maven

URL: https://elide.help/docs/build-tools-export

> Hand an Elide project to Maven and other tools with `elide project export` (POM, JSON, IntelliJ model), and build the result with `elide mvn` or stock Maven.

`elide project export` renders an `elide.pkl` project as a model other tools read. `--format=pom` writes a Maven
`pom.xml`, which `elide mvn` or any Maven 3.9+ install builds.

## Export

```bash
elide project export --format=pom > pom.xml
elide project export --format=json          # resolved manifest
elide project export --format=intellij      # IntelliJ workspace model
elide project export -p app --format=pom    # another project directory
```

Pass the format as `--format=<value>`; the output goes to stdout.

| Format | Contents |
| --- | --- |
| `json` (default) | The manifest after Pkl evaluation |
| `pom` | A Maven POM: coordinates, dependencies with scopes, compiler release, source roots |
| `intellij` | Modules per source set, content and source roots, library dependencies, JDK level |

### What the POM contains

| `elide.pkl` | `pom.xml` |
| --- | --- |
| `name` | `<groupId>`, `<artifactId>` and `<name>` (a workspace member takes the workspace name as `<groupId>`) |
| `version` | `<version>`; `0.0.0` when unset |
| `jvm.target`, `jvm.java.release` | `maven.compiler.release`, `.source`, `.target` |
| `packages`, `modules` | compile scope |
| `compileOnly`, `devPackages`, `processors` | `provided` |
| `runtimeOnly` | `runtime` |
| `testPackages` | `test` |
| A local JAR path | `system` scope with `${project.basedir}` path |
| Source sets | `<sourceDirectory>`, `<testSourceDirectory>`; extra roots through `build-helper-maven-plugin` |
| Workspace members | `<modules>` on the root, `<parent>` on each member |
| A `Jar.from` sibling | Its `packages`, `modules` and `runtimeOnly`, unless already listed |

Not exported: `exclusions`, `substitutions` and `kotlinPlugins`. Repositories declared in the manifest are exported.

## Build the POM

| Runner | Command | Needs |
| --- | --- | --- |
| [Native Maven](https://elide.help/docs/toolchain/jvm/native-maven) | `elide mvn -- package` | Nothing else |
| Stock Maven 3.9+ | `mvn package` | `JAVA_HOME` set to the Elide distribution, or any JDK |

Point `JAVA_HOME` at the directory that holds `bin/elide`; its `bin/java` and `bin/javac` run Maven, its compiler and
its forked test JVMs as a JDK 25 would:

```bash
export JAVA_HOME="$(dirname "$(dirname "$(readlink -f "$(command -v elide)")")")"
mvn package
```

To compile with `elide javac` and `elide kotlinc` inside an existing POM, use the [Maven plugin](https://elide.help/docs/build-tools-maven).

## Example

```pkl
amends "elide:project.pkl"

name = "hello"
version = "1.0.0"

dependencies {
  maven {
    packages { "com.google.guava:guava:33.4.8-jre" }
    testPackages { "org.junit.jupiter:junit-jupiter:5.13.4" }
  }
}

jvm {
  main = "com.example.Hello"
  target = 17
}
```

```bash
elide project export --format=pom > pom.xml
```

```xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>hello</groupId>
  <artifactId>hello</artifactId>
  <version>1.0.0</version>
  <name>hello</name>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <maven.compiler.target>17</maven.compiler.target>
    <maven.compiler.source>17</maven.compiler.source>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>33.4.8-jre</version>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.13.4</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <sourceDirectory>src/main/java</sourceDirectory>
    <testSourceDirectory>src/test/java</testSourceDirectory>
  </build>
</project>
```

```bash
elide mvn -- package
```

```terminaloutput
Running com.example.HelloTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.275 s -- in com.example.HelloTest
Building jar: target/hello-1.0.0.jar
BUILD SUCCESS
Total time:  5.041 s
```

## Limits

- The export is one-way: Elide never reads the generated file back. Regenerate it after changing `elide.pkl`.
- `name` becomes the coordinates. A name with spaces or other characters Maven rejects needs a hand-edited
  `<groupId>` and `<artifactId>`.
- Only `build-helper-maven-plugin` is declared. Kotlin sources need a Kotlin compiler added to the build, such as
  [Elide's](https://elide.help/docs/build-tools-maven).
- Elide's built-in test dependencies are not added; declare test frameworks in `testPackages`.

---

# Build an HTTP service

URL: https://elide.help/docs/http-service

> Serve HTTP from Elide with a fetch handler or node:http: routing, JSON bodies, streaming, static files, TLS, several contexts and frameworks.

Elide serves HTTP from a fetch handler or from `node:http`; this page builds one service both ways.

For a new service, start with [Two ways to serve](#two-ways-to-serve), which needs no packages. For an existing
framework app, check the table below before installing dependencies.

## Frameworks

Checked with Elide 1.6.2:

| Framework | Support | Next step |
| --- | --- | --- |
| Hono 4.13.16 | Routing and JSON work with a fetch handler. | Follow the [Hono example](#hono-example). |
| Express 5.3.0 | Partial: routing, `res.json`, `express.raw()` and manual body reads work; `express.json()` and `express.text()` stop the process with `TypeError: Buffer.isBuffer is not a function`. | Use manual body reads or `express.raw()`; see [Express body parsing](https://elide.help/docs/troubleshooting#express-expressjson-stops-the-server). |
| Fastify 5.12.8 | Fails at import: `Error: No such built-in module: node:http2`. | Use a fetch handler or `node:http`; see [missing built-in modules](https://elide.help/docs/troubleshooting#no-such-built-in-module). |

For individual Node modules, check the [API Overview](https://elide.help/docs/api-overview). Run your application's tests and send requests
through its middleware before migrating a service.

## Two ways to serve

| | Fetch handler | `node:http` |
| --- | --- | --- |
| Entry | `export default { fetch }` or `Elide.serve({ fetch })` | `http.createServer(listener).listen(port)` |
| Request and response | Web `Request`, `Response` | `IncomingMessage`, `ServerResponse` |
| HTTPS and HTTP/2 | `cert` and `key` options | Not available |
| `--contexts` | Yes | No; the second copy fails with `EADDRINUSE` |

```ts
// server.ts
export default {
  port: Number(process.env.PORT ?? 3000),
  fetch(request: Request): Response {
    return new Response("hello\n");
  },
};
```

```ts
// node-server.ts
import { createServer } from "node:http";

const port = Number(process.env.PORT ?? 3000);

createServer((req, res) => {
  res.writeHead(200, { "content-type": "text/plain" });
  res.end("hello\n");
}).listen(port, "127.0.0.1");
```

```bash
elide run server.ts
```

Keep the server running and send a request from a second terminal:

```bash
curl -i http://127.0.0.1:3000/
```

```text
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
content-length: 6
server: elide
date: Sat, 10 Oct 2026 00:18:12 GMT

hello
```

`elide run node-server.ts` answers the same request with `Transfer-Encoding: chunked` and `Connection: keep-alive`.
If the port is occupied, see [Port already in use](https://elide.help/docs/troubleshooting#port-already-in-use).

Where each style binds when you give no address:

| Server | Default address |
| --- | --- |
| `export default { fetch }` under `elide run` | `127.0.0.1:8080` |
| `export default { fetch }` under `elide serve` / `elide dev` | `127.0.0.1:8080` / `127.0.0.1:3000`; `--host` and `--port` override |
| `Elide.serve({ port, fetch })` | `0.0.0.0` on `port` |

## Routes, JSON and streaming

`URLPattern`, `Request.json()`, `Response.json()` and `ReadableStream` bodies are globals. This server has an API, a
streamed response and static files from `public/`:

```ts
// app.ts
import { readFile } from "node:fs/promises";
import { extname, join, normalize } from "node:path";

const users = new URLPattern({ pathname: "/api/users/:id" });
const types: Record<string, string> = {
  ".html": "text/html; charset=utf-8",
  ".css": "text/css",
  ".js": "text/javascript",
};

async function api(request: Request): Promise<Response | null> {
  const url = new URL(request.url);
  const match = users.exec(url);
  if (match && request.method === "GET") {
    return Response.json({ id: match.pathname.groups.id });
  }
  if (url.pathname === "/api/users" && request.method === "POST") {
    const body = await request.json();
    return Response.json({ created: body.name }, { status: 201 });
  }
  if (url.pathname === "/api/ticks") {
    let n = 0;
    const stream = new ReadableStream({
      async pull(controller) {
        controller.enqueue(new TextEncoder().encode(`tick ${++n}\n`));
        await new Promise((r) => setTimeout(r, 200));
        if (n === 3) controller.close();
      },
    });
    return new Response(stream, { headers: { "content-type": "text/plain" } });
  }
  return null;
}

async function file(pathname: string): Promise<Response> {
  const path = join("public", normalize(pathname === "/" ? "/index.html" : pathname));
  try {
    const body = await readFile(path);
    return new Response(body, { headers: { "content-type": types[extname(path)] ?? "application/octet-stream" } });
  } catch {
    return new Response("not found\n", { status: 404 });
  }
}

export default {
  port: Number(process.env.PORT ?? 3000),
  async fetch(request: Request): Promise<Response> {
    return (await api(request)) ?? file(new URL(request.url).pathname);
  },
};
```

```bash
elide run app.ts
curl http://127.0.0.1:3000/api/users/42
curl -X POST -H 'content-type: application/json' -d '{"name":"ada"}' http://127.0.0.1:3000/api/users
curl -N http://127.0.0.1:3000/api/ticks
```

```text
{"id":"42"}
{"created":"ada"}
tick 1
tick 2
tick 3
```

The POST answers `201 Created`. The three ticks arrive 200 ms apart. `/` returns `public/index.html`, and a missing file
returns `404`.

The same API on `node:http` reads the body with `node:stream/consumers` and streams with `res.write`:

```ts
// node-app.ts
import { createServer } from "node:http";
import { text } from "node:stream/consumers";

createServer(async (req, res) => {
  if (req.method === "POST" && req.url === "/api/users") {
    const body = JSON.parse(await text(req));
    res.writeHead(201, { "content-type": "application/json" });
    res.end(JSON.stringify({ created: body.name }));
    return;
  }
  if (req.url === "/api/ticks") {
    res.writeHead(200, { "content-type": "text/plain" });
    for (let n = 1; n <= 3; n++) {
      res.write(`tick ${n}\n`);
      await new Promise((r) => setTimeout(r, 200));
    }
    res.end();
    return;
  }
  res.writeHead(404).end();
}).listen(Number(process.env.PORT ?? 3000), "127.0.0.1");
```

To serve only files, use `elide serve ./public`; see [Development Server](https://elide.help/docs/dev-server).

## Errors

A fetch handler that throws or rejects answers `500 Internal Server Error` and keeps serving. The error is not printed,
so catch and log it yourself:

```bash
curl -i -d 'not json' http://127.0.0.1:3000/api/users
```

```text
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
content-length: 21
server: elide
date: Sat, 10 Oct 2026 00:34:28 GMT

Internal Server Error
```

## TLS

Pass PEM strings as `cert` and `key` to `Elide.serve`, or as properties of the exported object. The key must be
unencrypted PKCS#8 (`BEGIN PRIVATE KEY`). Clients that offer HTTP/2 get it.

```ts
// tls.ts
import { readFileSync } from "node:fs";

Elide.serve({
  port: Number(process.env.PORT ?? 8443),
  cert: readFileSync("cert.pem", "utf8"),
  key: readFileSync("key.pem", "utf8"),
  fetch(request) {
    return new Response("hello over tls\n");
  },
});
```

```bash
elide run tls.ts
curl -i --cacert cert.pem https://localhost:8443/
```

```text
HTTP/2 200
content-type: text/plain;charset=UTF-8
content-length: 15
server: elide
date: Sat, 10 Oct 2026 00:18:52 GMT

hello over tls
```

`elide serve` and `elide dev` have no TLS flags, and `elide.pkl` has no TLS settings. `https.createServer` throws:

```text
Error: HTTPS server is not supported in this runtime (no host TLS listener); use http.createServer behind a TLS terminator, or https client APIs.
```

## Several contexts

`--contexts=N` runs `N` copies of a fetch-handler app on one port, on Linux. Each copy has its own module state:

```ts
// counter.ts
let count = 0;

export default {
  fetch(): Response {
    count += 1;
    return new Response(`${count}\n`);
  },
};
```

```bash
elide serve --no-tui --contexts=4 counter.ts
for i in 1 2 3 4 5 6 7 8; do curl -s http://127.0.0.1:8080/; done
```

```text
1
1
2
2
3
4
1
2
```

Keep shared state in a database or another service. `--contexts=auto` sizes from the CPU cores; `engine.contexts` in
`elide.pkl` sets it per project ([Engine contexts](https://elide.help/docs/elide-pkl-reference#engine-contexts)).

## Hono example

In an empty directory, save this as `package.json`:

```json
{
  "type": "module",
  "dependencies": {
    "hono": "4.13.16"
  }
}
```

Install the dependency, then save the server below as `hono-app.ts`:

```bash
elide install --ecosystems=npm
```

For `package.json` dependencies, include `--ecosystems=npm`. If Hono cannot be imported, see
[Module not found after `elide install`](https://elide.help/docs/troubleshooting#module-not-found-after-elide-install).

```ts
// hono-app.ts
import { Hono } from "hono";

const app = new Hono();
app.get("/users/:id", (c) => c.json({ id: c.req.param("id") }));
app.post("/users", async (c) => c.json({ created: (await c.req.json()).name }, 201));

export default {
  port: Number(process.env.PORT ?? 3000),
  fetch: app.fetch,
};
```

Start the server:

```bash
elide run hono-app.ts
```

From a second terminal, check both routes:

```bash
curl http://127.0.0.1:3000/users/42
curl -X POST -H 'content-type: application/json' -d '{"name":"ada"}' http://127.0.0.1:3000/users
```

```text
{"id":"42"}
{"created":"ada"}
```

The POST returns `201 Created`. Stop the server with Ctrl+C. If a request returns `500`, see
[A request returns 500 with no error printed](https://elide.help/docs/troubleshooting#a-request-returns-500-with-no-error-printed).

## Samples

- [HTTP handler](https://elide.help/docs/code-samples#http-handler)
- [Routes with URLPattern](https://elide.help/docs/code-samples#routes-with-urlpattern)
- [Local server and fetch](https://elide.help/docs/code-samples#local-server-and-fetch)
- [Server-sent events](https://elide.help/docs/code-samples#server-sent-events)
- [Request limits](https://elide.help/docs/code-samples#request-limits)
- [Multi-context server](https://elide.help/docs/code-samples#multi-context-server)

## Next steps

- [Deploy an Elide App](https://elide.help/docs/deploy)
- [Elide Global](https://elide.help/docs/api-globals-elide) and [node:http](https://elide.help/docs/api-node-http)
- [Troubleshooting](https://elide.help/docs/troubleshooting)

---

# Build a polyglot app

URL: https://elide.help/docs/polyglot

> Combine an npm package and a PyPI package in one Elide program: pass values, functions and errors between JavaScript and Python with --interop.

This page builds one program that uses an npm package from JavaScript and a PyPI package from Python, in one process.

| Needs | How |
| --- | --- |
| Python | `elide setup python`; `elide info` lists `python` under `Languages` |
| Cross-language calls | `--interop` on every run; there is no manifest setting |
| npm packages | `dependencies.npm` in `elide.pkl`, then `elide install --ecosystems=npm` |
| PyPI packages | A Python 3.13 virtual environment, selected with `VIRTUAL_ENV` |

## Set up the project

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "poly"

dependencies {
  npm { packages { "pretty-ms@9.3.1" } }
  pypi { packages { "humanize==4.12.3" } }
}
```

```bash
elide install --ecosystems=npm
```

A bare `elide install` installs Maven only. Elide does not install PyPI packages: `elide install --ecosystems=pypi`
exits `2` with `pypi installs are not available in this build`. Keep the `pypi` block as the record, and install it
with a Python 3.13 `pip` into a virtual environment:

```bash
python3.13 -m venv .venv
.venv/bin/pip install humanize==4.12.3
export VIRTUAL_ENV=$PWD/.venv
```

Elide loads packages from `$VIRTUAL_ENV/lib/python3.13/site-packages`. Pure-Python packages work; some C extension
modules do not load (see [Python](https://elide.help/docs/python#known-limitations)).

## Write the program

```python
# report.py
import humanize

def size(n):
    return humanize.naturalsize(n)

def summarize(files):
    total = sum(f.bytes for f in files)
    return {"count": len(files), "total": humanize.naturalsize(total)}
```

```javascript
// app.mjs
import prettyMs from "pretty-ms";
import report from "./report.py";

const files = [
  { name: "build.log", bytes: 1_500_000, ageMs: 172_800_000 },
  { name: "test.log", bytes: 32_000, ageMs: 5_400_000 },
];

for (const f of files) {
  console.log(`${f.name}: ${report.size(f.bytes)}, ${prettyMs(f.ageMs)} old`);
}

const summary = report.summarize(files);
console.log(`${summary.count} files, ${summary.total}`);
```

```bash
elide --interop run app.mjs
```

```text
build.log: 1.5 MB, 2d old
test.log: 32.0 kB, 1h 30m old
2 files, 1.5 MB
```

A Python file's default export is its module; import it from an `.mjs` entry. Two common failures:

| Missing | Error |
| --- | --- |
| `--interop` | `Error: Cannot import 'report.py': JavaScript entries run without Python. Re-run with --interop to use it.` |
| `VIRTUAL_ENV` | `ModuleNotFoundError: No module named 'humanize'` |

## Pass values

```python
# shapes.py
def label(order):
    return f"{order.item} x{order.qty}"

def doubled(prices):
    return [p * 2 for p in prices]

def config():
    return {"region": "eu", "retries": 3}

def apply(fn, value):
    return fn(value)

def fail():
    raise ValueError("bad input")
```

```javascript
// values.mjs
import shapes from "./shapes.py";

console.log(shapes.label({ item: "bolt", qty: 4 }));
console.log(shapes.doubled([1, 2.5, 3]).map((n) => n + 1));
const config = shapes.config();
console.log(config.region, config.get("retries"));
console.log(JSON.stringify(Object.fromEntries(config.items())));
console.log(shapes.apply((s) => s.toUpperCase(), "shout"));
console.log(shapes.apply((v) => v, null), shapes.apply((v) => v, undefined));
```

```bash
elide --interop run values.mjs
```

```text
bolt x4
(3)[3, 6, 7]
eu 3
{"region":"eu","retries":3}
SHOUT
null undefined
```

| Value | From JavaScript into Python | From Python into JavaScript |
| --- | --- | --- |
| Numbers, strings, booleans | Native values | Native values |
| `null`, `undefined` / `None` | `None`, and back unchanged | `null` |
| Object / `dict` | Read fields as attributes (`order.item`); `order["item"]` raises `TypeError` | Read keys as `d.key`, `d["key"]` or `d.get("key")`; `Object.keys`, `in` and `JSON.stringify` see the dict's methods, not its keys. Convert with `Object.fromEntries(d.items())`. |
| Array / `list` | Iterable, indexable, `len()` works | `Array.isArray` is `true`; `map`, spread and `Array.from` work |
| Function | Callable | Callable |

## Call JavaScript from Python

The `elide` module evaluates JavaScript and returns its value:

```python
# calls.py
from elide import js

slug = js("(s) => s.trim().toLowerCase().replaceAll(' ', '-')")
print(slug("  Hello Polyglot World "))

point = js("({ x: 1, y: 2, tags: ['a', 'b'] })")
print(point.x + point.y, point.tags[0], len(point.tags))
print(sorted(js("[3, 1, 2]")))

try:
    js("JSON.parse('{oops')")
except RuntimeError as e:
    print("caught:", e)

js("Promise.resolve(42)").then(lambda v: print("resolved:", v))
```

```bash
elide --interop python calls.py
```

```text
hello-polyglot-world
3 a 2
[1, 2, 3]
caught: JSException: SyntaxError: Unexpected token o in JSON at position 1
resolved: 42
```

## Handle errors

A Python exception reaches JavaScript as an `Error` whose `name` is the exception class; a JavaScript error reaches
Python as `RuntimeError`. An uncaught error prints one stack across both languages:

```javascript
// errors.mjs
import shapes from "./shapes.py";

try {
  shapes.fail();
} catch (e) {
  console.log(e.name, "|", e.message);
}

shapes.apply((x) => {
  throw new RangeError(`bad value ${x}`);
}, 7);
```

```bash
elide --interop run errors.mjs
```

```text
ValueError | ValueError: bad input
RangeError: bad value 7
    at :=> (errors.mjs:10:9)
    at apply (shapes.py:11:12)
    at :module:eval (errors.mjs:9:1)
```

The program exits `1`.

## Call async code

| From | Works | Does not work |
| --- | --- | --- |
| JavaScript calling Python | Call a sync wrapper that runs `asyncio.run(...)` | `await` on a Python coroutine returns the coroutine, unrun |
| Python holding a JavaScript promise | `promise.then(callback)` | `await promise` raises `TypeError: object polyglot.ForeignObject can't be used in 'await' expression` |

```python
# rates.py
import asyncio

async def fetch_rate(code):
    await asyncio.sleep(0.01)
    return {"EUR": 0.92, "GBP": 0.79}[code]

def rate(code):
    return asyncio.run(fetch_rate(code))

def when_ready(promise, done):
    promise.then(lambda value: done(f"python saw {value}"))
```

```javascript
// rates.mjs
import rates from "./rates.py";

console.log("rate:", rates.rate("EUR"));

const total = new Promise((resolve) => setTimeout(() => resolve(7), 10));
rates.when_ready(total, (msg) => console.log(msg));
await total;
```

```bash
elide --interop run rates.mjs
```

```text
rate: 0.92
python saw 7
```

`asyncio.run` blocks the JavaScript event loop until the coroutine finishes. Python threads are not available under
`--interop`.

## Java and Kotlin

`elide run Hello.kt` runs Kotlin on its own; JavaScript and Python cannot call it. Importing it fails:

```javascript
import hello from "./Hello.kt";
```

```text
TypeError: Unsupported file extension: 'file:/path/to/Hello.kt'
```

See also [Languages and Interop](https://elide.help/docs/languages), [Python](https://elide.help/docs/python) and [NPM Installer](https://elide.help/docs/toolchain/web/npm).

## Samples

- [Python calling JavaScript](https://elide.help/docs/code-samples#python-calling-javascript)
- [JavaScript importing Python](https://elide.help/docs/code-samples#javascript-importing-python)

---

# TypeScript and modules

URL: https://elide.help/docs/typescript-and-modules

> What Elide's TypeScript type stripping accepts and rejects, JSX, type checking with tsc and @elide-dev/types, and how ES modules, CommonJS, JSON and exports resolve.

Elide runs `.ts`, `.mts`, `.cts` and `.tsx` files by removing their types; it does not type-check them or read
`tsconfig.json`.

## Script arguments

JavaScript and TypeScript entry files receive the same `process.argv` layout: the executable path,
the absolute entry-file path, then the application arguments. For example:

```bash
elide --timeout=10s run main.ts -- alpha 'two words'
```

Here `process.argv.slice(2)` is `["alpha", "two words"]`; neither `--timeout=10s` nor `run` appears in
the array. Direct execution (`elide main.ts -- alpha 'two words'`) uses the same layout, as does a
named manifest script that invokes the entry file. `process.execArgv` is empty; it does not contain
Elide launcher options. The initial `--` separates launcher and application arguments; subsequent
`--` tokens are preserved as application arguments.

## TypeScript syntax

| Syntax | Status |
| --- | --- |
| Type annotations, interfaces, `type`, generics, `as`, `satisfies`, `!` | Removed |
| `import type`, `import { type X }` | Removed |
| `enum`, `const enum` | Compiled to objects |
| `namespace` | Compiled |
| Constructor parameter properties (`constructor(public x: number)`) | Compiled |
| `abstract`, `declare` fields, `override`, `accessor` | Supported |
| `import fs = require("node:fs")` | Supported |
| Decorators on classes and methods | Standard decorators: each receives `(value, context)` |
| `experimentalDecorators`-style decorators | Not supported; they receive standard arguments |
| Parameter decorators (`constructor(@inject x)`) | `SyntaxError: … expected BindingIdentifier or BindingPattern` |
| `<string>value` type assertions | `Precompiler failed with 1 diagnostic(s): … [ERROR] Unexpected token`; use `value as string` |
| `export = value` | `SyntaxError: … Expected an operand but found export` |
| `tsconfig.json` `paths` | Ignored: `TypeError: Module not found: '@lib/math'` |

Imports may name the `.ts` file, a `.js` extension, or no extension; all three resolve to `math.ts`:

```ts
import { add } from "./src/lib/math.ts";
import { add as add2 } from "./src/lib/math.js";
import { add as add3 } from "./src/lib/math";
console.log(add(1, 2), add2(2, 2), add3(3, 3));
```

```text
3 4 6
```

## JSX

`.tsx` files use the automatic JSX runtime and import `react/jsx-runtime`. Install React yourself:

```tsx
// app.tsx
import { renderToString } from "react-dom/server";

function Hello({ name }: { name: string }) {
  return <p>hello {name}</p>;
}

console.log(renderToString(<Hello name="elide" />));
```

```bash
elide install --ecosystems=npm   # react, react-dom in package.json
elide app.tsx
```

```text
<p>hello <!-- -->elide</p>
```

| Input | Result |
| --- | --- |
| `/** @jsxImportSource preact */` at the top of a `.tsx` file | Imports `preact/jsx-runtime` |
| `jsxImportSource` in `tsconfig.json` | Ignored; React is used |
| `/** @jsx h */` | Ignored; React elements are created |
| JSX in a `.jsx` file | `SyntaxError: … Expected an operand but found <`; rename it to `.tsx` |

## Check types

Install TypeScript and run its compiler through Elide:

```json
{
  "scripts": { "typecheck": "tsc --noEmit" },
  "devDependencies": { "typescript": "^5.9.0", "@types/node": "^24.0.0" }
}
```

```json
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "types": ["node"]
  }
}
```

```bash
elide install --ecosystems=npm
elide run typecheck              # or: elide run tsc
```

```text
bad-types.ts(1,7): error TS2322: Type 'string' is not assignable to type 'number'.
```

`tsc` exits `2` on type errors. Pass compiler options after `--`: `elide run tsc -- --version`. `erasableSyntaxOnly`
makes `tsc` reject enums, namespaces and parameter properties; drop it if you use them.

## Elide types

`@elide-dev/types` declares Elide's own globals and modules and pulls in `@types/node`. Add it as a dev
dependency and name it in `types`:

```json
{
  "type": "module",
  "scripts": { "typecheck": "tsc --noEmit" },
  "devDependencies": { "typescript": "^5.9.0", "@elide-dev/types": "nightly" }
}
```

```json
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "types": ["@elide-dev/types"]
  }
}
```

```ts
// main.ts
import { Database } from "elide:postgres";
import { readFileSync } from "node:fs";

const bytes: number = readFileSync("package.json").length;
console.log(`Elide ${Elide.version}: ${bytes} bytes`);
export const open = (url: string) => Database.connect(url);
```

```bash
elide install --ecosystems=npm
elide run typecheck
elide main.ts
```

```text
Elide 1.6.0: 149 bytes
```

| API | Declared |
| --- | --- |
| `Elide.version`, `debug`, `release`, `buildMode` | Yes |
| `Elide.targetArchitecture` | Typed as `boolean`; the value is a string |
| `Elide.serve()` | No: `Property 'serve' does not exist` |
| `elide:postgres`, `elide:mysql` | Yes |
| `elide:sqlite`, `elide:cel`, `elide:telemetry` | No |
| `import … from "./script.py"` | Yes, as `any` |
| `node:*` modules | Yes, through `@types/node` |

The `nightly` tag tracks the newest declarations; `latest` is older.

## ES modules and CommonJS

| File | Module system |
| --- | --- |
| `.mjs`, `.mts` | ES module |
| `.cjs`, `.cts` | CommonJS |
| `.ts`, `.tsx` | ES module |
| `.js` | ES module when the nearest `package.json` has `"type": "module"`, else CommonJS |

A `.js` file with `import` statements and no `"type": "module"` fails with `SyntaxError: … Expected an operand but found
import`; add the field or rename the file to `.mjs`.

| Feature | Behavior |
| --- | --- |
| `import lib, { a } from "./lib.cjs"` | `module.exports` is the default export, its properties are named exports |
| `await import("./lib.cjs")` | Works |
| `require("./lib.mjs")` | `Error: require() of ES Module … not supported.` (`ERR_REQUIRE_ESM`); use `await import()` |
| `createRequire(import.meta.url)` | Works |
| `import.meta.url`, `.filename`, `.dirname` | Work |
| `import.meta.main`, `import.meta.resolve` | `undefined` |
| `__dirname` in CommonJS | Works |
| `__filename` in the entry CommonJS file | `"unknown"`; use `module.filename`. Required files get the real path. |
| `__dirname`, `require` in ES modules | Defined, unlike Node; do not rely on them |

## JSON

All of these load `data.json`:

```js
import data from "./data.json" with { type: "json" };
import same from "./data.json";
const viaRequire = require("./data.json"); // CommonJS
```

## Package `exports` and `imports`

| `package.json` field | `import` | `require()` |
| --- | --- | --- |
| `exports` subpaths (`"./feature": …`) | Works | Works |
| `exports` for the package root, with `main` | Works | Uses `main` |
| `exports` for the package root, no `main` | Works | `Error: Cannot find module 'pkg'` |
| `import` and `default` conditions | Work | — |
| A `require` condition listed before `default` | Selected instead of `default` | — |
| Unexported subpath | `Package subpath is not defined by "exports" field` (no `code`) | — |
| `imports` (`"#internal"`) | `TypeError: Packages imports do not define the specifier: '#internal'` | `Error: Cannot find module '#internal'` |

## Samples

- [TypeScript without a build](https://elide.help/docs/code-samples#typescript-without-a-build)

## See also

- [JavaScript and TypeScript](https://elide.help/docs/web)
- [Elide for Node users](https://elide.help/docs/elide-for-node)
- [NPM Installer](https://elide.help/docs/toolchain/web/npm)

---

# Development server

URL: https://elide.help/docs/dev-server

> Serve a directory with page reload using `elide dev` or `elide serve`, run a Fetch-style handler, and run a server across several Elide contexts.

`elide dev` and `elide serve` serve a directory of files or run a server script.

```bash
elide dev ./public
elide serve ./dist
```

| Command | Default address | Reload on file change |
| --- | --- | --- |
| `elide dev` | `127.0.0.1:3000` | HTML pages, when serving a directory |
| `elide serve` | `127.0.0.1:8080` | No |

A directory starts a file server; a script runs as a program and is not reloaded.

<img src="https://elide.help/assets/demos/dev-server.gif" alt="Starting the development server and observing a changed page" width="1591" height="691" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

| 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. |

## Serve a directory

| Request | Response |
| --- | --- |
| `/`, `/docs`, `/docs/` | The directory's `index.html` |
| A directory without `index.html` | `404`; there are no directory listings |
| `/about` when only `about.html` exists | `404`; link to `about.html` |
| A dot file such as `/.env` | `404`. `/.well-known/` is served. |
| A symbolic link that points outside the directory, or `..` in the path | `404` |
| `POST` and other methods | `405` from `elide serve`; `elide dev` answers as for `GET` |

- `Content-Type` comes from the file extension: `text/html; charset=utf-8`, `text/css`, `text/javascript`,
  `application/json`, `application/wasm`, `image/png` and so on.
- Files are sent whole, uncompressed, with no `ETag`, `Last-Modified` or `Cache-Control`; `Range` and conditional
  requests get a full `200`. Put a CDN or reverse proxy in front for caching and compression.
- `elide dev` adds a reload script to each HTML page and reloads it when any file in the directory changes.

## Run a fetch handler

```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.

## Serve with several contexts

```bash
elide serve --contexts=4 entrypoint.mjs
```

- Each context runs the entry module once and keeps its own globals, so 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).

## Samples

- [Multi-context server](https://elide.help/docs/code-samples#multi-context-server)

---

# Interactive REPL

URL: https://elide.help/docs/repl

> Start Elide's REPL with `elide repl` to evaluate JavaScript, TypeScript, Python and WebAssembly interactively and share values between languages.

The REPL evaluates code line by line and shares values between languages.

```bash
elide repl
```

`elide` with no arguments in a terminal also starts it. Languages: JavaScript, TypeScript, Python and WebAssembly.

<img src="https://elide.help/assets/demos/repl.gif" alt="One REPL session — JavaScript values used from Python" width="1107" height="691" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## 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`.

## Tern notebook sessions

With the Tern plugin installed and its embedded SDK configured, choose **Open REPL**
from the command palette. Use the language picker or **Ctrl+L** to switch languages.
**Enter** evaluates a cell; **Shift+Enter** inserts a newline.

Each session is one notebook. JavaScript and Python share live values automatically:
enter `const y = {"hi": 5}` in JavaScript, switch to Python, and enter `y.hi` to
get `5`. Changes to the shared object remain visible in both languages.

Declarations produce no result block. Objects appear as expandable JSON trees,
and language headings appear when the cell language changes. Switching preserves
each language's draft and history.

The picker shows languages supported by the configured SDK. CEL evaluates shared
data snapshots. Pkl evaluates modules and makes the result available as `_`.
Kotlin accepts module declarations. TypeScript and WebAssembly execution adapters
are not yet available in the embedded notebook.

### Serving in Tern

The Tern plugin also provides **Serve directory or script**. Enter a directory to
serve static files on an available loopback port, or a script to launch with the
configured runtime. Each server runs independently of notebook kernels.

The native dashboard shows the actual bound URL, readiness, uptime, observed
requests and bounded logs. Click a request for structured status and timing
details; use **Stop** or **Restart** to control the server. Closing the dashboard
stops its server. JavaScript servers using `Elide.serve` provide bind and request
events; server APIs without that instrumentation currently provide logs and
process controls only. A trace waterfall and OTLP inspection are not yet available.

---

# Languages and interop

URL: https://elide.help/docs/languages

> Which languages Elide runs, how to start each one, and how Python, JavaScript and WebAssembly call each other with `--interop` and in the REPL.

Elide runs these languages from one binary:

| 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).

<img src="https://elide.help/assets/demos/interop.gif" alt="elide --interop — Python calling JavaScript, JavaScript importing Python" width="1591" height="728" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## 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
```

The `default` export 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 JavaScript and TypeScript program. When Python is installed,
modules that use SIMD instructions fail 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).

## Samples

- [Python calling JavaScript](https://elide.help/docs/code-samples#python-calling-javascript)
- [JavaScript importing Python](https://elide.help/docs/code-samples#javascript-importing-python)
- [WebAssembly from JavaScript](https://elide.help/docs/code-samples#webassembly-from-javascript)

---

# Debugging

URL: https://elide.help/docs/debugging

> Debug Elide programs: read plain error output, attach a debugger, measure coverage, profile CPU time, trace with Insights scripts, and report a bug.

Find and report problems in programs run with Elide.

## Read errors

```bash
elide --error-format=plain run app.js
```

Plain errors go to stderr with a short stack; program output stays on stdout. `--verbose` or `--debug` adds Elide's
own logs.

<img src="https://elide.help/assets/demos/errors.gif" alt="Viewing an uncaught program error in Elide" width="1591" height="946" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

| Flag | Effect |
| --- | --- |
| `--abort-on-uncaught-exception` | Print the error, then raise `SIGABRT` (exit `134`) so the OS writes a core dump. |
| `--redirect-warnings=FILE` | Write process warnings, such as `process.emitWarning()`, to `FILE`, not stderr. |
| `--timeout=DURATION` | Stop the program after `DURATION` (for example `30s`) with exit `124`. |
| `--max-mem=SIZE` | Limit the heap size, for example `512m`. Exceeding it fails with a nonzero exit. |

<img src="https://elide.help/assets/demos/debug.gif" alt="elide --profiler and --debugger — profiler report and debug endpoints" width="1591" height="618" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## Attach a debugger

| Program | Flag | Listens on | Client |
| --- | --- | --- | --- |
| JavaScript, TypeScript, Python | `--debugger=cdp` | `ws://127.0.0.1:1337/…` | Chrome DevTools or any CDP client |
| JavaScript, TypeScript, Python | `--debugger=dap` | `127.0.0.1:4711`, waits for a client | Any DAP-capable editor |
| Java, Kotlin | `--debugger` | `127.0.0.1:5005` (JDWP), suspended | IntelliJ IDEA, VS Code, `jdb` |

```bash
elide run --debugger=cdp app.js
```

```text
Debugger listening on ws://127.0.0.1:1337/<id>/inspect
For help, see: https://docs.elide.dev/guides/debugging
E.g. in Chrome open: devtools://devtools/bundled/js_app.html?ws=127.0.0.1:1337/<id>/inspect
```

Open the `devtools://` link in Chrome.

```bash
elide run --debugger=dap app.js
elide run --debugger Hello.kt
```

```text
Listening for transport dt_socket at address: 5005
```

Change a listener's address with `--debugger-host` and `--debugger-port`:

```bash
elide run --debugger=dap --debugger-port=5678 app.js
elide run --debugger=0.0.0.0:5005 Hello.kt
```

A number or `host:port` after `--debugger` is a JDWP address and applies to Java and Kotlin only. JDWP has no
authentication: bind beyond loopback only on a trusted network, or use an SSH tunnel.

### Debug tests

```bash
elide test --debugger
elide test --debugger=dap sample.test.mts
elide test --debugger=5005
```

| Flag | Debugs |
| --- | --- |
| `--debugger` | JavaScript tests over CDP and JVM tests over JDWP on `5005` |
| `--debugger=cdp` or `dap` | JavaScript tests only |
| `--debugger=PORT` | JVM tests only |

A path narrows JavaScript tests to one file; narrow JVM tests by package name. While a debugger is attached,
JavaScript test files run one at a time.

## Measure coverage

```bash
elide run --coverage app.js
```

Elide prints a Coverage Report after the program exits, with statements, lines and functions covered per file.
JavaScript and TypeScript coverage is also written as LCOV to `.dev/reports/coverage/js/run/lcov.info` in the project,
or in the working directory outside one.

## Profile CPU time

```bash
elide run --profiler=cputracing app.js
```

```text
╭Profiler Report───────────────────────────────────────────────────────────────╮
│ Location           Root               Total        Interpreted      Compiled │
│   app.js            fib       21.89k 100.0%      21.89k 100.0%        0 0.0% │
│   app.js       :program              1 0.0%           1 100.0%        0 0.0% │
╰──────────────────────────────────────────────────────────────────────────────╯
```

`Total` counts calls to each function. For JFR recordings, heap dumps and Linux `perf`, see
[Monitoring and Profiling](https://elide.help/docs/instruments).

## Trace with Insights

```javascript
// insight.js
insight.on("enter", (ctx) => {
  console.log("enter", ctx.name);
}, { roots: true });
```

```bash
elide run --insights=insight.js app.js
```

Each function entry prints a line such as `enter fib`. See the [Insights API](https://elide.help/docs/api-insight) for events and filters.

## Report a bug

```bash
elide info
elide agent diagnostics
elide agent bug
```

`elide agent bug` prints the issue tracker URL and a Markdown report template. Fill in the exact command, the expected
behavior, and any crash report.

---

# Troubleshooting

URL: https://elide.help/docs/troubleshooting

> Common Elide errors with their exact messages and fixes: missing modules, Python, JVM tools, sandbox denials, timeouts, memory and ports.

Each section quotes an error as Elide prints it, then the fix.

## No such built-in module

```text
Error: No such built-in module: node:http2
```

`node:http2`, `node:cluster`, `node:inspector` and `node:wasi` are not available; `require` gives the code
`ERR_UNKNOWN_BUILTIN_MODULE`. Without the `node:` prefix the message is `Cannot find module 'http2'`. A package that
imports one at load time, such as Fastify, fails the same way. Check a module's status in the
[API Overview](https://elide.help/docs/api-overview).

## Module not found after `elide install`

```text
TypeError: Module not found: 'hono'
```

Plain `elide install` installs Maven dependencies only. With only a `package.json`, it prints nothing and exits `0`.
Install npm packages with:

```bash
elide install --ecosystems=npm
```

## Python is not installed

```text
Python support is not installed. Run 'elide setup python' to add it.
```

Exit code `2`. Run `elide setup python`; `elide info` lists the installed languages on its `Languages:` line. A JavaScript
file that imports a `.py` module before Python is installed exits `1` with
`Cannot import 'mod.py': Python support is not installed.` and the same hint. With Python installed, calls between
languages also need `--interop`; see [Languages and Interop](https://elide.help/docs/languages#without---interop).

## `elide javac` without `--`

```text
error: '[-- TOOL_ARGS]…' can only be given after '--'

Usage: elide javac [FLAGS] [-- TOOL_ARGS]…
```

Arguments for `javac`, `java`, `kotlinc` and the other JDK tools go after `--`:

```bash
elide javac -- -d out Hello.java
elide java -- -cp out Hello
```

## Kotlin classes fail under `elide java`

```bash
elide kotlinc -- -d kout Main.kt
elide java -- -cp kout MainKt
```

```text
Exception in thread "main" java.lang.NoClassDefFoundError: kotlin/collections/CollectionsKt
	at MainKt.main(Main.kt:2)
	at MainKt.main(Main.kt)
Caused by: java.lang.ClassNotFoundException: kotlin.collections.CollectionsKt
```

`elide java` does not add the Kotlin standard library. Run the file with `elide run Main.kt`, or package the app as a
[`Jvm.JvmApplication`](https://elide.help/docs/toolchain/jvm/jar#runnable-application-distributions). `kotlinc -include-runtime` fails.

## Sandbox denials

| Message | Grant |
| --- | --- |
| `EACCES: permission denied, open 'hello.txt'` | `--allow-read=PATHS` or `--allow-write=PATHS` |
| `Error: Filesystem read denied by policy: /app/node_modules/hono` | Add the npm store to `--allow-read`; packages link into `~/.cache/aube` |
| `fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com` | The flag in the message |
| `spawn of 'echo' is not permitted; grant it with --allow-run=echo` | The flag in the message |
| `fetch to 'example.com:443' denied by --deny-net` | Remove the host from `--deny-net` |
| `spawn of 'echo' denied by --deny-run` | Remove the command from `--deny-run` |

See [Sandbox and Limits](https://elide.help/docs/sandbox).

## `--deny-net` without `=`

```text
error: equal sign is needed when assigning values to '--deny-net=<HOSTS>'
```

Exit code `2`. Write `--deny-net=example.com`; the same holds for `--deny-run`. The `--allow-*` flags take an optional
value, so `--allow-net example.com run app.js` grants every host and tries to run a file named `example.com`:

```text
No file or script named 'example.com'
```

## Exit code 124

```text
Error: --timeout 2s exceeded
```

`--timeout=DURATION` stopped the run. Raise it or remove it.

## Exit code 3 and out of memory

`--heap-dump-on-oom=FILE` writes a heap dump when the heap is full, then exits `3`:

```text
Dumping heap to …/oom.hprof ...
Heap dump file created [308989015 bytes in 0.988 secs]
```

Without it, a full heap exits `1` with
`Could not allocate an unaligned heap chunk because the heap address space is exhausted.` Raise `--max-mem`. A value of
`128m` or less fails before the program starts:

```text
Failed to create isolate: INSUFFICIENT_ADDRESS_SPACE (802)
```

## Port already in use

`node:http` reports a taken port:

```text
Error: listen EADDRINUSE 127.0.0.1:3000
```

Fetch-handler servers (`export default { fetch }`, `Elide.serve`) report nothing: a second server on the same port
starts, and requests alternate between the two processes. Stop the old one first:

```bash
ss -ltnp | grep :3000
```

## A request returns 500 with no error printed

```text
HTTP/1.1 500 Internal Server Error
```

A fetch handler that throws answers `500 Internal Server Error` without printing the error. Wrap the handler in
`try`/`catch` and log it. See [Build an HTTP Service](https://elide.help/docs/http-service#errors).

## Express `express.json()` stops the server

```text
TypeError: Buffer.isBuffer is not a function
```

`express.json()` and `express.text()` stop the process on the first request with a body. Read the body yourself or use
`express.raw()`; see [Frameworks](https://elide.help/docs/http-service#frameworks).

---

# Monitoring and profiling

URL: https://elide.help/docs/instruments

> Record JFR files, dump the heap, watch a running Elide process with jcmd, jps and jstat, and profile with Linux perf using the instrument flags.

The instrument flags record what an Elide process does while it runs.

| Question | Capture | Inspect with |
| --- | --- | --- |
| What happened during the run? | `--jfr=run.jfr` | JDK `jfr` |
| What is in the heap? | `--heap-dump=heap.hprof` | VisualVM |
| How does the heap behave over time? | `--vmstat` | `jps`, `jstat` |
| What is a running process doing? | `jcmd PID` | JFR, heap dumps, thread stacks |
| Where does compiled code spend CPU time? | `--jitdump=DIR` | Linux `perf` |

List the flags with `elide help instruments`. They apply to `run` and to scripts, snippets and modules. Put them before
any `--` or `-m MODULE`. A JDK 25 install provides `jfr`, `jcmd`, `jps` and `jstat`;
[VisualVM](https://visualvm.github.io/download.html) reads heap dumps. For coverage, CPU tracing and debuggers, see
[Debugging](https://elide.help/docs/debugging). To export traces, metrics, and logs to an observability backend, see
[OpenTelemetry](https://elide.help/docs/opentelemetry).

## Record with JFR

```bash
elide --jfr=run.jfr run app.js
jfr summary run.jfr
jfr print --events 'dev.elide.*' run.jfr
```

`--jfr` uses the `profile` settings and saves on normal exit. `--jfr-settings=default` or a `.jfc` path picks other
settings. File names and settings cannot contain commas or double quotes.

| Event | Records |
| --- | --- |
| `dev.elide.Boot` | Startup finished; `elapsedNanos` is the startup time. |
| `dev.elide.GuestStart` / `dev.elide.GuestStop` | Entry program run, with language, duration, outcome, exit code. |
| `dev.elide.HttpRequest` / `dev.elide.HttpResponse` | One served request, with method, protocol, status, duration. |
| `dev.elide.HttpClientExchange` | One outgoing request, with queue and connect time, protocol, status and body bytes. |
| `dev.elide.TransportTlsHandshake` | One TLS handshake, with duration, role, outcome and ALPN. |
| `dev.elide.Execution` | The command finished, with its exit code. |

URLs, headers and payloads are not recorded.

## Dump the heap

```bash
elide --heap-dump=heap.hprof run app.js
elide --heap-dump-on-oom=oom.hprof run app.js
visualvm --openfile heap.hprof
```

`--heap-dump` writes on normal exit. `--heap-dump-on-oom` writes on an out-of-memory error, then exits without running
shutdown hooks.

## Watch a running process

```bash
elide --vmstat run app.js &
jps -l
jstat -gc PID 1s
```

`--vmstat` lists the process in `jps` (by PID, with no name) and lets `jstat` sample it. `jcmd` attaches by PID with or
without `--vmstat`, on Linux and macOS, as the same OS user:

```bash
jcmd PID help
jcmd PID JFR.start name=profile settings=profile
jcmd PID JFR.dump name=profile filename=live.jfr
jcmd PID GC.heap_dump live.hprof
jcmd PID Thread.print
```

A killed process does not write its captures. Dump a live recording with `jcmd` before you stop it.

## Profile with perf on Linux

```bash
perf record -k 1 --call-graph fp -o perf.data -- elide --jitdump=./jitdump run app.js
perf inject -j -i perf.data -o perf.jit.data
perf report -i perf.jit.data
```

`--jitdump` works in Linux release builds. Keep the `jitdump` directory until `perf inject` finishes. Frequently run
functions appear under `jitted-` objects. A zero exit does not prove a valid capture; check that the report shows your
functions. On WSL2, `perf` must match the running kernel.

## VM options

Each flag has a VM option spelling:

```text
--jfr=run.jfr                 -XX:StartFlightRecording=filename=run.jfr,settings=profile,dumponexit=true
--heap-dump-on-oom=oom.hprof  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=oom.hprof -XX:+ExitOnOutOfMemoryError
--vmstat                      -XX:+UsePerfData
--jitdump=DIR                 -XX:+RuntimeJitdump -XX:RuntimeJitdumpDir=DIR
```

`-XX:+DumpHeapAndExit -XX:HeapDumpPath=initial.hprof` dumps the initial heap, then exits. `-Xmx` and
`-XX:MaxHeapSize` are the same setting as `--max-mem`; passing both is an error.

---

# Deploy an app

URL: https://elide.help/docs/deploy

> Package a JavaScript or TypeScript server in a container image on elide.dev/elide, with environment, sandbox flags, logs and a health check.

This page packages a TypeScript server as a container image on `elide.dev/elide`.

## Write the app

```ts
// server.ts
import { Hono } from "hono";

const app = new Hono();

app.use(async (c, next) => {
  await next();
  console.log(JSON.stringify({ method: c.req.method, path: c.req.path, status: c.res.status }));
});

app.get("/healthz", (c) => c.text("ok"));
app.get("/", (c) => c.json({ greeting: process.env.GREETING ?? "hello" }));

export default app;
```

```js
// healthcheck.mjs
const res = await fetch("http://127.0.0.1:8080/healthz");
process.exit(res.ok ? 0 : 1);
```

```json
{
  "name": "deploy-app",
  "type": "module",
  "dependencies": {
    "hono": "^4.7.0"
  }
}
```

Run `elide install --ecosystems=npm` once to write `aube-lock.yaml`.

## Write the Dockerfile

```dockerfile
FROM elide.dev/elide:1.6.0
WORKDIR /app
COPY package.json aube-lock.yaml ./
RUN elide install --ecosystems=npm
COPY . .
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s CMD ["elide", "healthcheck.mjs"]
CMD ["--allow-read=/app,/root/.cache/aube", "--allow-net=api.example.com", "serve", "--no-tui", "--host", "0.0.0.0", "--port", "8080", "server.ts"]
```

```text
# .dockerignore
node_modules
.env
```

| Line | Why |
| --- | --- |
| `FROM elide.dev/elide:1.6.0` | The image's entrypoint is `elide`, so `CMD` holds only its arguments. Tags: [Container Images](https://elide.help/docs/installation/containers). |
| `RUN elide install --ecosystems=npm` | Installs inside the image. `node_modules` links into `/root/.cache/aube`, so a host `node_modules` would not work. |
| `--host 0.0.0.0` | A default-exported handler binds `127.0.0.1`, which is unreachable from outside the container. |
| `--no-tui` | Without it, `docker run -t` starts the terminal UI and the app's output never reaches `docker logs`. |
| `HEALTHCHECK` | The image has no `curl` or `wget`; a short Elide script does the check. |

```bash
docker build -t my-app .
docker run -d --name my-app -p 8080:8080 -e GREETING=hi my-app
curl http://127.0.0.1:8080/
```

```text
{"greeting":"hi"}
```

`docker inspect --format '{{.State.Health.Status}}' my-app` prints `healthy` once the first check passes. `docker stop`
ends the server within a second, with exit code `143`.

## Pass environment variables

`process.env` holds the container's variables; pass them with `docker run -e NAME=value` or Docker's
`--env-file .env`. This supplies configuration without copying the file into the image.

For local runs with Elide 1.6.2 or later, the launcher reads `.env` and `.env.local` automatically. Use `--env-file`
to select other files or `--no-env` to disable loading. Elide does not set `NODE_ENV`. See
[Environment and properties](https://elide.help/docs/environment) for precedence and [Environment variables](https://elide.help/docs/env-variables) for JavaScript access.

## Restrict the server

Programs run unrestricted until a sandbox flag is given. Grant a server what it needs and nothing else:

| Flag | In the Dockerfile above |
| --- | --- |
| `--allow-read=PATHS` | `/app` and the npm store `/root/.cache/aube`. |
| `--allow-net=HOSTS` | Outbound hosts. Listening on a port needs no grant. |
| `--allow-run=CMDS` | Not given: subprocesses stay allowed. Give a list to restrict them. |
| `--deny-net=HOSTS` | Hosts to block even when allowed, e.g. `--deny-net=169.254.169.254`. |
| `--max-mem=SIZE`, `--timeout=DURATION` | Heap size and total run time. |

Global flags go before the command (`serve`, `run`). `--deny-net` and `--deny-run` need the `=` form. Leaving the npm
store out of `--allow-read` stops the server at startup:

```text
Error: Filesystem read denied by policy: /app/node_modules/hono
```

A blocked outbound call names the flag:

```text
fetch to '169.254.169.254:80' denied by --deny-net
```

Every flag: [Sandbox and Limits](https://elide.help/docs/sandbox).

## Read logs

`console.log` writes to stdout and `console.error` to stderr; `docker logs` shows both:

```text
{"method":"GET","path":"/healthz","status":200}
{"method":"GET","path":"/","status":200}
```

`elide serve --no-tui` prints no access log, and a handler that throws answers `500` without printing the error. Log
requests and errors in the app, or export request spans, metrics, and errors with [OpenTelemetry](https://elide.help/docs/opentelemetry).

## Deploy a JVM app

- Build a JVM image from `elide.pkl` with a `ContainerImage` artifact: [JVM Containers](https://elide.help/docs/toolchain/jvm/containers).
- Compile a native executable: [Native Image](https://elide.help/docs/toolchain/jvm/native-image).

---

# Sandbox and limits

URL: https://elide.help/docs/sandbox

> Restrict an Elide program's filesystem, network, subprocess, thread and native access with `--sandbox` and `--allow-*` flags, and limit resources and run time.

Programs run unrestricted until you pass a sandbox flag. `--sandbox` denies filesystem access; network and
subprocesses stay allowed until you list hosts or commands:

```bash
elide --sandbox --allow-read=. --allow-net=example.com run app.js
```

<img src="https://elide.help/assets/demos/sandbox.gif" alt="elide --sandbox — filesystem, network and subprocess policy" width="1591" height="546" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## Allow file access

```bash
elide --allow-read=. --fs-audit run app.js
```

```text
[elide.fs] allow read open hello.txt
[elide.fs] DENY  write open out.txt
```

A denied access fails like a protected file: `EACCES: permission denied, open 'hello.txt'`. Relative paths resolve
from the working directory.

WASI programs cannot access host directories until you map one with `WasiMapDirs`; see
[WebAssembly](https://elide.help/docs/wasm#directory-access). These grants apply to mapped directories, and a WASI open needs both read
and write access.

## Allow network and subprocesses

```bash
elide --allow-net=localhost --allow-run=ls run app.js
```

A denied call names the grant it needs:

```text
TypeError: fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com
Error: spawn of 'echo' is not permitted; grant it with --allow-run=echo
```

A `--deny-*` match reports `denied by --deny-net` or `denied by --deny-run`. Policy checks the command that runs, so a
shell invocation is checked as `sh`. Spawn with `execFileSync` from `node:child_process`.

## Threads and native access

| Program | Threads by default | Native access by default |
| --- | --- | --- |
| JavaScript, TypeScript | Not applicable: `node:worker_threads` workers run under every flag | Allowed |
| Python entry | Allowed | Allowed |
| Python entry with `--sandbox` or an `--allow-read`/`--allow-write` grant | Denied; add `--allow-threads` | Allowed |
| Python under `--interop` | Denied, even with `--allow-threads` | Allowed |

```python
# threads.py
import threading
out = []
t = threading.Thread(target=lambda: out.append("worker ran"))
t.start(); t.join()
print(out[0])
```

```bash
elide python threads.py                                         # worker ran
elide --sandbox --allow-read=. python threads.py                # Creating threads is not allowed.
elide --sandbox --allow-read=. --allow-threads python threads.py  # worker ran
```

`--no-native` denies native access. Python then lacks some features, such as `AF_UNIX` sockets
(`AttributeError: module 'socket' has no attribute 'AF_UNIX'`) and arbitrary signals, and starts more slowly.
`--allow-native` states the default explicitly; combining it with `--no-native` is a usage error (exit `2`).

## Set limits

`--limit` applies to JavaScript and TypeScript programs. A value is a number, `0` to forbid, or `unlimited`, the
default. Other names, languages or commands are usage errors.

```bash
elide --limit=workers=4 --limit=fds=128 --max-mem=512m --timeout=30s run app.js
```

Workers inherit their parent's grants. These flags do not isolate the process from a native crash.

## Pick a profile

`--sandbox=trusted` is the default profile. `--sandbox=sandboxed` and `--sandbox=isolated` are unavailable and exit
with code `2`.

## Flags

| Flag | Effect |
| --- | --- |
| `--sandbox` | Deny filesystem access. Network and subprocesses stay allowed. |
| `--allow-read[=PATHS]` | Allow reads everywhere, or at the listed paths. Implies `--sandbox`. |
| `--allow-write[=PATHS]` | Allow writes everywhere, or at the listed paths. Implies `--sandbox`. |
| `--fs-audit` | Log each filesystem decision to stderr. |
| `--allow-net[=HOSTS]` | Allow all network access, or only the listed hosts (`HOST` or `HOST:PORT`). |
| `--allow-run[=CMDS]` | Allow all subprocesses, or only the listed commands. |
| `--deny-net=HOSTS` | Deny hosts even when allowed. |
| `--deny-run=CMDS` | Deny commands even when allowed. |
| `--allow-env[=NAMES]` | Let `elide.pkl` read more environment variables, or all of them. `process.env` is unchanged. |
| `--allow-threads` | Allow Python threads in a sandbox. |
| `--allow-native` | Allow native access (the default). |
| `--no-native` | Deny native access. |
| `--limit=workers=N` | Limit live workers; exceeding it throws `ERR_WORKER_LIMIT`. |
| `--limit=fds=N` | Limit open `node:fs` handles; exceeding it throws `EMFILE`. |
| `--max-mem=SIZE` | Limit the heap size; exceeding it is an out-of-memory error with a nonzero exit. |
| `--timeout=DURATION` | Stop the program after `DURATION` with exit `124`. |

Lists are comma-separated. `--deny-net` and `--deny-run` need the `=` form.

## Samples

- [Sandboxed subprocess](https://elide.help/docs/code-samples#sandboxed-subprocess)
- [Limit workers](https://elide.help/docs/code-samples#limit-workers)
- [Request limits](https://elide.help/docs/code-samples#request-limits)

---

# Upgrading

URL: https://elide.help/docs/upgrading

> Update Elide, pin a project or CI job to one version with elide use and .elideversion, and the renames and removals to handle when moving from 1.5 to 1.6.

This page covers updating Elide, pinning the version a project uses, and what to change when you move to 1.6.

## Update the installed binary

```bash
elide upgrade --check
elide upgrade
elide upgrade --channel release
```

| Install method | Update with |
| --- | --- |
| Install script | `elide upgrade`; it keeps an installed Python component |
| Homebrew, apt, RPM, MSI | The package manager; see [Packages & Installers](https://elide.help/docs/installation/packages) |
| GitHub Actions | The `version` input of `setup-elide`; see [Elide in CI](https://elide.help/docs/installation/ci-cd) |

`--channel` is `release` or `nightly`; the default is the channel the running build came from. `--force` reinstalls
the current version.

## Pin a project

```bash
elide use 1.5.4
```

```text
Elide 1.5.4 is already installed at /home/you/.local/share/elide/versions/1.5.4/bin/elide
```

`elide use` writes the version to `.elideversion` and installs it under `ELIDE_HOME` (default
`~/.local/share/elide`). Every `elide` command in that directory then runs the pinned version, downloading it on first
use if needed:

```bash
elide info
```

```text
Elide - putting the java back in javascript
Version: 1.5.4+20260921.44ff130047
Mode: release
```

| Command | Effect |
| --- | --- |
| `elide use 1.5.4` | Pin a release and install it. |
| `elide use --channel nightly 20260921` | Pin the nightly build of that date. |
| `elide use 1.5.4+20260921` | Pin a nightly by its full tag. |
| `elide use --no-install 1.6.0` | Write `.elideversion` only. |
| `elide --use-version 1.5.4 run app.js` | Run an installed version once, without a pin. |
| `elide --ignore-version run app.js` | Run the binary on `PATH`, ignoring `.elideversion`. |

`elide --version` always prints the binary on `PATH`; `elide info` prints the version that runs. Nightly tags have the
form `<version>+<YYYYMMDD>`, for example `1.5.4+20260921`; the list is on
[GitHub Releases](https://github.com/elide-dev/elide/releases).

To refuse versions outside a range instead of switching to one, set `toolchain.engines` in `elide.pkl`:

```pkl
toolchain { engines { ["elide"] = ">=1.6.0" } }
```

`elide build` on an older binary then stops with
`Current version of Elide ('1.5.4') does not satisfy project requirements ('>=1.6.0').` See
[Toolchain](https://elide.help/docs/elide-pkl-reference#toolchain).

## Pin CI

Pin the version in the setup step, and commit `.elideversion` so local runs match:

```yaml
- uses: elide-dev/setup-elide@v4.2.0
  with:
    version: 1.6.0
    channel: release
```

Any installed Elide downloads and runs the version in a committed `.elideversion`, so the workflow pin and the file
must agree. For a nightly, pin the full dated tag.

## Migrate from 1.5 to 1.6

Each row is a rename or removal from the [1.6.0 changelog](https://elide.help/docs/changelog), with the error 1.6 prints for old usage:

| 1.5 | 1.6 | Old usage in 1.6 |
| --- | --- | --- |
| `elide manifest` | `elide project export` | ``elide manifest: removed; use `elide project export` instead`` (exit `2`) |
| `testing { coverage { … } }` in `elide.pkl` | Top-level `coverage { … }` block | ``Cannot find property `coverage` in object of type `elide.testing#Testing`.`` |
| `preview` release channel | `release` or `nightly` | `invalid value 'preview' for '--channel'` (exit `2`) |
| Python in every install | `elide setup python`, or `--with-python` on the install script | `Python support is not installed. Run 'elide setup python' to add it.` |
| JavaScript and Python share a context | `--interop` on programs that call between languages | ``Cannot import 'mod.py': JavaScript entries run without Python. Re-run with --interop to use it.`` |
| `http://` Maven repositories | `https://` URLs; plain HTTP is accepted only on loopback | ``Maven repository 'plain' uses plain HTTP: http://example.com/maven`` |

Other 1.6 changes that can change results without an error:

- Java compiles with `--release`, targeting `jvm.target` or Java 21.
- A `JavadocJar` whose sources include Kotlin is generated by Dokka, which documents the Kotlin too; set
  `generator = "javadoc"` on it to keep the `javadoc` output of earlier releases. See [JAR Assembly](https://elide.help/docs/toolchain/jvm/jar).
- `elide run` and `elide test` exit with the program's own exit code.
- `elide test` stops discovery at a nested project; name its path to run it.
- Source sets follow `src/<set>/<language>`, then `src/<set>`, then flat `src` or `test`; see
  [Source Sets](https://elide.help/docs/toolchain/source-sets).

Patch releases within 1.6 only add `elide.pkl` properties. To keep a manifest on the 1.6.0 schema while running a newer
Elide, amend the published schema; see [elide.pkl Reference](https://elide.help/docs/elide-pkl-reference).

---

# OpenTelemetry

URL: https://elide.help/docs/opentelemetry

> Export OpenTelemetry traces, metrics, logs, errors, and profiles from Elide and your code over OTLP, with no SDK in the application: quick start, configuration, providers, and language APIs.

Elide is an OpenTelemetry SDK. JavaScript, TypeScript, and Python code uses the standard OpenTelemetry API for its
language, and Elide supplies the implementation and the OTLP exporter. Elide's own spans and metrics for served
requests, `fetch`, errors, the process, and builds and tests join the same traces.

> [!TIP] No SDK, exporter, or agent
> Import the standard API and configure a destination; there is nothing else to install.

> [!NOTE] Off until configured
> With no destination configured, Elide starts no telemetry threads and opens no connections.

## Quick start

Start an OpenTelemetry Collector that prints what it receives:

```bash
docker run --rm -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:0.115.1
```

Write a script that creates a span:

```ts
// app.ts
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("checkout");
await tracer.startActiveSpan("charge", async (span) => {
  span.setAttribute("order.id", 42);
  console.log("charged order 42");
  span.end();
});
```

Run it with the collector as its endpoint:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=checkout elide run app.ts
```

The collector prints the span, and the `console.log` line as a log record carrying the span's ids (excerpt):

```text
Resource attributes:
     -> telemetry.sdk.name: Str(elide)
     -> service.name: Str(checkout)
InstrumentationScope checkout
Span #0
    Trace ID       : 5162303c77b9dab62b1d536ce955c103
    ID             : 410c19dcae7eda3c
    Name           : charge
    Kind           : Internal
Attributes:
     -> order.id: Int(42)

InstrumentationScope console
LogRecord #0
SeverityText: INFO
Body: Str(charged order 42)
Trace ID: 5162303c77b9dab62b1d536ce955c103
Span ID: 410c19dcae7eda3c
```

Elide exports pending data before it exits, so short scripts need no flush call.

`@opentelemetry/api` needs no install: Elide provides it when the project has no copy.

## Configure a project

In a project, put the settings in `elide.pkl`. Credentials stay in environment variables, named by the manifest:

```pkl
amends "elide:project.pkl"

name = "checkout"

opentelemetry {
  service { name = "checkout"; version = "1.4.2"; environment = "production" }
  destinations {
    ["collector"] { endpoint = "http://localhost:4318" }
    ["honeycomb"] { provider = "honeycomb" }
  }
}
```

Variables override the block and `--otel-*` flags override both; see [Configuration](https://elide.help/docs/opentelemetry/configuration).

## Turn it off

```bash
elide run --no-otel app.ts          # one run
OTEL_SDK_DISABLED=true elide serve  # one process
```

## Languages

| Language | API | Elide records |
| --- | --- | --- |
| JavaScript and TypeScript | `@opentelemetry/api`, `@opentelemetry/api-logs`, [`elide:telemetry`](https://elide.help/docs/opentelemetry/javascript#elidetelemetry) | Server spans, `fetch` client spans, `console.*` logs, errors |
| Python | `opentelemetry`, `logging`, [`elide.telemetry`](https://elide.help/docs/opentelemetry/python#elidetelemetry) | `logging` records, errors |
| Java and Kotlin | None | Nothing |

Java and Kotlin programs that Elide runs get no OpenTelemetry API, agent, or trace context from Elide. Use the
OpenTelemetry Java SDK or agent in the program as you would on any JVM. `elide build` and `elide test` still record
their own spans for JVM projects; see [Builds and tests in CI](https://elide.help/docs/opentelemetry/runtime#builds-and-tests-in-ci).

## In this section

| Page | Covers |
| --- | --- |
| [Configuration](https://elide.help/docs/opentelemetry/configuration) | `elide.pkl`, environment variables, flags, precedence |
| [Providers](https://elide.help/docs/opentelemetry/providers) | OTLP, Sentry, Datadog, PostHog, Honeycomb, Grafana Cloud |
| [Signals](https://elide.help/docs/opentelemetry/signals) | Traces, metrics, logs, errors, profiles |
| [Runtime instrumentation](https://elide.help/docs/opentelemetry/runtime) | Serving, `fetch`, process metrics, CI spans |
| [Correlation and baggage](https://elide.help/docs/opentelemetry/correlation) | Linked signals, `traceparent`, W3C baggage |
| [JavaScript and TypeScript](https://elide.help/docs/opentelemetry/javascript) | API, SDK takeover, `elide:telemetry` |
| [Python](https://elide.help/docs/opentelemetry/python) | API, `logging`, `elide.telemetry` |
| [Emitted telemetry](https://elide.help/docs/opentelemetry/reference) | Every span, metric, and attribute Elide emits |
| [Troubleshooting](https://elide.help/docs/opentelemetry/troubleshooting) | Nothing arrives, rejected data, status counters |

## Samples

- [Custom span in TypeScript](https://elide.help/docs/code-samples#custom-span-in-typescript)
- [Metrics instruments](https://elide.help/docs/code-samples#metrics-instruments)
- [Python span and logging](https://elide.help/docs/code-samples#python-span-and-logging)
- [OTLP to a local collector](https://elide.help/docs/code-samples#otlp-to-a-local-collector)
- [Baggage across services](https://elide.help/docs/code-samples#baggage-across-services)

---

# OpenTelemetry configuration

URL: https://elide.help/docs/opentelemetry/configuration

> Configure Elide's OpenTelemetry export with the elide.pkl opentelemetry block, OTEL_* and ELIDE_OTEL_* environment variables, and --otel-* flags, and how they combine.

Telemetry is configured from three places. Higher rows win:

| Source | Scope | Example |
| --- | --- | --- |
| `--otel-*` flags | One run | `elide run --otel-endpoint=http://localhost:4318 app.ts` |
| `OTEL_*` and `ELIDE_OTEL_*` variables | One process and its environment | `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` |
| `opentelemetry` block in `elide.pkl` | A project | `destinations { ["collector"] { … } }` |
| Defaults | | Off until a destination exists |

Telemetry stays off until a destination exists in one of them. With no destination, Elide starts no telemetry
threads, opens no connections, and the OpenTelemetry APIs in your code do nothing.

## When each source is read

| Command | `elide.pkl` block | Variables and flags |
| --- | --- | --- |
| `elide run` (project entrypoint), `elide serve` | yes | yes |
| `elide run file.ts`, `elide file.py` inside a project | yes, when the project's `elide.pkl` contains `opentelemetry` | yes |
| `elide run file.ts` outside a project | no | yes |
| `elide build`, `elide test`, `elide install` | yes | yes |

A one-shot run looks for the word `opentelemetry` in the project's `elide.pkl` before evaluating it, so a block
inherited from another module is not seen by `elide run file.ts`; projects without telemetry pay nothing.

## The `elide.pkl` block

```pkl
amends "elide:project.pkl"

name = "checkout"

opentelemetry {
  service { name = "checkout"; version = "1.4.2"; environment = "production" }
  resource { ["cloud.region"] = "us-east-1" }

  destinations {
    ["collector"] { endpoint = "http://localhost:4317"; protocol = "grpc" }
    ["sentry"] { provider = "sentry" }
  }

  traces { sampler = "parentbased_traceidratio"; ratio = 0.25 }
  metrics { interval = 30.s }
  logs { level = "info" }
  runtime { logs = "warn" }
}
```

Credentials never go in `elide.pkl`. A destination names the environment variable that holds them (`credential`,
`dsn`, `headerEnv`), and Elide reads it at startup.

### Top level

| Property | Meaning | Default |
| --- | --- | --- |
| `enabled` | `false` turns telemetry off, whatever the environment says. | — |
| `service.name` | `service.name` resource attribute. | `unknown_service:elide` |
| `service.version`, `.namespace` | `service.version`, `service.namespace`. | — |
| `service.environment` | `deployment.environment.name`. | — |
| `resource` | Extra resource attributes: strings, booleans, integers, floats. | — |
| `destinations` | Named places to send telemetry; see below. | none |
| `shutdownTimeout` | Longest the final export may take at exit; see [At exit](#at-exit). | `5.s` |

### Signals

| Property | Meaning | Default |
| --- | --- | --- |
| `traces.enabled` | Record spans your code creates. | `true` |
| `traces.sampler` | `always_on`, `always_off`, `traceidratio`, `parentbased_always_on`, `parentbased_always_off`, `parentbased_traceidratio`. | `parentbased_always_on` |
| `traces.ratio` | Ratio for the ratio samplers, 0 to 1. | `1.0` |
| `traces.propagators` | `tracecontext`, `baggage`, `none`: what the OpenTelemetry API in your code injects and extracts. | `tracecontext`, `baggage` |
| `metrics.enabled` | Record instruments your code creates. | `true` |
| `metrics.interval` | Export interval. | `60.s` |
| `metrics.temporality` | `cumulative` or `delta`. | `cumulative`; `delta` when Datadog receives metrics |
| `logs.enabled` | Export log records your code emits. | `true` |
| `logs.level` | Minimum severity: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `off`. | `info` |
| `logs.console` | Export `console.*` and Python `logging` output as log records. | `true` |
| `profiles.enabled` | Sample guest CPU profiles (experimental). | `false` |
| `profiles.frequency` | Samples per second, 1 to 10000. | `100` |
| `runtime.traces` | Elide's automatic HTTP and build/test/install spans; see [Enable build reports](https://elide.help/docs/opentelemetry/runtime#enable-build-reports). | `true` |
| `runtime.metrics` | Elide's HTTP, process, and error metrics. | `true` |
| `runtime.logs` | Minimum severity of Elide's own log records to export. | `warn` |
| `propagation.baggage` | W3C baggage on Elide's HTTP server and clients; see [Baggage](https://elide.help/docs/opentelemetry/correlation#baggage). | off |

### Destinations

Each entry in `destinations` is one place telemetry goes. The name is yours; it appears in error messages.

| Property | Meaning | Default |
| --- | --- | --- |
| `provider` | `otlp`, `sentry`, `datadog`, `posthog`, `honeycomb`, `grafana`. See [Providers](https://elide.help/docs/opentelemetry/providers). | `otlp` |
| `endpoint` | Base URL. HTTP protocols append `/v1/traces`, `/v1/metrics`, `/v1/logs`. For a provider, replaces its host. | `http://localhost:4318`, or `http://localhost:4317` for gRPC |
| `protocol` | `grpc`, `http/protobuf`, `http/json`. | `http/protobuf` |
| `headers` | Literal, non-secret request headers. | — |
| `headerEnv` | Headers read from environment variables: `["authorization"] = "COLLECTOR_TOKEN"`. | — |
| `credential` | Variable holding a provider's API key or token. | per provider |
| `dsn` | Variable holding a Sentry DSN. | `SENTRY_DSN` |
| `site` | Datadog site. | `DD_SITE`, then `datadoghq.com` |
| `region` | PostHog or Honeycomb region (`us`, `eu`), or a Grafana Cloud zone. | `us` |
| `signals` | `traces`, `metrics`, `logs`, `profiles`. | every signal the provider takes by default |
| `compression` | `gzip` or `none`. | `gzip` |
| `timeout` | Per-request deadline, retries included. | `10.s` |
| `perSignal` | Per-signal `endpoint` (used as given), `protocol`, `headers`, `headerEnv`, `compression`, `timeout`. | — |

Several destinations can be active at once. Each receives only the signals it lists, or that its provider takes by
default:

```pkl
opentelemetry {
  destinations {
    ["collector"] { endpoint = "http://otel-collector:4318" }
    ["errors"] { provider = "sentry" }
    ["metrics"] { provider = "datadog"; site = "us5"; signals { "metrics" } }
  }
}
```

A collector that needs a token:

```pkl
opentelemetry {
  destinations {
    ["collector"] {
      endpoint = "https://otel.example.com"
      headerEnv { ["authorization"] = "OTEL_COLLECTOR_AUTH" }
      perSignal { ["metrics"] { endpoint = "https://metrics.example.com/otlp/v1/metrics" } }
    }
  }
}
```

The complete schema, with every other `elide.pkl` block, is in the [elide.pkl reference](https://elide.help/docs/elide-pkl-reference#opentelemetry-block).

## Environment variables

Elide reads the standard OpenTelemetry SDK variables. An invalid value is ignored, and the setting keeps its manifest
or default value.

| Variable | Effect | Default |
| --- | --- | --- |
| `OTEL_SDK_DISABLED` | `true` turns telemetry off. Only a `--otel-*` flag turns it back on. | `false` |
| `OTEL_SERVICE_NAME` | `service.name`. | `unknown_service:elide` |
| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes, `key=value,key=value`, values percent-encoded. | — |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL for `otlp` destinations; creates one named `otlp` when there is none. | — |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/protobuf`, `http/json`. | `http/protobuf` |
| `OTEL_EXPORTER_OTLP_HEADERS` | Request headers, `key=value,…`. Treated as secrets. | — |
| `OTEL_EXPORTER_OTLP_COMPRESSION` | `gzip` or `none`. | `gzip` |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | Request deadline in milliseconds. | `10000` |
| `OTEL_EXPORTER_OTLP_CERTIFICATE` | PEM file of trusted CA certificates; replaces the system trust store. | system |
| `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, `OTEL_EXPORTER_OTLP_CLIENT_KEY` | PEM client certificate and key for mutual TLS. | — |
| `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT` | Full URL for one signal, used as given. | — |
| `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_{PROTOCOL,HEADERS,COMPRESSION,TIMEOUT,CERTIFICATE,CLIENT_CERTIFICATE,CLIENT_KEY}` | The same settings for one signal. | — |
| `OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | `none` turns that signal off, for your code and for Elide. `otlp` with no destination anywhere sends that signal to `http://localhost:4318`. | — |
| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | Sampler and ratio, as `traces.sampler` and `traces.ratio`. | `parentbased_always_on` |
| `OTEL_PROPAGATORS` | `tracecontext`, `baggage`, `none` for the API in your code. Does not turn on baggage for Elide's HTTP server and clients. | `tracecontext,baggage` |
| `OTEL_METRIC_EXPORT_INTERVAL` | Metric export interval in milliseconds. | `60000` |
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `cumulative` or `delta`. | `cumulative` |
| `OTEL_METRICS_EXEMPLAR_FILTER` | `trace_based`, `always_on`, `always_off`. See [Exemplars](https://elide.help/docs/opentelemetry/correlation#metrics-and-exemplars). | `trace_based` |
| `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` | `logs` records errors as log records only; `logs/dup` also adds `exception` span events. | `logs/dup` |

Elide adds shorthands for providers and for settings the standard variables do not cover:

| Variable | Effect | Default |
| --- | --- | --- |
| `ELIDE_OTEL_PROVIDER` | Adds a destination for a provider, named after it. | — |
| `ELIDE_OTEL_REGION` | That destination's site or region: `us5` (Datadog), `eu` (PostHog, Honeycomb), `prod-us-east-0` (Grafana). | provider default |
| `ELIDE_OTEL_SIGNALS` | That destination's signals, e.g. `traces,logs`. | provider default |
| `ELIDE_OTEL_PROFILES` | `true` samples guest CPU profiles at 100 per second; a number sets the frequency. | off |
| `ELIDE_OTEL_BAGGAGE_INBOUND` | `true` admits served requests' `baggage` headers. | `false` |
| `ELIDE_OTEL_BAGGAGE_OUTBOUND` | `true` sends the current baggage on outgoing requests. | `false` |
| `ELIDE_OTEL_BAGGAGE_ALLOW` | Baggage keys allowed in both directions, comma-separated. | all keys |
| `ELIDE_OTEL_SHUTDOWN` | How the final export leaves at exit: `sidecar`, `inline`, `drop`. See [At exit](#at-exit). | `sidecar` |

`OTEL_EXPORTER_OTLP_*` apply to every destination that uses the `otlp` provider, including ones named in `elide.pkl`.
Provider credentials come from the variables listed on [Providers](https://elide.help/docs/opentelemetry/providers).

## Flags

| Flag | Effect |
| --- | --- |
| `--otel-endpoint=URL` | Adds or updates a destination with this endpoint. |
| `--otel-provider=PROVIDER` | Names that destination's provider; `otlp` when omitted. |
| `--otel-protocol=PROTOCOL` | `grpc`, `http/protobuf`, or `http/json` for that destination. |
| `--otel-shutdown=MODE` | `sidecar`, `inline`, or `drop`; see [At exit](#at-exit). |
| `--no-otel` | Turns telemetry off for this run, whatever the manifest and environment say. |

The flags take `=` and apply to `run`, `serve`, `test`, `build`, and `install`. Place global flags before the command:

```bash
elide --otel-endpoint=http://localhost:4317 --otel-protocol=grpc run app.ts
elide --no-otel test
```

## At exit

When a program ends, Elide still holds telemetry it has not sent: the last log records and spans, and a final
collection of metrics. The shutdown mode decides how that leaves the process:

| Mode | At exit | Exit waits |
| --- | --- | --- |
| `sidecar` | Hands the final export to a background exporter, which sends it. | under 250 ms, never on the network |
| `inline` | Sends the final export from the exiting process. | up to `shutdownTimeout` |
| `drop` | Discards the final export and counts it. | no |

`sidecar` is the default on Linux and macOS. The exporter is a small `elide` process, one per user, started by the
first exit that needs it. It accepts requests only from processes of the same user, keeps them in memory only, sends
each one once with the usual retries, and exits once no Elide process of that user is left and its queue is sent or
has expired. It never runs longer than 15 minutes. If the exporter cannot be started or reached in time, the final
export is dropped and counted, never sent from the exiting process.

On Windows, `inline` is the only mode; `sidecar` falls back to it with a warning. Choose `inline` to have the exiting
process send the data itself, for example when nothing may outlive the program:

```bash
elide run --otel-shutdown=inline app.ts
ELIDE_OTEL_SHUTDOWN=drop elide run app.ts
```

## How sources combine

- Destinations merge by name. A destination from `--otel-provider=honeycomb` and one named `honeycomb` in
  `elide.pkl` are the same destination; the flag's fields win.
- `OTEL_EXPORTER_OTLP_*` settings apply to every `otlp` destination. With no `otlp` destination, an endpoint
  variable creates one named `otlp`.
- `elide.pkl` and flag values are checked strictly: a bad value leaves telemetry off for the run, with a warning; see
  [Configuration errors](https://elide.help/docs/opentelemetry/troubleshooting#configuration-errors). Bad variable values are skipped.
- A destination left with no enabled signal is skipped. When no destination receives anything, telemetry stays off.
- Configuration is read once, at startup. Your code cannot change destinations, headers, or the resource.

## Samples

- [OTLP to a local collector](https://elide.help/docs/code-samples#otlp-to-a-local-collector)

---

# OpenTelemetry providers

URL: https://elide.help/docs/opentelemetry/providers

> Send Elide telemetry to an OTLP collector, Sentry, Datadog, PostHog, Honeycomb, or Grafana Cloud: which signals each accepts, its credential variable, endpoint, and a setup recipe.

A provider is a preset for one destination: it fills in the endpoint, the authentication header, and the signals and
protocols the service accepts. Every provider is reached over OTLP.

| Provider | Sent by default | Sent when listed | Protocols | Credential variable |
| --- | --- | --- | --- | --- |
| `otlp` | traces, metrics, logs; profiles when on | — | all | none; use `headerEnv` |
| `sentry` | traces, logs | — | `http/protobuf` | `SENTRY_DSN` |
| `datadog` | metrics, logs | traces | `http/protobuf`; `http/json` except logs | `DD_API_KEY` |
| `posthog` | logs | traces | `http/protobuf` | `POSTHOG_PROJECT_TOKEN` |
| `honeycomb` | traces, metrics, logs | — | all | `HONEYCOMB_API_KEY` |
| `grafana` | traces, metrics, logs | — | `http/protobuf` | `GRAFANA_CLOUD_OTLP_CREDENTIAL` |

Default signals are sent unless the destination lists `signals`. The others are sent only when named in `signals`
(or `ELIDE_OTEL_SIGNALS`). "all" is `grpc`, `http/protobuf`, and `http/json`. Errors travel inside traces, logs, and
metrics, so every provider receives them; see [Errors](https://elide.help/docs/opentelemetry/signals#errors).

Asking a provider for a signal or protocol it does not accept, or leaving its credential variable unset, leaves
telemetry off for the run with a warning; see [Configuration errors](https://elide.help/docs/opentelemetry/troubleshooting#configuration-errors).
Credential values never appear in logs or errors.

## Pick a provider at run time

`ELIDE_OTEL_PROVIDER` adds one destination for a provider, with `ELIDE_OTEL_REGION` and `ELIDE_OTEL_SIGNALS` for its
options:

```bash
ELIDE_OTEL_PROVIDER=honeycomb HONEYCOMB_API_KEY=... elide serve app.ts
```

The `--otel-provider=` flag does the same for one command. Use `elide.pkl` to keep the choice with the project, or to
send to several providers at once.

## OTLP collector or agent

Any OTLP receiver: the OpenTelemetry Collector, Grafana Alloy, a vendor agent, or a backend with an OTLP endpoint.

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 elide serve app.ts
```

```pkl
opentelemetry {
  destinations {
    ["collector"] {
      endpoint = "https://otel.example.com"
      protocol = "grpc"
      headerEnv { ["authorization"] = "OTEL_COLLECTOR_AUTH" }
    }
  }
}
```

| Setting | Value |
| --- | --- |
| Default endpoint | `http://localhost:4318`; `http://localhost:4317` with `grpc` |
| HTTP paths | `/v1/traces`, `/v1/metrics`, `/v1/logs`, `/v1development/profiles`, appended to `endpoint` |
| gRPC | `endpoint` used as given, with `http://` (plaintext) or `https://` |
| Authentication | `headers`, `headerEnv`, or `OTEL_EXPORTER_OTLP_HEADERS` |

Only `otlp` destinations take profiles, once profiles are turned on; see [Profiles](https://elide.help/docs/opentelemetry/signals#profiles).

## Sentry

Traces and logs, with the project's DSN:

```bash
ELIDE_OTEL_PROVIDER=sentry SENTRY_DSN=https://<key>@o123.ingest.us.sentry.io/456 elide serve app.ts
```

```pkl
opentelemetry {
  destinations {
    ["sentry"] { provider = "sentry"; dsn = "SENTRY_DSN" }
  }
}
```

| Setting | Value |
| --- | --- |
| Credential | `dsn` names the variable; default `SENTRY_DSN` |
| Endpoint | From the DSN: `https://<host>/api/<project>/integration/otlp/v1/{traces,logs}` |
| Header | `x-sentry-auth: sentry sentry_key=<key>` |
| Signals | traces, logs |

Uncaught errors reach Sentry as `exception` log records and as `exception` events on the failing span.

## Datadog

Metrics and logs by default, through Datadog's agentless OTLP intake:

```bash
ELIDE_OTEL_PROVIDER=datadog ELIDE_OTEL_REGION=us5 DD_API_KEY=... elide serve app.ts
```

```pkl
opentelemetry {
  destinations {
    ["datadog"] {
      provider = "datadog"
      site = "us5"
      signals { "metrics"; "logs"; "traces" }
    }
  }
}
```

| Setting | Value |
| --- | --- |
| Credential | `credential` names the variable; default `DD_API_KEY`. Sent as `dd-api-key`. |
| Site | `site`, then `DD_SITE`, then `datadoghq.com` |
| Endpoint | `https://otlp.<site>/v1/{traces,metrics,logs}` |
| Signals | metrics and logs by default; traces when listed |
| Temporality | Metrics are sent as delta. Setting `cumulative` with Datadog is an error. |

| `site` | Host |
| --- | --- |
| `us1`, `us` | `datadoghq.com` |
| `us3` | `us3.datadoghq.com` |
| `us5` | `us5.datadoghq.com` |
| `eu`, `eu1` | `datadoghq.eu` |
| `ap1` | `ap1.datadoghq.com` |
| `ap2` | `ap2.datadoghq.com` |
| `gov`, `us1-fed` | `ddog-gov.com` |
| any domain | used as given, e.g. `datadoghq.com` |

Traces are opt-in because Datadog's agentless trace intake must be enabled for your organization. With a Datadog
Agent running locally, use an `otlp` destination pointed at the Agent's OTLP receiver instead.

## PostHog

Logs by default; traces when listed:

```bash
ELIDE_OTEL_PROVIDER=posthog POSTHOG_PROJECT_TOKEN=phc_... elide serve app.ts
```

```pkl
opentelemetry {
  destinations {
    ["posthog"] { provider = "posthog"; region = "eu"; signals { "logs"; "traces" } }
  }
}
```

| Setting | Value |
| --- | --- |
| Credential | `credential` names the variable; default `POSTHOG_PROJECT_TOKEN`. Sent as `Authorization: Bearer`. |
| Region | `us` (default) or `eu` |
| Endpoint | `https://<region>.i.posthog.com/i/v1/{traces,logs}` |
| Signals | logs by default; traces when listed |

## Honeycomb

Traces, metrics, and logs:

```bash
ELIDE_OTEL_PROVIDER=honeycomb HONEYCOMB_API_KEY=... elide serve app.ts
```

```pkl
opentelemetry {
  service { name = "checkout" }
  destinations {
    ["honeycomb"] { provider = "honeycomb"; region = "eu"; protocol = "grpc" }
  }
}
```

| Setting | Value |
| --- | --- |
| Credential | `credential` names the variable; default `HONEYCOMB_API_KEY`. Sent as `x-honeycomb-team`. |
| Region | `us` (`api.honeycomb.io`, default) or `eu` (`api.eu1.honeycomb.io`) |
| Endpoint | `https://<host>/v1/{traces,metrics,logs}`; `<host>:443` with `grpc` |
| Signals | traces, metrics, logs |

Honeycomb names datasets after `service.name`; set it, or data lands in `unknown_service:elide`.

## Grafana Cloud

Traces, metrics, and logs through the stack's OTLP gateway. The credential is `<instance id>:<token>` from the
stack's OpenTelemetry connection page:

```bash
ELIDE_OTEL_PROVIDER=grafana ELIDE_OTEL_REGION=prod-us-east-0 \
GRAFANA_CLOUD_OTLP_CREDENTIAL=123456:glc_... elide serve app.ts
```

```pkl
opentelemetry {
  destinations {
    ["grafana"] { provider = "grafana"; region = "prod-us-east-0" }
  }
}
```

| Setting | Value |
| --- | --- |
| Credential | `credential` names the variable; default `GRAFANA_CLOUD_OTLP_CREDENTIAL`. Sent as HTTP basic auth. |
| Region | Required unless `endpoint` is set: the stack's zone, such as `prod-us-east-0` or `prod-eu-west-2` |
| Endpoint | `https://otlp-gateway-<zone>.grafana.net/otlp/v1/{traces,metrics,logs}` |
| Signals | traces, metrics, logs |

## Samples

- [OTLP to a local collector](https://elide.help/docs/code-samples#otlp-to-a-local-collector)

---

# OpenTelemetry signals

URL: https://elide.help/docs/opentelemetry/signals

> Traces, metrics, logs, errors, and experimental guest CPU profiles in Elide: what Elide records for each, the settings that control it, and how your code adds its own.

| Signal | Elide records | Your code adds | Settings |
| --- | --- | --- | --- |
| Traces | HTTP server and client spans, build and test spans | Spans through the tracer API | `traces`, `runtime.traces` |
| Metrics | HTTP, process, and error metrics | Counters, histograms, gauges, observable instruments | `metrics`, `runtime.metrics` |
| Logs | Its own warnings and errors | Logs API records, `console.*`, Python `logging` | `logs`, `runtime.logs` |
| Errors | Uncaught exceptions, rejections, failing handlers, crashes | `span.recordException(…)` | follows logs, traces, and metrics |
| Profiles (experimental) | Guest CPU samples | — | `profiles` |

User settings (`traces`, `metrics`, `logs`) govern telemetry from your code; `runtime` settings govern Elide's own.
Turning a signal off with `OTEL_TRACES_EXPORTER=none` (or the metrics and logs equivalents) turns off both.

## Traces

Spans start synchronously: the sampling decision and span context are available as soon as `startSpan` returns.
Context follows `await`, timers, and callbacks in JavaScript, and `contextvars` in Python.

| Setting | Effect | Default |
| --- | --- | --- |
| `traces.enabled` | Record spans from your code. | on |
| `traces.sampler`, `traces.ratio` | Head sampler for your spans. | `parentbased_always_on` |
| `runtime.traces` | Record Elide's HTTP and toolchain spans. | on |

With `parentbased_*` samplers, a sampled caller's `traceparent` keeps the request sampled, and your spans inside it
follow. Turning `traces.enabled` off keeps your spans' context flowing without recording them, so outgoing requests
still continue the caller's trace.

Recording never waits on export. When an export queue is full, spans are dropped and counted; read the counts with
`status()` from [`elide:telemetry`](https://elide.help/docs/opentelemetry/javascript#elidetelemetry) or
[`elide.telemetry`](https://elide.help/docs/opentelemetry/python#elidetelemetry).

## Metrics

| Setting | Effect | Default |
| --- | --- | --- |
| `metrics.enabled` | Record instruments from your code. | on |
| `metrics.interval` | Collect and export every interval. | `60.s` |
| `metrics.temporality` | `cumulative` or `delta`. | `cumulative`; `delta` for Datadog |
| `runtime.metrics` | Record Elide's HTTP, process, and error metrics. | on |

Your code can create counters, up-down counters, histograms (with `advice.explicitBucketBoundaries` in JavaScript or
`explicit_bucket_boundaries_advisory` in Python), gauges, and observable counters, up-down counters, and gauges.
Observable callbacks run at each collection. Elide's metric names are listed in
[Emitted telemetry](https://elide.help/docs/opentelemetry/reference#metrics).

Pending measurements are exported at exit, so a short script's metrics are not lost.

## Logs

| Setting | Effect | Default |
| --- | --- | --- |
| `logs.enabled` | Export records from your code. | on |
| `logs.level` | Minimum severity exported. | `info` |
| `logs.console` | Also export `console.*` and Python `logging` output. | on |
| `runtime.logs` | Minimum severity of Elide's own records. | `warn` |

Capturing output does not change what the program prints. `console.*` output is exported in the `console` scope;
Python `logging` records keep their logger's name as the scope, and only records some handler would print are
exported. Log API records keep structured bodies (objects, lists, bytes).

## Errors

Errors are exported as OTLP records, so every destination receives them through whichever of traces, logs, and
metrics it accepts:

| Source | `elide.error.origin` | Span status |
| --- | --- | --- |
| Uncaught exception | `uncaught` | — |
| Unhandled promise rejection | `rejection` | — |
| Request handler throws or rejects | `handler` | server span `ERROR` |
| `span.recordException(error)` | `guest_api` | unchanged |
| Earlier process crashed | `crash` | — |

Each produces an `exception` log record, an `exception` span event, and an `elide.errors` increment; see
[Errors](https://elide.help/docs/opentelemetry/correlation#errors). `elide.errors` is a runtime metric and follows `runtime.metrics`.

## Profiles

Guest CPU profiles are experimental and off by default. Elide samples the stacks of running JavaScript and Python code
and exports OTLP profiles, with each sample linked to the span active on its thread.

```pkl
opentelemetry {
  profiles { enabled = true; frequency = 99 }
}
```

```bash
ELIDE_OTEL_PROFILES=true elide serve app.ts   # 100 samples per second
ELIDE_OTEL_PROFILES=49 elide serve app.ts     # 49 samples per second
```

| Detail | Value |
| --- | --- |
| Destinations | `otlp` only; the receiver must accept the OTLP profiles signal |
| Export | Every 30 seconds and at exit, to `/v1development/profiles` over HTTP |
| Frequency | 1 to 10,000 samples per second; default 100 |
| Coverage | JavaScript and Python code; not Elide's own code |
| Conflicts | Off while `--profiler` is in use |

## Shutdown

At exit Elide hands what is still pending to a background exporter, so the program exits without waiting on the
network; `--otel-shutdown=inline` exports it from the exiting process instead, for up to `shutdownTimeout` (5 seconds
by default). See [At exit](https://elide.help/docs/opentelemetry/configuration#at-exit). `flush()` in
[JavaScript](https://elide.help/docs/opentelemetry/javascript#elidetelemetry) and [Python](https://elide.help/docs/opentelemetry/python#elidetelemetry) exports
on demand.

## Samples

- [Custom span in TypeScript](https://elide.help/docs/code-samples#custom-span-in-typescript)
- [Metrics instruments](https://elide.help/docs/code-samples#metrics-instruments)
- [Python span and logging](https://elide.help/docs/code-samples#python-span-and-logging)

---

# Runtime instrumentation

URL: https://elide.help/docs/opentelemetry/runtime

> What Elide instruments without code changes: server spans and metrics for served requests, fetch client spans, process metrics, build and test spans in CI with TRACEPARENT, and what is not instrumented yet.

With a destination configured, Elide records these without code changes:

| Area | Spans | Metrics | Setting |
| --- | --- | --- | --- |
| Served HTTP requests | `SERVER` span per request | `http.server.request.duration`, `http.server.active_requests`, `elide.http.server.rejected_requests` | `runtime.traces`, `runtime.metrics` |
| `fetch` | `CLIENT` span per request | `http.client.request.duration` | `runtime.traces`, `runtime.metrics` |
| Process | — | CPU time, memory, threads, file descriptors, uptime | `runtime.metrics` |
| Errors | `exception` events | `elide.errors` | follows logs, traces, metrics |
| `elide build`, `elide test`, `elide install` | Command, task, and test spans | — | `runtime.traces` |
| Elide's own logs | — | — | `runtime.logs` |

Names, units, and attributes are listed in [Emitted telemetry](https://elide.help/docs/opentelemetry/reference).

## Serving

Every request served by `elide serve`, an exported `fetch` handler, or a `node:http` server gets a server span and
the HTTP server metrics. The handler runs inside the span, so spans your code starts there are its children:

```ts
// server.ts
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("orders");

export default {
  async fetch(request: Request): Promise<Response> {
    return tracer.startActiveSpan("load order", async (span) => {
      span.setAttribute("order.id", new URL(request.url).searchParams.get("id") ?? "");
      span.end();
      return new Response("ok\n");
    });
  },
};
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 elide serve server.ts
```

A request carrying a valid `traceparent` continues the caller's trace. A 5xx response, a handler that throws, an
abandoned response, or a reset connection marks the server span `ERROR`.

Request rate comes from the count of `http.server.request.duration`: divide the increase in count by
the elapsed seconds. These counts include unsampled requests, so changing trace sampling does not
change the reported throughput. `http.server.active_requests` tracks requests still in flight.

`http.server.request.body.size` and `http.server.response.body.size` record body sizes in bytes.
Known empty bodies contribute zero; unknown response sizes are omitted. These histograms share the
duration metric's method, scheme, protocol, status, error, and known route dimensions. Raw paths,
query strings, user agents, and baggage are not automatic metric dimensions. Body-size metric names
follow OpenTelemetry's development semantic conventions.

### Routes

Server spans are named after the method: `GET`. A `node:http` server can name the matched route, which sets
`http.route` and renames the span `GET /items/:id`:

```ts
// routes.ts
import http from "node:http";
import { trace } from "@opentelemetry/api";

http
  .createServer((req, res) => {
    trace.getActiveSpan()?.setAttribute("http.route", "/items/:id");
    res.end("ok\n");
  })
  .listen(8091);
```

A router that sets `req.route` (Express and compatible routers) supplies the route without that line; `req.baseUrl`
is prefixed. Inside a `node:http` handler or an exported `fetch` handler the active span stands for the server
span, and only `http.route` set on it reaches the exported span.

## fetch

Each `fetch` gets a client span, parented to the span active where `fetch` was called, and sends `traceparent` and
`tracestate` so the next service continues the trace. A `traceparent` header you set yourself is kept.

```ts
import { trace } from "@opentelemetry/api";

await trace.getTracer("sync").startActiveSpan("sync inventory", async (span) => {
  await fetch("https://inventory.example.com/items"); // child CLIENT span
  span.end();
});
```

## Process metrics

`process.cpu.time`, `process.memory.usage`, `process.thread.count`, `process.unix.file_descriptor.count`, and
`process.uptime`, collected at each metric export on Linux and macOS.

## Builds and tests in CI

### Enable build reports

Build-report export is opt-in: configure an OTLP destination with CLI flags, `elide.pkl`, or
[environment variables](https://elide.help/docs/opentelemetry/configuration#environment-variables). With no destination configured,
Elide exports no build or test telemetry. Once a destination accepts traces, `runtime.traces` enables the command,
task, execution-unit, and individual-test spans together; it defaults to `true`. There is no separate build-report flag.

For one invocation, point Elide at a running OTLP/HTTP collector. Place these global flags before the command:

```bash
elide --otel-endpoint=http://localhost:4318 --otel-protocol=http/protobuf build
elide --otel-endpoint=http://localhost:4318 --otel-protocol=http/protobuf test
```

For a project, add this configuration to `elide.pkl` (merge the block into an existing manifest):

```pkl
amends "elide:project.pkl"

name = "my-project"

opentelemetry {
  service { name = "my-project-builds" }
  destinations {
    ["collector"] {
      endpoint = "http://localhost:4318"
      protocol = "http/protobuf"
      signals { "traces" }
    }
  }
  runtime { traces = true }
}
```

Then run `elide build` or `elide test` normally. Replace the endpoint with your collector's base URL;
Elide appends `/v1/traces` for HTTP export. For gRPC, use port `4317` and protocol `grpc`.
The destination above exports only traces. Configure authentication through
[environment-backed headers](https://elide.help/docs/opentelemetry/configuration#destinations).

To suppress telemetry for one invocation, even when the project or environment enables it:

```bash
elide --no-otel build
elide --no-otel test
```

In the manifest, `opentelemetry { enabled = false }` disables all telemetry. To keep application telemetry but
suppress automatic build/test spans, set `opentelemetry { runtime { traces = false } }`; this also disables Elide's
automatic HTTP spans. Setting only `traces { enabled = false }` controls application spans and does not disable
runtime spans. `OTEL_TRACES_EXPORTER=none` disables both kinds of trace export.

To verify export, find `elide.build` or `elide.test` in your collector under the configured service name, then group
its descendants by `elide.invocation.id`. Task, execution, and test spans appear when that work actually runs.
Sampling still applies: an unsampled upstream `TRACEPARENT` suppresses spans with the default parent-based sampler.
For a local diagnostic run, `OTEL_TRACES_SAMPLER=always_on` records every span; it does not guarantee delivery if
an exporter queue fills. See [Troubleshooting](https://elide.help/docs/opentelemetry/troubleshooting) if no spans arrive.

`ELIDE_BUILD_TELEMETRY` is a separate local timing-profile switch. It is not required for OTLP build reports and
does not enable OTLP export.

### Correlate builds and tests

`elide build`, `elide test`, and `elide install` record a root span for the command (`elide.build`, `elide.test`,
`elide.install`). Build stages and tasks become child spans with outcome and cache-hit attributes, and each test case
nests under its execution unit (a JS file or JVM launcher fork), which nests under the owning task. The root span
continues a W3C `TRACEPARENT` from the environment, so a CI job's own trace can include the build:

```bash
TRACEPARENT=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 \
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com \
elide test
```

The command span carries `elide.ci.*` attributes from GitHub Actions, GitLab CI, Buildkite, and CircleCI variables
(see [Emitted telemetry](https://elide.help/docs/opentelemetry/reference#toolchain)) and `process.exit.code`. Elide waits up to 5 seconds
for the export before the command returns.

Build-report spans carry schema version `1`, an `elide.span.type`, and an `elide.invocation.id` on every span.
The invocation ID combines the command's trace ID and span ID: two commands can share a CI trace without merging
into one build. Use this ID for a single report, and workspace/project name plus task path and test identity to
compare reports across runs. Scope comparisons to the same repository or service; project names alone are not
globally unique. CI revision and pipeline attributes remain on the command span.

Task spans include their implementation type, workspace-qualified path, prerequisite paths, cacheability, and
outcome. Driver operations remain nested under tasks. JS files have zero-based shard indexes and the discovered
file count; JVM source-set forks have separate execution IDs, including discovery fallback forks. This describes
local execution units; it does not add distributed sharding. Each execution reports result counts and becomes an
error on a failed test or unsuccessful execution, even when the runner returned normally.

Individual tests carry a stable, length-prefixed display-path identity and an occurrence number within their
execution. Identical display paths intentionally share a comparison key; occurrences distinguish emitted results,
not retries. JUnit's text feed cannot yet provide native unique IDs. Test span positions are reconstructed from
result arrival and reported duration, clamped to their execution's lifetime; `elide.test.duration_ns` preserves the
reported duration. This is sufficient for result comparison but not an exact concurrent-test timeline.
Execution spans measure their full lifecycle. Filtered tests contribute to execution counts but emit no test span.

Telemetry remains subject to tracing configuration, sampling, and exporter queue limits. It is not a lossless build
event archive. Structured JUnit identities/start events, per-task scheduler wait, artifact provenance, and a durable
report store are follow-up work; this schema does not claim complete Bazel or Gradle report parity.

In GitHub Actions:

```yaml
- name: Test
  run: elide test
  env:
    OTEL_EXPORTER_OTLP_ENDPOINT: ${{ vars.OTEL_ENDPOINT }}
    OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_HEADERS }}
    OTEL_SERVICE_NAME: my-service-ci
```

## Elide's own logs

Elide's warnings and errors are exported as log records in the `dev.elide.runtime` scope, at or above `runtime.logs`
(`warn` by default), with the active span's ids. Set `runtime { logs = "off" }` to stop them.

Rust instrumentation and library diagnostics also use this runtime scope. Structured log fields and span
parentage are retained. Console output follows `ELIDE_LOG` and the active console or progress logger;
export independently follows `runtime.logs`. Application log and trace settings do not enable runtime signals.

Compio's internal task and poll spans are off by default. Set `ELIDE_OTEL_RUNTIME_INTERNAL_TRACES=true`
to include them when runtime tracing is enabled and a telemetry destination is configured. This can produce
many spans; library log events still follow `runtime.logs`. Tokio's unstable internal tracing is not enabled
in shipped builds. Library events do not automatically become metrics, and exporter diagnostics are excluded
from export to prevent feedback.

## Not instrumented yet

| Area | Workaround |
| --- | --- |
| `node:http` and `node:https` client requests: no client span, no `traceparent` | Inject headers with `propagation.inject`; see [Trace context](https://elide.help/docs/opentelemetry/correlation#trace-context-over-http) |
| Python HTTP clients (`urllib`, `requests`) | Inject headers with `opentelemetry.propagate.inject` |
| Serving from Python | Serve from JavaScript or TypeScript |
| Garbage collection and event-loop delay metrics | — |
| Database, file system, and child process spans | Create spans in your code |
| Java and Kotlin programs | Not supported; see [Languages](https://elide.help/docs/opentelemetry#languages) |

---

# Correlation, propagation, and baggage

URL: https://elide.help/docs/opentelemetry/correlation

> How Elide links logs, errors, metrics, and profiles to the active span, continues W3C trace context across HTTP, and propagates W3C baggage only when you allow it.

The span active where a signal is produced links that signal to its trace. Elide applies this to everything it
records, with no code changes.

| Signal | Linked to the active span by |
| --- | --- |
| Log records | Trace id, span id, and trace flags on the record |
| Errors | An `exception` log record and span event on the span, and an `elide.errors` exemplar |
| Metrics | Exemplars on histogram buckets and sums |
| Profiles | A link from each CPU sample to its span |

Request handlers run inside the request's server span, so anything they log, throw, measure, or call joins the
request's trace.

## Logs

Every log record emitted inside a span carries its trace id, span id, and trace flags: records from the
OpenTelemetry logs API, captured `console.*` and Python `logging` output, and Elide's own log records.

```ts
// handler.ts
export default {
  async fetch(request: Request): Promise<Response> {
    console.log("looking up order"); // exported with the request span's ids
    return new Response("ok");
  },
};
```

## Errors

One error produces three records that share a timestamp and the same `exception.type`, `exception.message`, and
`exception.stacktrace`:

| Record | Where |
| --- | --- |
| Log record, severity `ERROR`, `event.name = exception` | Linked to the active span |
| `exception` event on the span, and `ERROR` status when the failure ends the span | The active span |
| `elide.errors` increment, with an exemplar pointing at the span | `error.type`, `elide.error.origin` |

With no active span, the log record and counter are still emitted. `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN=logs` drops
the span events; the default, `logs/dup`, keeps both. Uncaught exceptions, unhandled rejections, failing request
handlers, and `span.recordException(…)` all take this path; `recordException` never changes span status.

A process that crashes cannot export. The next Elide process on the machine that has telemetry configured exports
the crash report as a `FATAL` error record: up to 16 reports per run, from the last 7 days, each sent once. See
[Emitted telemetry](https://elide.help/docs/opentelemetry/reference#log-records).

Only reports from a process with the same `service.name` are exported; a crash in a process without telemetry
configured is never exported.

## Metrics and exemplars

A counter or histogram measurement recorded inside a sampled span carries an exemplar: the trace id, span id, value,
and time. Backends that read exemplars link a latency bucket to an example trace.

| `OTEL_METRICS_EXEMPLAR_FILTER` | Exemplars from |
| --- | --- |
| `trace_based` (default) | Measurements inside a sampled span |
| `always_on` | Every measurement |
| `always_off` | None |

Elide keeps the latest exemplar per histogram bucket and per sum in each export. `http.server.request.duration` and
`http.client.request.duration` carry exemplars of their own request spans.

## Profiles

Each guest CPU sample links to the span active on the sampled thread when the sample was taken, including after
`await`, in promise callbacks, and across Python asyncio tasks. See [Profiles](https://elide.help/docs/opentelemetry/signals#profiles).

## Trace context over HTTP

Elide's HTTP server and clients use W3C Trace Context in both directions:

| Direction | Behavior |
| --- | --- |
| Inbound | A valid `traceparent` (with `tracestate`) on a served request becomes the parent of the server span. An invalid one starts a new trace. |
| Outbound | `fetch` sends `traceparent` and `tracestate` for its client span. A header the caller set is never replaced. |

```bash
curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' http://localhost:8080/
```

`traces.propagators` (or `OTEL_PROPAGATORS`) chooses what `propagation.inject` and `propagation.extract` do in your
code: `tracecontext`, `baggage`, or `none`. Removing `tracecontext` also stops Elide's HTTP clients from sending
`traceparent`. `node:http` client requests and Python HTTP clients do not send it yet; inject it with the API:

```ts
import { context, propagation } from "@opentelemetry/api";
import http from "node:http";

const headers: Record<string, string> = {};
propagation.inject(context.active(), headers);
http.get("http://localhost:8081/inventory", { headers });
```

## Baggage

W3C baggage carries key-value pairs alongside a trace. Your code can always read, set, and send baggage through the
OpenTelemetry API. Elide's HTTP server and clients pass the `baggage` header only for directions you turn on, because
baggage from a client is untrusted input:

```pkl
opentelemetry {
  propagation {
    baggage {
      inbound = true
      outbound = true
      allow { "tenant"; "region" }
      spanAttributes { "tenant" }
    }
  }
}
```

| Property | Variable | Effect | Default |
| --- | --- | --- | --- |
| `inbound` | `ELIDE_OTEL_BAGGAGE_INBOUND` | A served request's `baggage` header becomes the handler's baggage. | `false` |
| `outbound` | `ELIDE_OTEL_BAGGAGE_OUTBOUND` | `fetch` sends the current baggage, unless the request sets `baggage` itself. | `false` |
| `allow` | `ELIDE_OTEL_BAGGAGE_ALLOW` | Only these keys pass, in both directions. | all keys |
| `spanAttributes` | — | These inbound keys are recorded on the server span as `baggage.<key>`; each must be in `allow`. | none |

- A header over 8,192 bytes or 180 members, or with any malformed member, is dropped whole.
- Baggage received on a request reaches outgoing requests only when both directions are on.
- `OTEL_PROPAGATORS` does not turn baggage on for Elide's HTTP server and clients; it affects only the API in your
  code.

Read inbound baggage in a handler:

```ts
import { context, propagation } from "@opentelemetry/api";

export default {
  async fetch(): Promise<Response> {
    const tenant = propagation.getBaggage(context.active())?.getEntry("tenant")?.value;
    return new Response(`tenant: ${tenant ?? "none"}\n`);
  },
};
```

## Samples

- [Baggage across services](https://elide.help/docs/code-samples#baggage-across-services)

---

# OpenTelemetry in JavaScript and TypeScript

URL: https://elide.help/docs/opentelemetry/javascript

> Use @opentelemetry/api in JavaScript and TypeScript on Elide without an SDK: built-in and installed copies, spans with using, metrics, logs, SDK takeover and handback, the elide:telemetry module, and diagnostics_channel events.

Instrument code with the standard [`@opentelemetry/api`](https://www.npmjs.com/package/@opentelemetry/api) and
`@opentelemetry/api-logs`. Elide implements them: there is no SDK, exporter, or collector to add to the
application, and libraries that already use the API work unchanged.

```ts
// app.ts
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("checkout");
await tracer.startActiveSpan("charge", async (span) => {
  span.setAttribute("order.id", 42);
  console.log("charged");
  span.end();
});
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 elide run app.ts
```

## The API package

| Your project | `import "@opentelemetry/api"` resolves to |
| --- | --- |
| No `@opentelemetry/api` installed | Elide's built-in copy (API 1.9) |
| `@opentelemetry/api` 1.x installed | Your copy, backed by Elide |

The same holds for `@opentelemetry/api-logs` and `@opentelemetry/api/experimental`. Install the package as a dev
dependency when you want its TypeScript types:

```bash
elide add -D @opentelemetry/api
```

Elide registers its tracer, meter, logger, context manager, and propagator in the API's global registry before your
code runs, so any 1.x copy finds them. When telemetry is not configured, the API returns no-op implementations.

## Traces

Tracers, spans, links, events, and status follow the OpenTelemetry API and SDK rules: invalid attribute values are
dropped with a warning, operations on ended spans warn, `UNSET` status is ignored, and `OK` is final.

Spans implement `Symbol.dispose`, so `using` ends them at the end of the block:

```ts
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("jobs");
{
  using span = tracer.startSpan("nightly");
  span.setAttribute("job.items", 120);
} // span ends here
```

Elide's tracers also have `withSpan(name, [options], [context], fn)`: it runs `fn` with a new active span, ends the
span when `fn` returns or its promise settles, and records a throw or rejection as an `ERROR`:

```ts
const tracer = trace.getTracer("jobs") as any;
await tracer.withSpan("import", async (span) => {
  await importRows();
});
```

`wrapTracer` from `@opentelemetry/api/experimental` (or [`elide:telemetry`](#elidetelemetry)) gives any tracer the
same `withSpan` and `withActiveSpan`, typed.

Context follows `await`, promises, timers, event emitters, and callbacks; it is backed by `AsyncLocalStorage`.
Request handlers run inside their server span.

## Metrics

```ts
import { metrics } from "@opentelemetry/api";

const pending: string[] = [];
const meter = metrics.getMeter("checkout");
const orders = meter.createCounter("orders", { unit: "{order}" });
const latency = meter.createHistogram("charge.duration", {
  unit: "s",
  advice: { explicitBucketBoundaries: [0.01, 0.05, 0.1, 0.5, 1] },
});
const queue = meter.createObservableGauge("queue.depth");
queue.addCallback((result) => result.observe(pending.length));

orders.add(1, { region: "eu" });
latency.record(0.042);
```

All synchronous and observable instruments are supported. Observable callbacks run on the program's event loop at
each collection; a callback may return a promise. Measurements are validated as the SDK does (counters and
histograms reject negative values).

## Logs

```ts
import { logs, SeverityNumber } from "@opentelemetry/api-logs";

logs.getLogger("checkout").emit({
  severityNumber: SeverityNumber.WARN,
  severityText: "WARN",
  body: { event: "retry", attempt: 2 },
});
```

Non-string bodies export as structured values. `console.*` output is exported too while `logs.console` is on; see
[Logs](https://elide.help/docs/opentelemetry/signals#logs).

## Propagation

`propagation.inject` and `propagation.extract` use the propagators from `traces.propagators` or `OTEL_PROPAGATORS`
(default `tracecontext,baggage`). Baggage set with `propagation.setBaggage` stays in your code's context; Elide's HTTP
clients send it only when outbound baggage is on. See [Correlation and baggage](https://elide.help/docs/opentelemetry/correlation).

## Using an OpenTelemetry SDK

You can still bring the JavaScript SDK (`@opentelemetry/sdk-node`, `sdk-trace-*`, `sdk-metrics`, `sdk-logs`) and its
exporters. When it registers a provider, it takes that signal over:

| Event | Result |
| --- | --- |
| SDK registers a tracer, meter, or context manager | Elide steps aside for that signal and prints a warning. Tracers, meters, and observable callbacks already handed out forward to the SDK. |
| `@opentelemetry/sdk-logs` is loaded | Elide frees the logs global; its loggers keep recording until the SDK registers a logger provider, then forward to it. |
| SDK calls `disable()` on a global | The signal returns to Elide. |
| SDK is loaded but registers nothing | Elide stays in place. |

The warning names the signal:

```text
[warn] dev.elide.lang.javascript.telemetry.JsTelemetry An OpenTelemetry SDK
registered its own tracer provider; Elide's JavaScript tracer provider steps
aside
```

`status().steppedAside` then lists `trace`.

Call `release()` from `elide:telemetry` before the SDK starts to hand it every signal without warnings. Elide's own
server, client, and error telemetry keeps recording through Elide either way, and request handlers run under
whichever context manager is registered.

## `elide:telemetry`

Controls the API does not cover. Types ship in `@elide-dev/types`; every function is safe to call when telemetry is
not configured.

```ts
import { trace } from "@opentelemetry/api";
import { flush, status } from "elide:telemetry";

{
  using span = trace.getTracer("jobs").startSpan("nightly");
}
const ok = await flush();
console.log(ok, status().spans);
```

| Export | Type | Description |
| --- | --- | --- |
| `active` | `boolean` | Whether telemetry is configured for this process. |
| `flush(timeoutMillis?)` | `(timeoutMillis?: number) => Promise<boolean>` | Exports everything recorded so far, waiting up to `timeoutMillis` (default `5000`). Resolves with whether every destination accepted it; never rejects. |
| `status()` | `() => TelemetryStatus` | Approximate, process-wide pipeline counters; see below. |
| `release()` | `() => boolean` | Stops serving as the global OpenTelemetry implementation for good, so an SDK registered afterwards owns every signal. Elide's runtime instrumentation keeps recording. Returns `false` if already released. |
| `enter(ctx)` | `(context: Context) => ContextScope` | Makes `ctx` active for the rest of the current synchronous scope and the async work it starts. `exit()` or `using` restores the previous context. Warns and does nothing when an SDK registered its own context manager. |
| `wrapTracer(tracer)` | `(tracer: Tracer) => SugaredTracer` | The `SugaredTracer` of `@opentelemetry/api/experimental`: `withActiveSpan` and `withSpan` end the span with the callback and record a throw or rejection. `options.onException` replaces that recording. |
| `currentSpanContext()` | `() => ActiveSpanContext \| undefined` | The active span's `traceId`, `spanId`, `traceFlags`, and `traceparent`, or `undefined` outside a valid span. |
| `api` | `typeof import("@opentelemetry/api")` | The API surface Elide serves. |
| `logs` | `typeof import("@opentelemetry/api-logs")` | The logs API surface Elide serves. |

```ts
interface TelemetryStatus {
  readonly active: boolean;
  readonly released: boolean;
  /** Signals an SDK took over: "trace", "metrics", "context", "propagation", "logs". */
  readonly steppedAside: readonly string[];
  readonly spans: {
    readonly started: number;
    readonly unsampled: number;
    readonly ended: number;
    readonly live: number;
    readonly exported: number;
    readonly dropped: number; // a destination queue was full
    readonly tableFull: number; // the open-span table was full
    readonly reclaimed: number;
    readonly handedOff: number; // sent at exit by the background exporter
    readonly exitDropped: number; // produced at exit and dropped
  };
  readonly logs: {
    readonly emitted: number;
    readonly filtered: number; // below logs.level
    readonly exported: number;
    readonly dropped: number;
    readonly handedOff: number;
    readonly exitDropped: number;
  };
  readonly metrics: { readonly handedOff: number; readonly exitDropped: number };
  readonly exportFailures: number;
  readonly exportsAbandoned: number; // in-process exports still running when exit ended them
}
```

Pass a context to code that runs outside the current one, such as a queue consumer:

```ts
import { context, trace } from "@opentelemetry/api";
import { currentSpanContext, enter } from "elide:telemetry";

const saved = context.active();
setImmediate(() => {
  using _scope = enter(saved);
  console.log(currentSpanContext()?.traceparent);
});
```

## `diagnostics_channel` events

Instrumentation libraries that subscribe to Node's diagnostics channels see the same events as on Node:

| Channel | Published by |
| --- | --- |
| `http.server.request.start` | `node:http` server, before the request handler |
| `http.server.response.created` | `node:http` server |
| `http.server.response.finish` | `node:http` server |
| `http.client.request.created`, `http.client.request.start` | `node:http` client |
| `http.client.request.error` | `node:http` client |
| `http.client.response.finish` | `node:http` client |
| `undici:request:create` | `fetch`, before dispatch (`request.origin`, `method`, `path`, `headers`) |

See [`node:diagnostics_channel`](https://elide.help/docs/api-node-diagnostics-channel).

## Samples

- [Custom span in TypeScript](https://elide.help/docs/code-samples#custom-span-in-typescript)
- [Metrics instruments](https://elide.help/docs/code-samples#metrics-instruments)
- [Baggage across services](https://elide.help/docs/code-samples#baggage-across-services)

---

# OpenTelemetry in Python

URL: https://elide.help/docs/opentelemetry/python

> Use the opentelemetry API in Python on Elide without an SDK: the vendored and installed API, spans, metrics, logging export, provider handover, and the elide.telemetry module.

Instrument code with the standard [`opentelemetry`](https://pypi.org/project/opentelemetry-api/) API. Elide
implements it: there is no SDK, exporter, or `opentelemetry-instrument` wrapper to add, and libraries that already
use the API work unchanged.

```python
# app.py
import logging
from opentelemetry import trace

tracer = trace.get_tracer("checkout")
with tracer.start_as_current_span("charge") as span:
    span.set_attribute("order.id", 42)
    logging.warning("card declined, retrying")
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 elide run app.py
```

## The API package

| Your environment | `import opentelemetry` resolves to |
| --- | --- |
| No `opentelemetry-api` installed | Elide's vendored copy (`opentelemetry-api` 1.45.1) |
| `opentelemetry-api` installed | Your copy, backed by Elide |

Elide installs its tracer, meter, and logger providers when your code first imports `opentelemetry.trace`,
`opentelemetry.metrics`, or `opentelemetry._logs`. Nothing is imported before your code does, and the import order
among those modules does not matter. The vendored copy
answers `importlib.metadata` like an installed wheel, so `OTEL_PROPAGATORS`, `OTEL_PYTHON_CONTEXT`, and the
`OTEL_PYTHON_*_PROVIDER` variables work as usual. When telemetry is not configured, the API returns its no-op
implementations.

## Traces

Tracers, spans, links, events, and status follow the API. Context is the API's `contextvars` context, so it follows
`with` blocks, threads that copy the context, and asyncio tasks.

```python
from opentelemetry import trace

tracer = trace.get_tracer("jobs")

@tracer.start_as_current_span("import rows")
def import_rows(rows):
    trace.get_current_span().set_attribute("rows", len(rows))
```

A span started with no active Python span is parented to the request Elide is serving on that thread, if any. Passing
an explicit `context=` starts a root span instead.

## Metrics

```python
from opentelemetry import metrics

pending = []
meter = metrics.get_meter("checkout")
orders = meter.create_counter("orders", unit="{order}")
latency = meter.create_histogram(
    "charge.duration", unit="s", explicit_bucket_boundaries_advisory=[0.01, 0.05, 0.1, 0.5, 1]
)

def queue_depth(options):
    yield metrics.Observation(len(pending))

meter.create_observable_gauge("queue.depth", callbacks=[queue_depth])

orders.add(1, {"region": "eu"})
latency.record(0.042)
```

All synchronous and observable instruments are supported, and callbacks may be generators. Callbacks run at each
collection.

## Logging

With `logs.console` on (the default), records that a `logging` handler would print are also exported as log records,
with the active span's ids. What `logging` prints is unchanged, and records no handler would emit are not exported.

| `logging` field | Log record |
| --- | --- |
| Logger name | Instrumentation scope |
| `levelno` | Severity: `DEBUG` 5, `INFO` 9, `WARNING` 13, `ERROR` 17, `CRITICAL` 21 |
| `getMessage()` | Body |
| `pathname`, `funcName`, `lineno` | `code.file.path`, `code.function.name`, `code.line.number` |
| `exc_info` | `exception.type`, `exception.message`, `exception.stacktrace` |

The logs API works too; records keep structured bodies (`dict`, `list`, `bytes`):

```python
from opentelemetry._logs import get_logger, LogRecord, SeverityNumber

get_logger("checkout").emit(
    LogRecord(severity_number=SeverityNumber.WARN, body={"event": "retry", "attempt": 2})
)
```

An uncaught exception is exported as an error with its Python traceback; see [Errors](https://elide.help/docs/opentelemetry/signals#errors).

## Using an OpenTelemetry SDK

An application can still set its own providers, from `opentelemetry-sdk` or `opentelemetry-instrument`:

| Event | Result |
| --- | --- |
| The application sets a tracer, meter, or logger provider | It takes over that signal and Elide prints a warning. Tracers, meters, loggers, and observable callbacks created earlier forward to it. |
| `OTEL_PYTHON_TRACER_PROVIDER` (or `_METER_`, `_LOGGER_`) names a provider | Elide never installs its own for that signal. |
| `elide.telemetry.release()` | Elide unsets its providers; the application's take over without warnings. |

```text
An OpenTelemetry SDK set its own tracer provider; Elide's Python tracer provider steps aside
```

Elide's runtime telemetry keeps recording either way.

## `elide.telemetry`

Controls the API does not cover. Stubs ship with Elide's Python type stubs; every function is safe to call when
telemetry is not configured.

```python
import elide.telemetry
from opentelemetry import trace

with trace.get_tracer("jobs").start_as_current_span("nightly"):
    print(elide.telemetry.current_span_context()["traceparent"])

elide.telemetry.flush()
print(elide.telemetry.status()["spans"])
```

| Function | Returns | Description |
| --- | --- | --- |
| `active()` | `bool` | Whether telemetry is configured for this process. |
| `flush(timeout_millis=5000)` | `bool` | Exports everything recorded so far, waiting up to `timeout_millis`. Whether every destination accepted it. |
| `status()` | `TelemetryStatus` | Approximate, process-wide pipeline counters; see below. |
| `current_span_context()` | `CurrentSpanContext \| None` | The active span's `trace_id`, `span_id`, `trace_flags`, and `traceparent`, or `None` outside a valid span. |
| `release()` | `bool` | Stops serving as the global OpenTelemetry implementation, so a provider set afterwards owns every signal. Elide's runtime instrumentation keeps recording. `False` when already released or never installed. |

```python
class TelemetryStatus(TypedDict):
    active: bool
    released: bool
    stepped_aside: list[str]  # "trace", "metrics", "logs"
    spans: SpanCounters  # started, unsampled, ended, live, exported, dropped, table_full, reclaimed,
    #                      handed_off, exit_dropped
    logs: LogCounters  # emitted, filtered, exported, dropped, handed_off, exit_dropped
    metrics: MetricCounters  # handed_off, exit_dropped
    export_failures: int
    exports_abandoned: int

class CurrentSpanContext(TypedDict):
    trace_id: str
    span_id: str
    trace_flags: int
    traceparent: str
```

## Limits

- Requests served by Elide do not set the Python `contextvars` context; spans parent to the request through Elide
  instead, as described in [Traces](#traces).
- Python HTTP clients do not get client spans or `traceparent`; inject it with
  `opentelemetry.propagate.inject(headers)`.

## Samples

- [Python span and logging](https://elide.help/docs/code-samples#python-span-and-logging)

---

# Emitted telemetry

URL: https://elide.help/docs/opentelemetry/reference

> Every span, metric, log record, and resource attribute Elide emits on its own: names, instrumentation scopes, units, attributes, and when each is recorded.

What Elide records without code changes, once a destination is configured. Telemetry your code creates keeps the
names and scopes you give it.

## Resource

Every span, metric, log record, and profile from one process carries the same resource.

| Attribute | Value |
| --- | --- |
| `service.name` | `OTEL_SERVICE_NAME`, else `service.name` in `elide.pkl`, else `unknown_service:elide` |
| `service.version` | `service.version` |
| `service.namespace` | `service.namespace` |
| `deployment.environment.name` | `service.environment` |
| `telemetry.sdk.name` | `elide` |
| `telemetry.sdk.version` | The Elide version |
| any | `resource` in `elide.pkl` and `OTEL_RESOURCE_ATTRIBUTES` |

When the same attribute is set in more than one place, flags win over variables, and variables over `elide.pkl`.

## Instrumentation scopes

| Scope | Signals |
| --- | --- |
| `dev.elide.runtime` | HTTP server and client spans, `elide build`, `elide test`, and `elide install` spans, runtime metrics, error records, Elide's own log records |
| `dev.elide.runtime.profiler` | Guest CPU profiles |
| `console` | Captured `console.*` output (JavaScript) |
| logger name, e.g. `root`, `app.db` | Captured Python `logging` records |

## Spans

### HTTP server spans

One `SERVER` span per request served by `elide serve`, a `fetch` handler, or a `node:http` server, when
`runtime.traces` is on.

| Field | Value |
| --- | --- |
| Name | The method (`GET`, `POST`, …), or `GET /users/:id` once a `node:http` route is known; `HTTP` for a nonstandard method |
| Parent | The caller's `traceparent`, when valid; otherwise a new trace |
| Status | `ERROR` for a 5xx response, an abandoned response, or a reset connection |

| Attribute | When |
| --- | --- |
| `http.request.method` | Always. Methods outside the standard nine are `_OTHER`. |
| `http.request.method_original` | For `_OTHER` |
| `url.scheme` | Always |
| `url.path` | Always |
| `url.query` | When the target has a query string. The values of `AWSAccessKeyId`, `Signature`, `sig`, `X-Goog-Signature`, `X-Amz-Signature`, `X-Amz-Credential`, and `X-Amz-Security-Token` are redacted; other values are exported as sent, so keep secrets out of URLs. |
| `network.protocol.version` | Always: `1.0`, `1.1`, or `2` |
| `server.address`, `server.port` | From the `Host` header |
| `user_agent.original` | When sent |
| `client.address`, `network.peer.address`, `network.peer.port` | When the peer is known |
| `http.response.status_code` | When a response was sent |
| `http.request.body.size`, `http.response.body.size` | When nonzero or known |
| `http.route` | `node:http` servers, when set by the handler or a router; see [Routes](https://elide.help/docs/opentelemetry/runtime#routes) |
| `error.type` | `abandoned`, `reset`, or the 5xx status code |
| `baggage.<key>` | For keys listed in `propagation.baggage.spanAttributes` |

A handler that throws adds an `exception` event to the server span and sets its status to `ERROR`.

### HTTP client spans

One `CLIENT` span per outgoing `fetch` request, when `runtime.traces` is on.

| Field | Value |
| --- | --- |
| Name | The method: `GET`, `POST`, … |
| Parent | The span active where `fetch` was called |
| Status | `ERROR` for a 4xx or 5xx response, or a failed request |

| Attribute | When |
| --- | --- |
| `http.request.method`, `http.request.method_original` | As for server spans |
| `url.full` | Always |
| `server.address`, `server.port` | From the URL |
| `http.response.status_code` | When a response arrived |
| `network.protocol.version` | When known |
| `http.response.body.size` | When known |
| `error.type` | The 4xx or 5xx status code, or the failure kind |

### Toolchain

Recorded by `elide build`, `elide test`, and `elide install`. The root span continues
a `TRACEPARENT` (and `TRACESTATE`) from the environment.

| Span | Parent | Attributes |
| --- | --- | --- |
| `elide.build`, `elide.test`, `elide.install` | `TRACEPARENT`, or a new trace | `elide.command`, `process.exit.code`, `elide.ci.*`; `ERROR` status for a nonzero exit code |
| `elide.build.<stage>` | Command span | `elide.build.category` |
| `elide.task <name>` | Command span | `elide.build.category`, `elide.build.task`, `elide.build.outcome`, `elide.build.cache_hit` |
| `elide.task.<operation>` | Task span | same as tasks |
| `elide.test.file <path>`, `elide.test.fork <source-set>` | Task span | `elide.test.execution.*`, `elide.test.shard.index/count` for JS files, `elide.test.count.<status>`, `process.exit.code` |
| test name | Execution span (command for records without an execution) | `elide.test.engine`, `elide.test.name`, `elide.test.status`, `elide.test.suite`, `elide.test.file`, `elide.test.source_set`, `elide.test.failure`; `ERROR` status on failure |

Report attributes (schema version 1):

| Attribute | Meaning |
| --- | --- |
| `elide.report.schema_version` | Integer `1` on every report span |
| `elide.invocation.id` | `<trace-id>/<command-span-id>`, shared by all spans in one invocation |
| `elide.span.type` | `command`, `build_stage`, `task`, `task_operation`, `test_execution`, or `test` |
| `elide.project.name`, `elide.workspace.name` | Manifest identities where available; member tasks override project name |
| `elide.task.path`, `elide.task.type` | Workspace-qualified task key and implementation class; type may change across releases |
| `elide.task.dependencies` | Array of scheduled prerequisite task paths; edges are not parent-child span relationships |
| `elide.task.cacheable` | Whether the task permits caching; separate from an actual cache hit |
| `elide.build.workers/peak_ready/ready_wait_ns/critical_path_ns/critical_path` | Command summary: worker count, peak ready tasks, aggregate ready wait, critical-path duration and ordered task paths |
| `elide.build.operation`, `thread.name` | Driver region name and the thread that completed it |
| `elide.test.execution.id/kind/path` | Execution span ID, `file` or `fork`, and project-relative file or source-set name |
| `elide.test.shard.index/count` | Zero-based JS file index and discovered file count; indexes are local to the task |
| `elide.test.count.<status>` | Counts for observed `pass`, `fail`, `skip`, `todo`, `abort`, and `filtered` results; absent means zero |
| `elide.test.id` | Length-prefixed engine, nullable file, nullable source set, suite components, and test name; null encodes as `-1:`, strings as `<UTF-16-length>:<value>` |
| `elide.test.identity.kind` | `display_path`; not a native engine unique ID |
| `elide.test.occurrence` | One-based occurrence of that identity within the execution; not a retry counter |
| `elide.test.timing.kind`, `elide.test.duration_ns` | `result_duration` and the runner's original duration in nanoseconds |

For cross-build test comparison, use repository/service scope, workspace/project, task path, and `elide.test.id`.
For one emitted result, use invocation ID plus execution ID plus test ID plus occurrence (or its OTLP span ID).
Test children carry their execution identity and task path explicitly, so queries do not require walking the tree.
See [Builds and tests in CI](https://elide.help/docs/opentelemetry/runtime#builds-and-tests-in-ci) for timing and completeness limits.

CI attributes come from the provider's own variables:

| Attribute | GitHub Actions | GitLab | Buildkite | CircleCI |
| --- | --- | --- | --- | --- |
| `elide.ci.provider` | `github` | `gitlab` | `buildkite` | `circleci` |
| `elide.ci.pipeline.name` | `GITHUB_WORKFLOW` | `CI_PIPELINE_NAME` | `BUILDKITE_PIPELINE_SLUG` | — |
| `elide.ci.pipeline.run.id` | `GITHUB_RUN_ID` | `CI_PIPELINE_ID` | `BUILDKITE_BUILD_ID` | `CIRCLE_WORKFLOW_ID` |
| `elide.ci.pipeline.run.attempt` | `GITHUB_RUN_ATTEMPT` | — | — | — |
| `elide.ci.pipeline.run.url` | built from `GITHUB_SERVER_URL` | `CI_PIPELINE_URL` | `BUILDKITE_BUILD_URL` | `CIRCLE_BUILD_URL` |
| `elide.ci.job.name` | `GITHUB_JOB` | `CI_JOB_NAME` | `BUILDKITE_LABEL` | `CIRCLE_JOB` |
| `elide.ci.vcs.ref` | `GITHUB_REF_NAME` | `CI_COMMIT_REF_NAME` | `BUILDKITE_BRANCH` | `CIRCLE_BRANCH` |
| `elide.ci.vcs.revision` | `GITHUB_SHA` | `CI_COMMIT_SHA` | `BUILDKITE_COMMIT` | `CIRCLE_SHA1` |
| `elide.ci.vcs.repository` | `GITHUB_REPOSITORY` | `CI_PROJECT_PATH` | — | — |

Any other CI that sets `CI` gets `elide.ci.provider = generic`.

### Span limits

A span still open when the process exits is ended and exported with `elide.span.reclaimed = true`. So is the oldest
open span once more than 16,384 are open at the same time.

## Metrics

Runtime metrics are recorded when `runtime.metrics` is on and some destination accepts metrics.

| Instrument | Kind | Unit | Attributes |
| --- | --- | --- | --- |
| `http.server.request.duration` | Histogram | `s` | `http.request.method`, `url.scheme`, `network.protocol.version`, `http.response.status_code`, `error.type` |
| `http.server.active_requests` | UpDownCounter | `{request}` | `http.request.method`, `url.scheme` |
| `http.server.request.body.size` | Histogram | `By` | Same dimensions as server duration, including a known `http.route` |
| `http.server.response.body.size` | Histogram | `By` | Same dimensions as server duration, including a known `http.route` |
| `elide.http.server.rejected_requests` | Counter | `{request}` | `http.response.status_code` |
| `http.client.request.duration` | Histogram | `s` | `http.request.method`, `server.address`, `server.port`, `url.scheme`, `network.protocol.version`, `http.response.status_code`, `error.type` |
| `process.cpu.time` | Counter (observable) | `s` | `cpu.mode` = `user`, `system` |
| `process.memory.usage` | UpDownCounter (observable) | `By` | — |
| `process.thread.count` | UpDownCounter (observable) | `{thread}` | — |
| `process.unix.file_descriptor.count` | UpDownCounter (observable) | `{file_descriptor}` | — |
| `process.uptime` | Gauge (observable) | `s` | — |
| `elide.errors` | Counter | `{error}` | `error.type`, `elide.error.origin` |

Process metrics are collected on Linux, macOS, and Windows. `elide.http.server.rejected_requests` counts requests Elide
answered itself because they were malformed or unsupported; they never reach your handler.

HTTP duration histograms use the bucket boundaries `0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5,
5, 7.5, 10` seconds and carry exemplars of their request span.

`elide.error.origin` values:

| Value | Recorded for |
| --- | --- |
| `uncaught` | An uncaught exception |
| `rejection` | An unhandled promise rejection |
| `handler` | A request handler that threw or rejected |
| `crash` | A crash of an earlier process, reported by the next one |
| `guest_api` | `span.recordException(…)` in your code |

## Log records

| Record | Scope | Severity | Attributes |
| --- | --- | --- | --- |
| Error | `dev.elide.runtime`; the span's scope for `recordException` | `ERROR` | `event.name = exception`, `exception.type`, `exception.message`, `exception.stacktrace`, `elide.error.origin` |
| Crash report | `dev.elide.runtime` | `FATAL` | as above, plus `elide.crash.origin`, `elide.crash.file`, `elide.crash.signature`, `elide.crash.exit_code`, `elide.crash.subcommand`, `elide.crash.build_id`, `process.pid` |
| Elide's own log | `dev.elide.runtime` | at or above `runtime.logs` | `elide.log.target`, `code.file.path`, `code.line.number` |
| `console.*` | `console` | `console.trace` TRACE, `debug` DEBUG, `log` and `info` INFO, `warn` WARN, `error` and `assert` ERROR | — |
| Python `logging` | the logger's name | mapped from the record level | `code.file.path`, `code.function.name`, `code.line.number`, and `exception.*` with `exc_info` |

Every record emitted inside a span carries its trace id, span id, and trace flags.

## Profiles

Experimental. One OTLP CPU profile per export (every 30 seconds and at exit) in the `dev.elide.runtime.profiler`
scope, with `samples`/`count` values and a `cpu`/`nanoseconds` period. Each sample links to the span that was active
on its thread. See [Profiles](https://elide.help/docs/opentelemetry/signals#profiles).

## Not yet recorded

- Garbage collection and event-loop delay metrics.
- Client spans and `traceparent` injection for `node:http` client requests and Python HTTP clients.
- Spans for engine start, module loading, or worker threads.

---

# OpenTelemetry troubleshooting

URL: https://elide.help/docs/opentelemetry/troubleshooting

> Fix missing or rejected Elide telemetry: check that a destination is configured, read configuration errors, inspect pipeline counters with status(), and see exports in a local collector.

## Nothing arrives

Telemetry runs only when a destination exists. Check, in order:

| Check | How |
| --- | --- |
| A destination is configured | `OTEL_EXPORTER_OTLP_ENDPOINT`, `ELIDE_OTEL_PROVIDER`, `OTEL_TRACES_EXPORTER=otlp`, a `--otel-*` flag, or `destinations` in `elide.pkl` |
| Telemetry is not turned off | No `--no-otel`, `OTEL_SDK_DISABLED=true`, or `enabled = false` |
| The signal is not turned off | No `OTEL_<SIGNAL>_EXPORTER=none`, `traces { enabled = false }`, or `runtime { traces = false }` |
| The provider accepts the signal | See [Providers](https://elide.help/docs/opentelemetry/providers); Datadog sends traces and PostHog sends traces only when listed |
| A one-shot run sees the project | `elide run file.ts` reads `elide.pkl` only when the file contains `opentelemetry` |
| The configuration is accepted | `--verbose` prints why telemetry is not active; see [Configuration errors](#configuration-errors) |
| Your code is active | `active` in [`elide:telemetry`](https://elide.help/docs/opentelemetry/javascript#elidetelemetry) or `active()` in [`elide.telemetry`](https://elide.help/docs/opentelemetry/python#elidetelemetry) |

```ts
// check.ts
import { active, flush, status } from "elide:telemetry";

console.log("active:", active);
console.log("flushed:", await flush());
console.log(status());
```

With nothing listening on the endpoint:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4999 OTEL_EXPORTER_OTLP_TIMEOUT=1000 elide run check.ts
```

```text
active: true
flushed: false
{
  active: true,
  released: false,
  steppedAside: [],
  spans: {
    started: 0,
    unsampled: 0,
    ended: 0,
    live: 0,
    exported: 0,
    dropped: 0,
    tableFull: 0,
    reclaimed: 0,
    handedOff: 0,
    exitDropped: 0
  },
  logs: { emitted: 2, filtered: 0, exported: 0, dropped: 0, handedOff: 0, exitDropped: 0 },
  exportFailures: 1,
  metrics: { handedOff: 0, exitDropped: 0 },
  exportsAbandoned: 0
}
```

`active: false` means no destination was configured. `flushed: false` with `exportFailures` above zero means the
destination could not be reached or rejected the request.

## Configuration errors

A bad value in `elide.pkl` or a flag, a missing credential, or a signal a provider does not accept leaves telemetry
off for the run. The program still runs; `--verbose` prints the reason:

```bash
ELIDE_OTEL_PROVIDER=honeycomb elide run --verbose app.ts   # HONEYCOMB_API_KEY is not set
```

```text
[warn] elide.telemetry Telemetry is not active: telemetry destination 'honeycomb':
environment variable HONEYCOMB_API_KEY is not set
```

The reason names the bad value, missing credential, or unsupported signal. Check, for each
destination:

- its credential variable is set: `SENTRY_DSN`, `DD_API_KEY`, `POSTHOG_PROJECT_TOKEN`, `HONEYCOMB_API_KEY`,
  `GRAFANA_CLOUD_OTLP_CREDENTIAL`, or the variable named by `credential`, `dsn`, or `headerEnv`;
- every signal in `signals` (or `ELIDE_OTEL_SIGNALS`) and its protocol are accepted by the provider;
- `endpoint` starts with `http://` or `https://`, and Grafana has a `region` or `endpoint`;
- `--otel-protocol` is `grpc`, `http/protobuf`, or `http/json`.

A bad environment variable value, such as `OTEL_TRACES_SAMPLER=bogus`, is ignored, and the setting keeps its
`elide.pkl` or default value.

## A provider rejects data

- Check that the credential variable is set in the environment Elide runs in, and holds the full value: a Sentry DSN,
  a Grafana `<instance id>:<token>` pair.
- Check the site or region: a Datadog key only works on its own site, and Honeycomb and PostHog EU accounts need
  `region = "eu"`.
- Check the protocol: Sentry, PostHog, and Grafana take `http/protobuf` only.

Rejected or failed exports are retried with backoff on 429, 502, 503, and 504 responses and on connection errors, up
to the destination's `timeout` (10 seconds by default), then dropped and counted in `exportFailures`.

## Data stops under load

Recording never waits on export. When a destination queue is full, spans and log records are dropped and counted:
`status().spans.dropped`, `status().logs.dropped`. Reduce volume with a sampler
(`traces { sampler = "parentbased_traceidratio"; ratio = 0.1 }`) or a higher `logs.level`, or point Elide at a
nearby collector.

`spans.tableFull` counts spans started while more than 8,192 were open, and `spans.reclaimed` counts spans Elide ended
for you, marked `elide.span.reclaimed`; both usually mean spans that are never ended.

## Short scripts lose data

At exit Elide hands what is pending to a background exporter (see [At exit](https://elide.help/docs/opentelemetry/configuration#at-exit)),
which keeps retrying after the program has ended. Data arrives a moment after exit, not before it. If it never
arrives:

- `ELIDE_OTEL_SIDECAR_LOG=/tmp/elide-otel.log` makes the exporter write what it does, without headers or bodies.
- The exporter gives up on a request after two minutes. Point Elide at a collector it can reach.
- `elide run --otel-shutdown=inline` sends from the exiting process instead, for up to `shutdownTimeout`, and prints
  `Telemetry shutdown failed` when that runs out. Raise it for a slow destination, or call `flush()` before the
  script ends:

```pkl
opentelemetry {
  shutdownTimeout = 15.s
}
```

## An SDK took over

`An OpenTelemetry SDK registered its own tracer provider; Elide's JavaScript tracer provider steps aside` means your
application registered an OpenTelemetry SDK, which now owns that signal and its exporters. `status().steppedAside`
lists the signals it took. Remove the SDK to use Elide's export, or call `release()` before the SDK starts to silence
the warning. See [Using an OpenTelemetry SDK](https://elide.help/docs/opentelemetry/javascript#using-an-opentelemetry-sdk).

## See what Elide sends

Run an OpenTelemetry Collector that prints every request:

```bash
docker run --rm -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:0.115.1
```

Or [otel-desktop-viewer](https://github.com/CtrlSpice/otel-desktop-viewer), which shows traces, metrics, and logs in a
browser. Point `OTEL_EXPORTER_OTLP_ENDPOINT` at either.

---

# Agentic engineering

URL: https://elide.help/docs/agentic-engineering

> Use Elide from a coding agent: the project MCP server over stdio, the public docs MCP server, evidence commands in the binary, and reporting problems from your editor.

A coding agent works with Elide through two MCP servers: `elide mcp` inside your project, and the public docs server
at `https://elide.help/mcp`.

1. Your editor or coding agent connects to two MCP servers.
2. `elide mcp` runs inside your project over stdio: build, run and trace tools, plus the evidence commands
   `elide agent diagnostics`, `elide agent perf` and `elide agent bug`.
3. `https://elide.help/mcp` is public, over Streamable HTTP: docs search, pages, samples, comparisons, benchmarks and
   the report tools.
4. Evidence from the binary reaches a report only when the agent pastes it in. Elide never sends it.

## The two servers

| | Project MCP server | Docs MCP server |
| --- | --- | --- |
| Endpoint | `elide mcp` | `https://elide.help/mcp` |
| Transport | stdio | Streamable HTTP |
| Runs | On your machine, in the project | Hosted; public, no authentication |
| Tools | Build, run, trace, any `elide` command | Search, pages, samples, comparisons, benchmarks, reports |
| Details | [Project MCP server](https://elide.help/docs/mcp) | [Docs MCP server](https://elide.help/docs/mcp-docs) |

## Connect both

```json
{
  "mcpServers": {
    "elide": { "command": "elide", "args": ["mcp"] },
    "elide-docs": { "type": "http", "url": "https://elide.help/mcp" }
  }
}
```

Claude Code:

```bash
claude mcp add elide -- elide mcp
claude mcp add --transport http elide-docs https://elide.help/mcp
```

## Evidence from the binary

| Command | Prints |
| --- | --- |
| `elide agent diagnostics --json` | Version, platform and crash-report directory |
| `elide agent perf --json -- <command>` | Timings for a command, against another runtime or Elide version |
| `elide agent bug --kind <kind> --json` | An `elide.report/1` skeleton for `bug`, `perf`, `expectation` or `feature` |

These commands work offline and send nothing. The agent pastes their output into a report.

## Report from your editor

While you work, the docs server asks your agent to notice failures, slow runs, surprises and missing features, and to
offer to report them. Nothing is sent until you confirm. Accepted reports become public issues in
[elide-dev/elide](https://github.com/elide-dev/elide/issues).

- [Report a problem](https://elide.help/docs/agentic-reporting): kinds, consent, evidence and what is stored.
- [From report to fix](https://elide.help/docs/agentic-triage): triage, issues and status.
- [For AI agents](https://elide.help/docs/agents): non-interactive flags, exit codes and commands that need a terminal.

---

# Project MCP server

URL: https://elide.help/docs/mcp

> Run `elide mcp` over stdio to give AI agents tools to build projects, run files and snippets, and trace programs inside a project over the Model Context Protocol.

`elide mcp` gives AI agents tools to build projects, run code and trace programs inside a project, over stdio.

```bash
elide mcp
elide mcp --project PATH
```

Start it in a project directory, or pass `--project PATH`. To search these docs and report problems, connect the
[docs MCP server](https://elide.help/docs/mcp-docs) too.

## Configure a client

```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. |

## HTTP mode

`elide mcp --mode http` (default address `localhost:8125`) serves the legacy HTTP+SSE transport, not Streamable HTTP,
with a token from `ELIDE_MCP_TOKEN` (random if unset). Prefer stdio.

---

# Docs MCP server

URL: https://elide.help/docs/mcp-docs

> Connect an agent to https://elide.help/mcp: search the docs, read pages, find samples, compare runtimes, read benchmarks, and report problems. Public, no authentication, Streamable HTTP.

`https://elide.help/mcp` serves these docs over the Model Context Protocol and accepts problem reports. It is public,
needs no authentication, and uses the Streamable HTTP transport.

## Connect

```json
{
  "mcpServers": {
    "elide-docs": { "type": "http", "url": "https://elide.help/mcp" }
  }
}
```

Claude Code:

```bash
claude mcp add --transport http elide-docs https://elide.help/mcp
```

To build and run code in a project, also connect the [project MCP server](https://elide.help/docs/mcp).

## Reading tools

| Tool | Does |
| --- | --- |
| `search_docs` | Search pages, sections, code samples, release notes and documented gaps. |
| `get_page` | Return one page as Markdown, by slug, path or URL. |
| `list_pages` | List pages with slugs and descriptions, optionally for one section. |
| `find_samples` | Find runnable code samples by query, language, tag or level. |
| `compare_runtimes` | Compare Elide with Node, Bun, Deno, CPython, Java or Kotlin, with a source for every claim. |
| `get_benchmarks` | Every published benchmark number with its command, machine and date. |

## Reporting tools

| Tool | Does |
| --- | --- |
| `preview_report` | Read-only. Strips secrets and personal data, checks for duplicates, lists missing evidence, and returns the preview. |
| `submit_report` | Sends a report after the developer confirms. |
| `report_status` | Returns a report's status and, once triaged, its issue. |
| `check_known_issue` | Looks up existing issues for a problem before reporting it. |

[Report a problem](https://elide.help/docs/agentic-reporting) covers kinds, consent and evidence.

## Prompts

| Prompt | Argument | Does |
| --- | --- | --- |
| `compare` | `other` | Compare Elide with another runtime from the Perspectives pages and benchmarks. |
| `migrate` | `from` | Plan a migration to Elide from another runtime or toolchain. |

## Resources

| URI | Contains |
| --- | --- |
| `https://elide.help/docs/{slug}.md` | Any page as Markdown (resource template). |
| `https://elide.help/_agent/benchmarks.json` | Benchmark numbers. |
| `https://elide.help/_agent/comparisons.json` | Runtime comparisons. |
| `https://elide.help/_agent/compatibility.json` | Compatibility results. |

## Rate limits

| Calls | Limit per client IP |
| --- | --- |
| Reading tools, prompts and resources | 120 per minute |
| Reports | 10 per minute, 20 per hour |

Over a limit, the server answers `429` with `Retry-After`.

## Discovery

| Resource | URL |
| --- | --- |
| Server card | `https://elide.help/.well-known/mcp/server-card.json` |
| Agent reference | [/developers](https://elide.help/developers) |
| Documentation index | [/llms.txt](https://elide.help/llms.txt) |

---

# Elide for AI Agents

URL: https://elide.help/docs/agents

> Run Elide non-interactively from an AI agent or CI: environment variables, timeouts, exit codes, commands that need a terminal, and collecting 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 <command>
```

`--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 <file>`, `elide python <file>`, or an inline `-s` snippet |
| `elide init` | `elide init --plain --skip-defaults --template <id>`; ids from `elide init --templates --json` |
| `elide adopt` | `elide adopt --non-interactive --build <strategy> --harness <harness> --approval <mode>` |
| `elide serve`, `elide dev` | Add `--no-tui`. |
| `elide help` | `elide help <topic> --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 <file>` | Run a program; script arguments follow `--`. |
| `elide python <file>` | Run with Python-style arguments. |
| `elide build --inspect` | List project task names. |
| `elide test <path>` | Run tests; raise `--concurrency` to parallelize. |
| `elide project export` | Print the manifest as JSON; `--format=pom` or `--format=intellij` for other tools. |
| `elide classpath <sourceSet>:<usage>` | 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 <path>` | 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 <script>` resolves `<script>` in this order:

1. An inline snippet, when `-s`, `--snippet` or `--code` is present.
2. A **file** that exists. `.java` and `.kt` compile first.
3. A **named script**: `scripts` in `elide.pkl`, a `package.json` script, a `pyproject.toml` entry point, then a
   `node_modules/.bin` binary.
4. For a bare `elide run`: `entrypoint` from `elide.pkl`, then `jvm.main`.

Anything else exits `2` and lists every location searched.

## More documentation

`elide agent help <topic>` prints a page by slug, title, or command name; an approximate match prints the closest
page and exits `1`. `elide help --format=markdown` lists every page. The same pages are at https://elide.help.
Agentic engineering (https://elide.help/docs/agentic-engineering) covers both MCP servers and reporting.

## Diagnostics and bug reports

`elide agent diagnostics --json` reports the version, platform, and crash-report directory (`crash_root`).
`elide agent bug` prints a report body and issue URL; it submits nothing. `--kind bug|perf|expectation|feature --json`
prints an `elide.report/1` skeleton instead.
`elide agent perf [--runs 10] [--warmup 3] [--baseline "<command>"] [--against <version>] [--json] -- <command>` times a
command locally; `--baseline` measures another command the same way and `--against` an installed Elide version. It
never downloads. For servers, measure with `wrk` or `oha`.

The docs MCP server at https://elide.help/mcp searches the documentation and samples, and accepts these reports: bugs,
slow runs, missed expectations, and missing features. For immediate help, ask on Discord at https://elide.dev/discord.

---

# Report a problem

URL: https://elide.help/docs/agentic-reporting

> Report a bug, a slow run, a missed expectation or a missing feature from your editor through the docs MCP server: kinds, one-step consent, evidence from elide agent, and what is stored.

Your coding agent can report a problem to Elide through the [docs MCP server](https://elide.help/docs/mcp-docs). Nothing is sent until you
confirm.

## Kinds

| Kind | Use for | Evidence |
| --- | --- | --- |
| `bug` | Elide fails, crashes or gives a wrong result. | The command, its output, `elide agent diagnostics --json` |
| `perf` | Elide is slower than another runtime or an earlier Elide. | `elide agent perf --json` |
| `expectation` | "I expected Elide to do Y for X; it did Z." | The basis: a docs page or another runtime's behavior |
| `feature` | Elide lacks something you need. | What you would use it for |

The server's instructions ask your agent to notice these during normal work and offer to report them.

## Steps

1. `check_known_issue` looks for an existing issue.
2. `preview_report` strips secrets and personal data, checks for duplicates, lists missing evidence, and returns the
   preview with a confirm token. It sends nothing.
3. You confirm once.
4. `submit_report` sends the report and returns its id.
5. `report_status` tracks it; see [From report to fix](https://elide.help/docs/agentic-triage).

## Consent

| Client | What you see |
| --- | --- |
| Supports MCP elicitation | A one-click form, "Send this report to Elide", with an optional GitHub username for credit. |
| Other clients | The agent must show you the preview; your yes releases a confirm token that `submit_report` requires. |
| Headless runs (`claude -p`, `codex exec`) | These declare elicitation but answer the form themselves, so the agent shows you the preview and sends `preview_report`'s confirm token after your yes. |

A confirm token is valid for 15 minutes and only for the exact report previewed. Rate limits and quotas apply either
way.

Every confirmation also links Elide's Discord, https://elide.dev/discord, with a live count of members online.

## Evidence

A report needs only a kind, a title and a summary. Everything else is requested, not required: `preview_report` lists
what would help, and a report without it is still filed, marked as needing evidence. A problem with no working Elide
binary, such as a failed install, can still be reported. A submission that does not match `elide.report/1` at all is
accepted too: the parts that fit are kept, the title and summary are written from what was sent when needed, and the
original is attached to the issue.

The binary prints evidence and sends nothing. The agent pastes it into the report.

```bash
elide agent diagnostics --json
elide agent perf --json --baseline "node app.ts" -- elide run app.ts
elide agent perf --json --against 1.5.4 -- elide run app.ts
elide agent bug --kind expectation --json
```

1. `elide agent perf --json --baseline "node app.ts" -- elide run app.ts` prints an `elide.report/1` document.
2. Its `elide` block fills the report's version and platform, `context.command` the measured command, and `perf` the
   timings, baseline, ratio and machine.
3. The agent writes `title`, `summary` and `repro`, and submits with kind `perf`.

### `elide agent perf`

```bash
elide agent perf [--runs 10] [--warmup 3] [--baseline "<command>"] [--against <version>] [--json] -- <command>
```

| Flag | Default | Does |
| --- | --- | --- |
| `--runs N` | `10` | Measured runs. |
| `--warmup N` | `3` | Unmeasured runs before measuring. |
| `--baseline "<command>"` | none | Measures another command, such as another runtime, the same way. |
| `--against <version>` | none | Runs the same `elide` command with an installed Elide version. It never downloads. |
| `--json` | off | Prints an `elide.report/1` document instead of a table. |

`--baseline` and `--against` are exclusive. Times are in milliseconds; `ratio` is the Elide mean divided by the baseline
mean. On Linux, peak memory (`max_rss_mb`) never reads below the measuring `elide` process's own. For servers, measure
with a load generator such as `wrk` or `oha`.

### `elide agent bug`

`elide agent bug --kind bug|perf|expectation|feature --json` prints an `elide.report/1` skeleton: the Elide version and
platform filled, with empty `title`, `summary` and `repro` for the agent. `perf` adds a `perf` block and `expectation` an
`expectation` block with `expected`, `actual` and `basis`. Without `--json`, it prints a Markdown issue body.

## What is stored

| Data | Handling |
| --- | --- |
| Home directory paths | Replaced before storing |
| Tokens and keys | Removed before storing |
| Email addresses | Removed before storing |
| Your IP address | Stored only as a hash with a daily salt |
| GitHub username | Stored only if you give one, for credit |
| The report | Kept indefinitely |

Without an MCP client, file an issue at [elide-dev/elide](https://github.com/elide-dev/elide/issues) with the output of
`elide agent bug`.

---

# From report to fix

URL: https://elide.help/docs/agentic-triage

> What happens to a report sent from your editor: the hourly triage, public issues in elide-dev/elide, +1s on duplicates, draft benchmark cases, and tracking with report_status.

An accepted report becomes a public issue in [elide-dev/elide](https://github.com/elide-dev/elide/issues), usually
within the hour.

1. The agent calls `preview_report`: secrets and personal data are stripped, duplicates checked, and a preview
   returned. Nothing is sent.
2. You confirm, and `submit_report` puts the report in the queue.
3. An hourly triage job reads the queue.
4. Each report becomes a public issue, a +1 on an existing issue, a draft benchmark case, a docs fix, or goes to human
   review.
5. `report_status` reads the status back to the agent.

## Outcomes

| Outcome | When |
| --- | --- |
| New public issue | The report is new. Labels: `intake` and `kind:<kind>`. |
| +1 on an existing issue | The problem is already reported. |
| Draft benchmark case | A `perf` report includes a repro. |
| Docs fix | The docs were wrong or missing. |
| Human review | Triage can't decide. |

## Track a report

Call `report_status` with the id `submit_report` returned. It reports the state and, once triaged, the issue URL.

Follow issues with the `intake` label at
[elide-dev/elide](https://github.com/elide-dev/elide/issues?q=label%3Aintake). For immediate help, ask on Discord at
https://elide.dev/discord.

---

# API overview

URL: https://elide.help/docs/api-overview

> Every built-in module and global in Elide: Node modules and where each is documented, the `elide:` modules, the Python `elide` module, the `Elide` global and Web globals.

JavaScript code gets the [`Elide` global](https://elide.help/docs/api-globals-elide), Node built-in modules, `elide:` database modules,
and Web globals. Suite results are in the [Compatibility Matrix](https://elide.help/docs/compatibility). Java and Kotlin programs: see
[JVM APIs](https://elide.help/docs/api-jvm).

## Built-in modules

Node modules resolve with or without the `node:` prefix. Each page links the upstream documentation, lists
differences, and ends with a generated reference: exports, anything not implemented, and suite results.

<!-- api-reference:start 904a1b23b589 -->
| Module | Page | Status | Suite |
| --- | --- | --- | --- |
| `assert`, `assert/strict` | [node:assert](https://elide.help/docs/api-node-assert) | Partial | 53.8% of 13 |
| `async_hooks` | [node:async_hooks](https://elide.help/docs/api-node-async-hooks) | Partial | 80.0% of 45 |
| `buffer` | [node:buffer](https://elide.help/docs/api-node-buffer) | Full | 90.3% of 62 |
| `child_process` | [node:child_process](https://elide.help/docs/api-node-child-process) | Full | Not measured |
| `console` | [node:console](https://elide.help/docs/api-node-console) | Partial | 95.2% of 21 |
| `crypto` | [node:crypto](https://elide.help/docs/api-node-crypto) | Partial | 84.8% of 112 |
| `dgram` | [node:dgram](https://elide.help/docs/api-node-dgram) | Full | Not measured |
| `diagnostics_channel` | [node:diagnostics_channel](https://elide.help/docs/api-node-diagnostics-channel) | Full | 62.7% of 67 |
| `dns`, `dns/promises` | [node:dns](https://elide.help/docs/api-node-dns) | Full | 85.0% of 20 |
| `domain` | [node:domain](https://elide.help/docs/api-node-domain) | Full | Not measured |
| `events` | [node:events](https://elide.help/docs/api-node-events) | Full | 89.5% of 38 |
| `fs`, `fs/promises` | [node:fs](https://elide.help/docs/api-node-fs) | Partial | 93.2% of 264 |
| `http`, `https` | [node:http](https://elide.help/docs/api-node-http) | Partial | Not measured |
| `module` | [node:module](https://elide.help/docs/api-node-module) | Partial | 86.5% of 52 |
| `net` | [node:net](https://elide.help/docs/api-node-net) | Partial | Not measured |
| `os` | [node:os](https://elide.help/docs/api-node-os) | Full | Not measured |
| `path`, `path/posix`, `path/win32` | [node:path](https://elide.help/docs/api-node-path) | Full | 100.0% of 16 |
| `perf_hooks` | [node:perf_hooks](https://elide.help/docs/api-node-perf-hooks) | Partial | Not measured |
| `querystring` | [node:querystring](https://elide.help/docs/api-node-querystring) | Full | Not measured |
| `stream`, `stream/promises`, `stream/web`, `stream/consumers`, `stream/iter` | [node:stream](https://elide.help/docs/api-node-stream) | Partial | 90.3% of 238 |
| `test` | [node:test](https://elide.help/docs/api-node-test) | Partial | Not measured |
| `timers`, `timers/promises` | [node:timers](https://elide.help/docs/api-node-timers) | Full | 94.7% of 57 |
| `url` | [node:url](https://elide.help/docs/api-node-url) | Full | 95.2% of 42 |
| `util`, `util/types` | [node:util](https://elide.help/docs/api-node-util) | Partial | 50.0% of 18 |
| `v8` | [node:v8](https://elide.help/docs/api-node-v8) | Partial | Not measured |
| `vm` | [node:vm](https://elide.help/docs/api-node-vm) | Full | 84.2% of 95 |
| `worker_threads` | [node:worker_threads](https://elide.help/docs/api-node-worker-threads) | Partial | 82.0% of 128 |
| `zlib`, `zlib/iter` | [node:zlib](https://elide.help/docs/api-node-zlib) | Partial | Not measured |
| `process` | [process](https://elide.help/docs/api-globals-process) | Partial | 88.5% of 87 |

## Web globals

| Globals | Page | Status | Suite |
| --- | --- | --- | --- |
| `fetch`, `Headers`, `Request`, `Response` and 3 more | [Fetch](https://elide.help/docs/api-whatwg-fetch) | Full | 57.9% of 2,511 |
| `ReadableStream`, `ReadableStreamDefaultReader`, `ReadableStreamDefaultController`, `ReadableStreamBYOBReader` and 9 more | [Streams](https://elide.help/docs/api-whatwg-streams) | Full | Not measured |
| `CompressionStream`, `DecompressionStream` | [Compression streams](https://elide.help/docs/api-whatwg-compression) | Full | Not measured |
| `URL`, `URLSearchParams` | [URL](https://elide.help/docs/api-whatwg-url) | Full | 96.0% of 9,046 |
| `URLPattern` | [URLPattern](https://elide.help/docs/api-whatwg-urlpattern) | Full | Not measured |
| `TextEncoderStream`, `TextDecoderStream`, `TextDecoder`, `TextEncoder` | [Encoding](https://elide.help/docs/api-whatwg-encoding) | Full | 99.4% of 14,266 |
| `crypto`, `SubtleCrypto` | [Web Crypto](https://elide.help/docs/api-whatwg-web-crypto) | Full | Not measured |
| `Event`, `CustomEvent`, `EventTarget` | [DOM events](https://elide.help/docs/api-whatwg-dom-events) | Full | Not measured |
| `AbortController`, `AbortSignal` | [DOM abort](https://elide.help/docs/api-whatwg-dom-abort) | Full | Not measured |
| `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` and 2 more | [Timers](https://elide.help/docs/api-html-timers) | Full | Not measured |
| `MessageEvent`, `MessageChannel`, `MessagePort` | [Messaging](https://elide.help/docs/api-wintercg-messaging) | Partial | Not measured |
| `navigator`, `WorkerNavigator` | [WorkerNavigator](https://elide.help/docs/api-wintercg-navigator) | Full | Not measured |
| `performance`, `PerformanceEntry`, `PerformanceMark`, `PerformanceMeasure` and 3 more | [Performance](https://elide.help/docs/api-wintercg-performance) | Full | Not measured |
| `DOMException`, `PromiseRejectionEvent` | [Other globals](https://elide.help/docs/api-web-misc-globals) | Full | Not measured |
<!-- api-reference:end -->

## Other built-in modules

| Module | Status |
| --- | --- |
| `cluster` | Unavailable |
| `constants` | Unavailable |
| `http2` | Unavailable |
| `inspector` | Unavailable |
| `punycode` | `encode`, `decode`, `toASCII` and `toUnicode` |
| `readline`, `readline/promises` | Line iteration, `question()` and the cursor and key-press helpers |
| `repl` | Unavailable |
| `sea` | Unavailable |
| `sqlite` | [SQLite](https://elide.help/docs/api-sqlite) |
| `string_decoder` | `StringDecoder`, including split multi-byte and base64 input |
| `sys` | Loads; the same object as `util` |
| `test/reporters` | Unavailable |
| `tls` | Client connections with `tls.connect`; `createServer` throws and `rootCertificates` is empty |
| `trace_events` | Unavailable |
| `tty` | `isatty`, `ReadStream` and `WriteStream` |
| `wasi` | Unavailable |

Importing an unavailable module throws `ERR_UNKNOWN_BUILTIN_MODULE`.

### `elide:` aliases

`elide:X` returns the same module object as `node:X`. There is no `elide:compression`; use `node:zlib` or
`CompressionStream`.

## Elide modules

| Module | Exports | Page |
| --- | --- | --- |
| `elide:sqlite`, `elide:postgres`, `elide:mysql` | `Database` | [Databases](https://elide.help/docs/api-database) |
| `elide:cel` | `compile` | [CEL module](https://elide.help/docs/api-cel) |
| `elide:telemetry` | `flush`, `status`, `enter`, `wrapTracer`, `release` | [`elide:telemetry`](https://elide.help/docs/opentelemetry/javascript#elidetelemetry) |

Python code gets the [`elide` module](https://elide.help/docs/api-python-elide) for calling JavaScript and sharing functions.

## Telemetry

| Module | Page |
| --- | --- |
| `@opentelemetry/api`, `@opentelemetry/api-logs`, `@opentelemetry/api/experimental` | Built in when not installed; [OpenTelemetry in JavaScript](https://elide.help/docs/opentelemetry/javascript) |
| `elide:telemetry` | `flush`, `status`, `enter`, `wrapTracer`, `release`; [`elide:telemetry`](https://elide.help/docs/opentelemetry/javascript#elidetelemetry) |
| Python `opentelemetry`, `elide.telemetry` | [OpenTelemetry in Python](https://elide.help/docs/opentelemetry/python) |

---

# JavaScript language

URL: https://elide.help/docs/javascript-language

> Which ECMAScript edition and proposals Elide runs (Temporal, ShadowRealm, AsyncContext, `using`, Float16Array), and the non-standard globals `print`, `printErr`, `gc`, `Operators`, `Process` and `XMLHttpRequest`.

Elide runs ECMAScript 2025 and the newer features below, with no flag. The project's
[`javascript.ecma`](https://elide.help/docs/elide-pkl-reference#javascript) setting is informational and does not change them.

## Language features

| Feature | Status |
| --- | --- |
| ECMAScript 2025: iterator helpers, `Set` methods, `Promise.try`, `RegExp.escape`, import attributes, regexp modifiers, duplicate named groups | Supported |
| `using`, `await using`, `DisposableStack`, `AsyncDisposableStack` | Supported |
| `Float16Array`, `Math.f16round` | Supported |
| `Temporal` | Supported |
| `ShadowRealm` | Supported |
| `AsyncContext.Variable`, `AsyncContext.Snapshot` | Supported; values follow `await`, `.then()`, timers, `setImmediate`, `process.nextTick` and `queueMicrotask` |
| `Error.isError`, `Math.sumPrecise`, `Iterator.concat`, `Map.prototype.getOrInsert` | Supported |
| `Uint8Array.fromBase64`, `toBase64`, `fromHex`, `toHex` | Supported |
| JSON.parse source text access (`context.source` in the reviver) | Supported |
| Decorators | Standard decorators; see [TypeScript and modules](https://elide.help/docs/typescript-and-modules#typescript-syntax) |
| `Intl` | Supported |

```js
// modern.mjs
{
  using file = { [Symbol.dispose]() { console.log("closed"); } };
  console.log("open");
}

const due = Temporal.PlainDate.from("2026-10-11").add({ days: 30 });
console.log(due.toString(), due.dayOfWeek);

const request = new AsyncContext.Variable();
await request.run("req-1", async () => {
  await null;
  console.log("request", request.get());
});

const realm = new ShadowRealm();
console.log(realm.evaluate("typeof process"));

console.log(new Float16Array([1.337])[0]);
console.log([1, 2, 3].values().map((x) => x * 2).toArray().join());
```

```bash
elide modern.mjs
```

```text
open
closed
2026-11-10 2
request req-1
undefined
1.3369140625
2,4,6
```

A `ShadowRealm` has the ECMAScript built-ins, `console` and `require`, but no `process`, `fetch` or `Buffer`.

## Non-standard globals

| Global | Behavior |
| --- | --- |
| `print(...values)` | Writes the values to stdout, separated by spaces. Objects print as `[object Object]`. |
| `printErr(...values)` | The same, to stderr. |
| `gc()` | Defined only when the program receives `--expose-gc`: `elide app.mjs -- --expose-gc`. Requests a garbage collection. |
| `Operators(table)` | Operator overloading: returns a base class whose subclasses use the functions in `table` for `+`, `-`, `<` and the other operators. |
| `Process` | The class of `process`; `new Process()` throws `TypeError: Creating Process instances is not allowed`. |
| `XMLHttpRequest` | Not supported. The constructor exists, but every request fails: `onerror` fires and `status` is `0`. Use `fetch`. |

```js
const Vector = Operators({ "+"(a, b) { return new Vec(a.x + b.x); } });
class Vec extends Vector {
  constructor(x) { super(); this.x = x; }
}
console.log((new Vec(1) + new Vec(2)).x); // 3
```

## Samples

- [Dates with Temporal](https://elide.help/docs/code-samples#dates-with-temporal)

## See also

- [TypeScript and modules](https://elide.help/docs/typescript-and-modules)
- [API overview](https://elide.help/docs/api-overview)
- [Compatibility matrix](https://elide.help/docs/compatibility)

---

# Elide global

URL: https://elide.help/docs/api-globals-elide

> The `Elide` global: version and build metadata, `Elide.serve()` options and defaults (bind address, port, TLS, body limits, timeouts), and serving a module's default-exported fetch handler.

`Elide` is a global with build metadata and the `serve()` HTTP entry point.

| Property | Type |
|---|---|
| `version` | `string` |
| `debug` | `boolean` |
| `release` | `boolean` |
| `buildMode` | `string` |
| `targetArchitecture` | `string` |

## `Elide.serve(options)`

`Elide.serve` takes a Fetch-style handler and returns an object with `port`, `hostname`, and `close()`:

```js
const server = Elide.serve({
  port: 3000,
  hostname: "127.0.0.1",
  fetch(request) {
    return new Response("hello");
  },
});
```

| Option | Default | Effect |
|---|---|---|
| `fetch` | required | Handler: receives a `Request`, returns a `Response` or a Promise of one. |
| `hostname` | all interfaces (`0.0.0.0`) | Interface to bind. |
| `port` | `0` | TCP port; `0` picks a free port, read it from `server.port`. |
| `cert`, `key` | none | PEM certificate and private key; with both set the server speaks HTTPS. |
| `idleTimeoutMs` | `30000` | Time allowed to read a request body; a stalled body gets `408`. `0` disables it. |
| `maxBodyBytes` | `104857600` (100 MiB) | Larger request bodies get `413 Payload Too Large`. `0` removes the cap. |

Without `hostname`, the server listens on every network interface and is reachable from other machines. Pass
`hostname: "127.0.0.1"` to accept local connections only:

```js
const open = Elide.serve({ fetch: () => new Response("ok") });
console.log(open.hostname, open.port);
open.close();

const local = Elide.serve({ hostname: "127.0.0.1", fetch: () => new Response("ok") });
console.log(local.hostname, local.port);
local.close();
```

```terminaloutput
0.0.0.0 36518
127.0.0.1 38424
```

- `elide run` does not exit until `close()` is called.
- Connections are accepted once the entry module, including top-level `await`, has finished. A request made from
  top-level code to the module's own server waits forever; make it from a callback such as `setTimeout`.
- It serves HTTP/1.1, and HTTP/2 over TLS.
- Request and response bodies stream; return a `Response` backed by a `ReadableStream` to stream output.
- `request.signal` aborts when the client disconnects.
- Responses are sent as returned and never recompressed; set `Content-Encoding` and `Vary: Accept-Encoding` yourself.

### HTTPS

```js
import { readFileSync } from "node:fs";

const server = Elide.serve({
  hostname: "127.0.0.1",
  port: 8443,
  cert: readFileSync("cert.pem", "utf8"),
  key: readFileSync("key.pem", "utf8"),
  fetch: (request) => new Response(`hello over ${new URL(request.url).protocol}\n`),
});
```

```bash
curl -sk https://127.0.0.1:8443/
```

```terminaloutput
hello over https:
```

### Request limits

```js
const server = Elide.serve({
  hostname: "127.0.0.1",
  port: 0,
  maxBodyBytes: 1024,
  async fetch(request) {
    const body = await request.text();
    return new Response(`received ${body.length} bytes\n`);
  },
});

setTimeout(async () => {
  for (const size of [512, 4096]) {
    const res = await fetch(`http://127.0.0.1:${server.port}/`, { method: "POST", body: "x".repeat(size) });
    console.log(size, res.status, (await res.text()).trim());
  }
  server.close();
}, 0);
```

```terminaloutput
512 200 received 512 bytes
4096 413 Payload Too Large
```

## Exported fetch handler

An entry ES module can default-export an object with a `fetch(request)` method instead:

```js
export default {
  hostname: "127.0.0.1",
  port: 3000,
  fetch(request) {
    return new Response(new URL(request.url).pathname);
  },
};
```

- `elide run`, `elide serve`, and `elide dev` start it after the module, including top-level `await`, finishes.
- Imported modules never start a server.
- `fetch` is called with the exported object as `this` and returns a `Response` or a Promise of one.
- `run` binds the exported `hostname` and `port`, default `127.0.0.1:8080`; `--host` and `--port` override them in
  `serve` and `dev`.

## Samples

- [Server-sent events](https://elide.help/docs/code-samples#server-sent-events)
- [Request limits](https://elide.help/docs/code-samples#request-limits)
- [Multi-context server](https://elide.help/docs/code-samples#multi-context-server)

---

# process

URL: https://elide.help/docs/api-globals-process

> How Elide supports Node's `process` global: the same object as `node:process`, with differences in `resourceUsage`, `send`, stdout and `nextTick` ordering.

`process` is a global; `node:process` and `elide:process` return the same object. It follows
[Node's `process`](https://nodejs.org/api/process.html).

## Example

```js
// process.mjs
process.on("exit", (code) => console.log("exit code", code));

console.log(typeof process.pid, typeof process.env.PATH, process.argv.length >= 2);
console.log(process.memoryUsage().rss > 0, process.hrtime.bigint() > 0n);

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("promise"));
process.nextTick(() => console.log("nextTick"));
process.exitCode = 3;
```

`elide run process.mjs` prints:

```text
number string true
true true
nextTick
promise
timeout
exit code 3
```

The process exits with status 3.

## Differences from Node

- `process.resourceUsage` is not available.
- `process.send` and `process.disconnect` exist only in a child started with `child_process.fork()`.
- Replacing `process.stdout.write` also intercepts `console.log`.
- `process.nextTick` callbacks run before Promise and `queueMicrotask` callbacks; see [Timers](https://elide.help/docs/api-html-timers).

For `process.env` loading and subprocess behavior, see [Environment Variables](https://elide.help/docs/env-variables).

## Samples

- [Command-line arguments](https://elide.help/docs/code-samples#command-line-arguments)

<!-- api-reference:start 7778e4076f00 -->
## Reference

**Status:** Partial · 77 of 87 suite tests pass (88.5%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `process.arch` | property | Full | CPU architecture of the process (e.g. "x64", "arm64") |
| `process.argv` | property | Full | Command-line arguments passed to the process, starting with the node executable path |
| `process.argv0` | property | Full | The original value of argv[0] before any modification by Node.js |
| `process.env` | property | Full | Object containing the process environment variables |
| `process.execArgv` | property | Full | Node.js-specific flags passed to the node executable |
| `process.execPath` | property | Full | Absolute path of the node executable |
| `process.pid` | property | Full | Process ID |
| `process.ppid` | property | Full | Parent process ID |
| `process.platform` | property | Full | Operating system platform (e.g. "linux", "darwin", "win32") |
| `process.title` | property | Full | Displayed process title (settable in most environments) |
| `process.version` | property | Full | Node.js version string (e.g. "v20.0.0") |
| `process.versions` | property | Full | Object mapping dependency names to their version strings |
| `process.abort()` | function | Full | Terminates the process immediately with a core dump (SIGABRT) |
| `process.cwd()` | function | Full | Returns the current working directory of the process |
| `process.chdir()` | function | Full | Changes the current working directory of the process |
| `process.exit()` | function | Full | Terminates the process with the given exit code |
| `process.getuid()` | function | Full | Returns the numeric user ID of the process owner |
| `process.getgid()` | function | Full | Returns the numeric group ID of the process owner |
| `process.geteuid()` | function | Full | Returns the effective numeric user ID |
| `process.getegid()` | function | Full | Returns the effective numeric group ID |
| `process.hrtime()` | function | Full | Returns the current high-resolution time as [seconds, nanoseconds] |
| `process.umask()` | function | Full | Gets or sets the file creation mode mask |
| `process.cpuUsage()` | function | Full | Returns the CPU time used since an optional reference point |
| `process.memoryUsage()` | function | Full | Returns a snapshot of the current process memory usage |
| `process.uptime()` | function | Full | Returns the number of seconds the current process has been running |
| `process.nextTick()` | function | Full | Schedules a callback to run after I/O events but before timers in the current event loop tick |
| `process.stdin` | property | Full | Readable stream connected to stdin |
| `process.stdout` | property | Full | Writable stream connected to stdout |
| `process.stderr` | property | Full | Writable stream connected to stderr |

### Not implemented

`addUncaughtExceptionCaptureCallback`, `debugPort`, `finalization`, `getBuiltinModule`, `report`, `resourceUsage`, `sourceMapsEnabled`.

**Tests:** [node-api `node:process`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 77 pass, 10 fail, 0 error, 6 skipped. Failing: `test-process-dlopen-error-message-crash.js`, `test-process-env-allowed-flags-are-documented.js`, `test-process-env-allowed-flags.js`, `test-process-exec-argv.js`, `test-process-execve-permission-fail.js`, `test-process-exit-code-validation.js`, `test-process-load-env-file.js`, `test-process-remove-all-signal-listeners.js`, and 2 more.
<!-- api-reference:end -->

---

# CEL API Reference

URL: https://elide.help/docs/api-cel

> The elide:cel module: compile and evaluate Common Expression Language expressions.

`elide:cel` compiles and evaluates [CEL](https://cel.dev) expressions using
[TruffleCEL](https://github.com/elide-dev/trufflecel), backed by
[TruffleData](https://github.com/elide-dev/truffledata). Expressions have no side effects and evaluation
is bounded, so they suit user-supplied rules, filters and policies.

```js
import { compile } from "elide:cel";

const rule = compile("user.age >= 18 && 'admin' in user.roles");
rule.variables; // ["user"]
rule.test({ user: { age: 30, roles: ["admin"] } }); // true
compile("xs.filter(x, x % 2 == 0)").evaluate({ xs: [1, 2, 3, 4] }); // [2, 4]
```

- `compile(expression)` parses and type-checks once and returns a reusable program. Free identifiers become
  variables, typed `dyn`. Invalid expressions throw an `Error` with the CEL diagnostic.
- `program.evaluate(variables?)` returns the result; `program.test(variables?)` requires a boolean.
  Evaluation failures throw an `Error`.
- The standard library and macros (`has`, `all`, `exists`, `exists_one`, `map`, `filter`) are available.
  TruffleCEL also includes optional values, two-variable macros, and string, list, math and network
  extensions. See its [extension reference](https://github.com/elide-dev/trufflecel/blob/main/docs/EXTENSIONS.md).

## Values

| JavaScript | CEL |
| --- | --- |
| integral `number`, `bigint` within int64 | `int` |
| other `number` | `double` |
| `string`, `boolean`, `null` | `string`, `bool`, `null` |
| `Uint8Array`, `Buffer` | `bytes` |
| array, plain object | `list`, `map` |

Results convert back the same way. An `int` beyond `Number.MAX_SAFE_INTEGER` returns as a `bigint`; a
timestamp or duration returns as its string form. Comparisons mix `int` and `double` freely, arithmetic
does not: write `double(x) / 2.0` when `x` may be integral.

## Samples

- [Access rules with CEL](https://elide.help/docs/code-samples#access-rules-with-cel)

---

# Python elide module

URL: https://elide.help/docs/api-python-elide

> The Python `elide` module: evaluate JavaScript with `elide.js`, share Python functions with `elide.bind` and `@elide.poly(name=…)`, and reach telemetry controls.

Python code running on Elide can `import elide` without installing anything.

| Name | Effect |
| --- | --- |
| `elide.js(source)` | Evaluates a JavaScript string and returns its value. Needs `--interop`. |
| `elide.bind(fn)` | Shares `fn` under its `__name__`; returns `fn`, so it works as a decorator. |
| `elide.poly(name=…)` | Decorator that shares a function under `name`. |
| `elide.telemetry` | Telemetry controls; see [OpenTelemetry](https://elide.help/docs/opentelemetry/python). |

## `elide.js`

```python
# calls.py
from elide import js

slug = js("(s) => s.trim().toLowerCase().replaceAll(' ', '-')")
print(slug("  Hello Polyglot World "))

point = js("({ x: 1, y: 2, tags: ['a', 'b'] })")
print(point.x + point.y, point.tags[0], len(point.tags))
```

```bash
elide --interop python calls.py
```

```text
hello-polyglot-world
3 a 2
```

JavaScript functions are callable, objects expose their properties as attributes, and `undefined` becomes `None`.
[Build a polyglot app](https://elide.help/docs/polyglot) lists every value conversion.

| Input | Result |
| --- | --- |
| Run without `--interop` | `ValueError: polyglot language 'js' not found` |
| JavaScript that throws or fails to parse | `RuntimeError: JSException: SyntaxError: <elide.js>:1:3 Expected an operand but found eof` |
| A non-string argument | `TypeError: elide.js() argument source must be str, not int` |

## `elide.bind` and `elide.poly`

Both share a Python function by name. Python reads shared values with `polyglot.import_value`, and the
[REPL](https://elide.help/docs/repl) with `/import NAME`.

```python
# shared.py
import polyglot
from elide import bind, poly

@bind
def add(a, b):
    return a + b

@poly(name="greet")
def say_hello(name):
    return f"hello {name}"

print(add(2, 3), say_hello("elide"))
print(polyglot.import_value("add")(2, 3))
print(polyglot.import_value("greet")("elide"))
```

```bash
elide python shared.py
```

```text
5 hello elide
5
hello elide
```

- Both decorators return the original function, so it stays callable from Python.
- `elide.poly(name=1)` raises `TypeError: elide.poly() argument name must be str, not int`.
- JavaScript files have no `Polyglot` global, so they cannot read shared values. To call Python from JavaScript,
  import the `.py` module instead; see [Languages and interop](https://elide.help/docs/languages).

## See also

- [Build a polyglot app](https://elide.help/docs/polyglot)
- [Languages and interop](https://elide.help/docs/languages)
- [Python toolchain](https://elide.help/docs/python-toolchain)

---

# Insight scripts

URL: https://elide.help/docs/api-insight

> The `insight` object available to scripts loaded with Elide's `--insights` flag: the `source`, `enter` and `return` events, their filters, and what each handler receives.

An Insight script runs before the program and subscribes to its execution events. Load one with the repeatable
`--insights <FILE>` option:

```bash
elide run --insights=trace.js app.js
```

```javascript
// trace.js
insight.on("enter", (ctx, frame) => {
  console.log("enter", ctx.name, JSON.stringify(frame));
}, { roots: true, rootNameFilter: "add" });

insight.on("return", (ctx, frame) => {
  console.log("return", ctx.name, ctx.returnValue(frame));
}, { roots: true, rootNameFilter: "add" });
```

For `function add(a, b) { return a + b; }` called as `add(1, 2)`, this prints `enter add {"a":1,"b":2,"this":{}}` and
`return add 3`.

## Events

| Event    | Fires when                          | Handler arguments |
| -------- | ----------------------------------- | ----------------- |
| `source` | a source file is loaded             | `(source)` with `name`, `characters`, `uri` |
| `enter`  | a matching function, statement or expression starts | `(ctx, frame)` |
| `return` | a matching function, statement or expression ends   | `(ctx, frame)` |

`insight.on(event, handler, filter)` registers a handler for the whole run; `insight.off` is not supported.
`insight.id` and `insight.version` identify the API.

## Filters

`enter` and `return` need at least one of `roots`, `statements` or `expressions`.

| Key              | Value                                                   |
| ---------------- | ------------------------------------------------------- |
| `roots`          | `true` to match function entries                        |
| `statements`     | `true` to match each statement                          |
| `expressions`    | `true` to match each expression                         |
| `rootNameFilter` | a regular expression string matched against the function name |
| `sourceFilter`   | a function `(source) => boolean`; also filters `source` events |

## Context and frame

| Member                  | Value                                         |
| ----------------------- | --------------------------------------------- |
| `ctx.name`              | function name                                 |
| `ctx.source.name`       | file name                                     |
| `ctx.line`, `ctx.column` | start position                               |
| `ctx.characters`        | source text of the matched node               |
| `ctx.returnValue(frame)` | value returned (in `return` handlers)        |
| `frame`                 | local variables and `this`, by name           |

For profiling and a guided example, see [Debugging](https://elide.help/docs/debugging).

---

# Databases

URL: https://elide.help/docs/api-database

> The database drivers built into Elide: embedded SQLite, PostgreSQL and MySQL from JavaScript and TypeScript, Python's sqlite3, and JDBC from Java and Kotlin.

Elide includes three database drivers for JavaScript and TypeScript. Import the one you need; there is nothing to
install and no `Elide.db` global.

| Module | Database | API | Placeholders | Page |
| --- | --- | --- | --- | --- |
| `elide:sqlite` | SQLite file or in-memory | Synchronous | `?`, `?1`, `$name` | [SQLite](https://elide.help/docs/api-sqlite) |
| `elide:postgres` | PostgreSQL server | Promises, pooled | `$1` or `?` | [PostgreSQL](https://elide.help/docs/api-postgres) |
| `elide:mysql` | MySQL server | Promises, pooled | `?` | [MySQL](https://elide.help/docs/api-mysql) |

```javascript
import { Database } from "elide:sqlite";

const db = new Database(":memory:");
db.exec("CREATE TABLE notes (body TEXT)");
db.prepare("INSERT INTO notes VALUES (?)").run("hello");
console.log(db.query("SELECT body FROM notes").all());
```

`node:sqlite` and `bun:sqlite` load the same module as `elide:sqlite`; Node's `DatabaseSync` isn't provided (see
[SQLite](https://elide.help/docs/api-sqlite#nodesqlite-and-bunsqlite)). `elide:postgres` and `elide:mysql` ship TypeScript declarations in
`@elide-dev/types`; `elide:sqlite` has none yet (see [TypeScript and modules](https://elide.help/docs/typescript-and-modules)).

## Other languages

| Language | Use |
| --- | --- |
| Python | The standard [`sqlite3`](https://docs.python.org/3/library/sqlite3.html) module, after `elide setup python` |
| Java, Kotlin | JDBC, with the driver as a Maven dependency, such as `org.xerial:sqlite-jdbc` or `org.postgresql:postgresql` |

The JavaScript drivers aren't on a JVM program's classpath: declare the JDBC driver like any other library (see
[Maven dependencies](https://elide.help/docs/toolchain/jvm/maven)).

## Samples

- [Embedded SQLite](https://elide.help/docs/code-samples#embedded-sqlite)
- [SQLite transactions](https://elide.help/docs/code-samples#sqlite-transactions)
- [PostgreSQL queries](https://elide.help/docs/code-samples#postgresql-queries)

---

# SQLite

URL: https://elide.help/docs/api-sqlite

> Embedded SQLite from JavaScript and TypeScript with `elide:sqlite`: open a file or in-memory database, prepared statements, parameters, rows and transactions.

`elide:sqlite` is an embedded SQLite database with a synchronous API. It is built in: there is nothing to install and no
server to run.

```javascript
// sqlite.mjs
import { Database } from "elide:sqlite";

const db = new Database("app.db", { create: true });
db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, age INTEGER)");

const insert = db.prepare("INSERT INTO users (name, age) VALUES (?, ?)");
insert.run("Ada", 36);
db.prepare("INSERT INTO users (name, age) VALUES ($name, $age)").run({ $name: "Alan", $age: 41 });

const addAll = db.transaction((people) => {
  for (const p of people) insert.run(p.name, p.age);
  return people.length;
});
console.log(addAll([{ name: "Grace", age: 85 }, { name: "Edsger", age: 72 }]));

console.log(db.prepare("SELECT name, age FROM users WHERE age > ?").all(40));
console.log(db.prepare("SELECT name FROM users WHERE id = ?").get(1));
console.log(db.prepare("SELECT name, age FROM users ORDER BY age LIMIT 2").values());
console.log(db.query("SELECT count(*) AS n FROM users").get());
db.close();
```

```bash
elide run sqlite.mjs
```

```text
2
(3)[{name: "Alan", age: 41}, {name: "Grace", age: 85}, {name: "Edsger", age: 72}]
{name: "Ada"}
(2)[["Ada", 36], ["Alan", 41]]
{n: 4}
```

## Open a database

| Call | Opens |
| --- | --- |
| `new Database()`, `new Database(":memory:")` | A new in-memory database |
| `new Database("app.db", { create: true })` | `app.db`, created if missing |
| `new Database("app.db")` | An existing `app.db`; a missing file throws `Database file does not exist or is not readable` |
| `new Database("app.db", { readonly: true })` | An existing file; writes throw `[SQLITE_READONLY] Attempt to write a readonly database` |

## `Database`

| Member | Does |
| --- | --- |
| `exec(sql)` | Runs one statement; returns nothing. Text after the first statement is ignored. |
| `prepare(sql)` | Returns a statement. |
| `query(sql)` | Same as `prepare`. |
| `transaction(fn)` | Returns a function that runs `fn` in a transaction: it commits when `fn` returns and rolls back when `fn` throws. `fn` must be synchronous. `.deferred()`, `.immediate()` and `.exclusive()` return the same function with that lock mode. |
| `serialize()` | The database as an array of bytes. |
| `loadExtension(path)` | Loads a SQLite extension. |
| `close()` | Closes the database; later calls throw `Database is closed`. |

## Statements

| Member | Returns |
| --- | --- |
| `all(...params)` | Every row, as objects keyed by column name |
| `get(...params)` | The first row, or `null` |
| `values(...params)` | Every row, as arrays |
| `run(...params)` | Nothing; use `SELECT last_insert_rowid()` or `changes()` for counts |
| `bind(...params)` | The statement, with its parameters set |

Parameters are positional (`?`, `?1`) or named (`$name`, passed as `{ $name: value }`). A `NULL` column reads as
`undefined`.

## `node:sqlite` and `bun:sqlite`

`node:sqlite` and `bun:sqlite` export the same `Database` class as `elide:sqlite`. Code written for Node's `DatabaseSync` does not run:
`DatabaseSync` is not exported, and `run()` does not return `{ changes, lastInsertRowid }`.

## Samples

- [Embedded SQLite](https://elide.help/docs/code-samples#embedded-sqlite)
- [SQLite transactions](https://elide.help/docs/code-samples#sqlite-transactions)
- [Databases](https://elide.help/docs/api-database): the other drivers, and SQLite from Python and the JVM.

---

# PostgreSQL

URL: https://elide.help/docs/api-postgres

> Connect to PostgreSQL from JavaScript and TypeScript with `elide:postgres`: pooled connections, parameterised queries, transactions, savepoints and batches.

`elide:postgres` connects to a PostgreSQL server through a connection pool. Every call returns a Promise. The same API
drives [MySQL](https://elide.help/docs/api-mysql).

```javascript
// pg.mjs
import { Database } from "elide:postgres";

const db = await Database.connect({
  host: "127.0.0.1",
  port: 5432,
  database: "app",
  user: "app",
  password: process.env.DB_PASSWORD,
  pool: { maxSize: 4 },
});

await db.exec("CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, age INT)");
console.log(await db.exec("INSERT INTO users (name, age) VALUES ($1, $2)", "Ada", 36));

const adults = await db.query("SELECT id, name, age FROM users WHERE age > $1", 18);
console.log(await adults.all());
console.log(await (await db.query("SELECT name FROM users WHERE id = $1", 999)).get());

const [a, b] = await Promise.all([
  db.query("SELECT count(*) AS n FROM users"),
  db.query("SELECT max(age) AS oldest FROM users"),
]);
console.log(await a.get(), await b.get());
console.log(db.poolStats.maxConnections);

await db.close();
```

With `DB_PASSWORD` set in the environment:

```bash
elide run pg.mjs
```

```text
{affectedRows: 1, insertId: 1, insertIds: [1]}
[{id: 1, name: "Ada", age: 36}]
null
{n: 1} {oldest: 36}
4
```

## Connect

`Database.connect()` takes an options object or a `postgresql://` URL with user, password, host, port and database.
It resolves to a database backed by a connection pool.

| Option | Default |
| --- | --- |
| `database`, `user`, `password` | Required; a missing one fails with `password is required` (or that field's name) |
| `host` | `"localhost"` |
| `port` | `5432` |
| `pool.minSize`, `pool.maxSize` | `2`, `10` |
| `pool.connectionTimeout`, `pool.idleTimeout`, `pool.maxLifetime` | `5000`, `30000`, `1800000` ms |
| `pool.leakDetectionThreshold` | `0` (off), ms |
| `ssl.enabled`, `ssl.rejectUnauthorized` | `false`, `true` |
| `ssl.ca`, `ssl.cert`, `ssl.key` | Certificate file paths |
| `properties` | Extra driver properties, as strings |

A refused connection or a wrong password rejects with `Failed to connect to PostgreSQL: …`.

## Queries and rows

| Member | Resolves to |
| --- | --- |
| `query(sql, ...params)` | A result; `await` its `all()` (rows as objects) or `get()` (first row or `null`) |
| `exec(sql, ...params)` | `{ affectedRows, insertId, insertIds }` |
| `prepare(sql)` | A statement with `query()`, `exec()`, `executeBatch(paramLists)` and `close()` |
| `batch([[sql, params], …])` | One `exec` result per statement |
| `transaction(async (tx) => …)` | The callback's return value |
| `close()` | Closes the pool; `connected` becomes `false` and later queries reject with `Database connection is closed` |

Parameters are `$1`, `$2`, … or `?`. Numbers, strings, booleans and `null` map to their SQL types; timestamps read as
strings. A SQL error rejects when you read the result (`all()`, `get()`), not when `query()` resolves.

`poolStats` reports `activeConnections`, `idleConnections`, `totalConnections`, `pendingRequests`, `maxConnections` and
`minConnections`.

## Transactions

```javascript
// tx.mjs
import { Database } from "elide:postgres";

const db = await Database.connect(process.env.DATABASE_URL);

const age = await db.transaction(async (tx) => {
  await tx.exec("UPDATE users SET age = age + 1 WHERE name = $1", "Ada");
  await tx.savepoint("before_cleanup");
  await tx.exec("DELETE FROM users");
  await tx.rollbackTo("before_cleanup");
  return (await tx.query("SELECT age FROM users WHERE name = $1", "Ada")).get();
});
console.log(age);

try {
  await db.transaction(async (tx) => {
    await tx.exec("DELETE FROM users");
    throw new Error("abort");
  });
} catch (e) {
  console.log(e.message);
}
console.log(await (await db.query("SELECT count(*) AS n FROM users")).get());

const update = await db.prepare("UPDATE users SET age = $1 WHERE name = $2");
console.log(await update.executeBatch([[37, "Ada"], [42, "Alan"]]));
update.close();

console.log(await db.batch([
  ["INSERT INTO users (name, age) VALUES ($1, $2)", ["Grace", 85]],
  ["DELETE FROM users WHERE name = $1", ["Grace"]],
]));
await db.close();
```

With `DATABASE_URL` set to the database's `postgresql://` URL:

```bash
elide run tx.mjs
```

```text
{age: 37}
Error: abort
{n: 1}
(2)[{affectedRows: 1, insertId: null, insertIds: []}, {affectedRows: 0, insertId: null, insertIds: []}]
(2)[{affectedRows: 1, insertId: 2, insertIds: [2]}, {affectedRows: 1, insertId: null, insertIds: []}]
```

The transaction commits when the callback resolves and rolls back when it throws or rejects. `tx` has `query`, `exec`,
`commit()`, `rollback()`, `savepoint(name)`, `rollbackTo(name)`, `active`, and `isolation` (default
`"READ_COMMITTED"`).

## Samples

- [PostgreSQL queries](https://elide.help/docs/code-samples#postgresql-queries)
- [Databases](https://elide.help/docs/api-database): choosing a driver.

---

# MySQL

URL: https://elide.help/docs/api-mysql

> Connect to MySQL from JavaScript and TypeScript with `elide:mysql`: the `elide:postgres` API with `?` placeholders, pooled connections and transactions.

`elide:mysql` connects to a MySQL server through a connection pool, with the same Promise-based API as
[`elide:postgres`](https://elide.help/docs/api-postgres).

```javascript
// my.mjs
import { Database } from "elide:mysql";

// A mysql:// URL: user and password, then host, port and database.
const db = await Database.connect(process.env.DATABASE_URL);
await db.exec("CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name TEXT NOT NULL, age INT)");
console.log(await db.exec("INSERT INTO users (name, age) VALUES (?, ?)", "Ada", 36));
console.log(await (await db.query("SELECT name, age FROM users WHERE age > ?", 18)).all());
await db.close();
```

```bash
elide run my.mjs
```

```text
{affectedRows: 1, insertId: 1, insertIds: [1]}
[{name: "Ada", age: 36}]
```

## Connect

`Database.connect()` takes the same options as [PostgreSQL](https://elide.help/docs/api-postgres#connect), or a `mysql://` URL; the default
port is `3306`. `ssl.key` is ignored. Connection failures reject with `Failed to connect to MySQL: …`.

## Differences from PostgreSQL

| | MySQL | PostgreSQL |
| --- | --- | --- |
| Placeholders | `?` only; `$1` fails with `Parameter index out of range` | `$1`, `$2`, … or `?` |
| Default port | `3306` | `5432` |
| `ssl.key` | Ignored | Client key path |

Queries, rows, statements, batches, transactions and `poolStats` work as on the
[PostgreSQL page](https://elide.help/docs/api-postgres#queries-and-rows).

## Related

- [PostgreSQL](https://elide.help/docs/api-postgres): the shared API in full.
- [Databases](https://elide.help/docs/api-database): choosing a driver.

---

# node:assert

URL: https://elide.help/docs/api-node-assert

> How Elide supports Node's `assert` and `assert/strict` modules: which assertions work, and where loose deep equality, the `Assert` class and error messages differ.

`node:assert` and `node:assert/strict` provide [Node's assertion functions](https://nodejs.org/api/assert.html),
from `ok` and `deepStrictEqual` to `throws`, `rejects`, `match` and `partialDeepStrictEqual`.

## Example

```js
// assert.mjs
import assert from "node:assert/strict";

assert.deepEqual({ ids: [1, 2] }, { ids: [1, 2] });
assert.throws(() => JSON.parse("{"), SyntaxError);
await assert.rejects(Promise.reject(new Error("nope")), /nope/);

try {
  assert.equal(1 + 1, 3);
} catch (error) {
  console.log(error.name, error.code, error.actual, error.expected);
}
```

`elide run assert.mjs` prints:

```text
AssertionError ERR_ASSERTION 2 3
```

## Differences from Node

- `assert.Assert` is not a constructor.
- Loose `deepEqual` treats `null` and `undefined` as different, and compares proxies differently.
- A symbol `message`, or a number as `expected` in `throws()`, raises `AssertionError` instead of
  `ERR_INVALID_ARG_TYPE`.
- `AssertionError.operator` holds the method name (`strictEqual`), not a symbol (`===`).

<!-- api-reference:start bd2bc2f11d46 -->
## Reference

**Status:** Partial · 7 of 13 suite tests pass (53.8%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `ok()` | function | Full | Tests if `value` is truthy |
| `equal()` | function | Full | Tests shallow equality between `actual` and `expected` using `==` |
| `notEqual()` | function | Full | Tests shallow inequality between `actual` and `expected` using `!=` |
| `strictEqual()` | function | Full | Tests strict equality between `actual` and `expected` using `===` |
| `notStrictEqual()` | function | Full | Tests strict inequality between `actual` and `expected` using `!==` |
| `deepEqual()` | function | Full | Tests for deep equality between `actual` and `expected` using abstract equality (`==`) for leaf comparisons |
| `deepStrictEqual()` | function | Full | Tests for deep strict equality between `actual` and `expected` using strict equality (`===`) for leaf… |
| `notDeepEqual()` | function | Full | Tests that `actual` is NOT deeply equal to `expected` (abstract equality) |
| `notDeepStrictEqual()` | function | Full | Tests that `actual` is NOT deeply strictly equal to `expected` |
| `throws()` | function | Full | Expects the function `fn` to throw an error |
| `doesNotThrow()` | function | Full | Asserts that the function `fn` does not throw an error |
| `rejects()` | function | Full | Awaits the `asyncFn` promise (or calls it if it's a function) and expects it to reject |
| `doesNotReject()` | function | Full | Awaits the `asyncFn` promise (or calls it if it's a function) and expects it NOT to reject |
| `fail()` | function | Full | Throws an AssertionError unconditionally |
| `ifError()` | function | Full | If `value` is truthy (not null/undefined/false), throws it |
| `match()` | function | Full | Expects `string` to match the regular expression `regexp` |
| `doesNotMatch()` | function | Full | Expects `string` NOT to match the regular expression `regexp` |

### Not implemented

`Assert`, `assert/strict.Assert`.

**Tests:** [node-api `node:assert`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 7 pass, 6 fail, 0 error, 1 skipped. Failing: `test-assert-async.js`, `test-assert-class-destructuring.js`, `test-assert-class.js`, `test-assert-deep.js`, `test-assert-esm-cjs-message-verify.js`, `test-assert.js`.
<!-- api-reference:end -->

---

# node:async_hooks

URL: https://elide.help/docs/api-node-async-hooks

> How Elide supports Node's `async_hooks`: AsyncLocalStorage, AsyncResource and createHook, and where AsyncLocalStorage context does not propagate.

`node:async_hooks` provides `AsyncLocalStorage`, `AsyncResource`, and `createHook` from
[Node's `async_hooks`](https://nodejs.org/api/async_hooks.html).

## Example

```js
import { AsyncLocalStorage } from "node:async_hooks";

const storage = new AsyncLocalStorage();
storage.run("request", async () => {
  await null;
  console.log(storage.getStore()); // request
  queueMicrotask(() => console.log(storage.getStore())); // undefined
});
```

## Differences from Node

- `AsyncLocalStorage` context is lost in `queueMicrotask` callbacks and `node:fs` callbacks.
- `createHook` callbacks (`init`, `before`, `after`, `destroy`) fire for timers, immediates, and Promise continuations.

<!-- api-reference:start 6e95af6a7301 -->
## Reference

**Status:** Partial · 36 of 45 suite tests pass (80.0%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `async_hooks` | module | Partial | hooks fire for timers/immediates/promises but not yet for TCP/HTTP/TLS native resources |
| `createHook()` | function | Full | Creates a new AsyncHook instance |
| `executionAsyncId()` | function | Full | Returns the asyncId of the current execution context |
| `triggerAsyncId()` | function | Full | Returns the ID of the resource responsible for calling the callback that is currently being executed |
| `AsyncLocalStorage` | property | Full | The AsyncLocalStorage class |
| `AsyncResource` | property | Full | The AsyncResource class |

**Tests:** [node-api `node:async-hooks`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 36 pass, 8 fail, 1 error, 3 skipped. Failing: `test-async-hooks-destroy-on-gc.js`, `test-async-hooks-enable-recursive.js`, `test-async-hooks-fatal-error.js`, `test-async-hooks-http-parser-destroy.js`, `test-async-hooks-top-level-clearimmediate.js`, `test-async-local-storage-http-agent.js`, `test-async-local-storage-http-multiclients.js`, `test-async-local-storage-http-parser-leak.js`, and 1 more.
<!-- api-reference:end -->

---

# node:buffer

URL: https://elide.help/docs/api-node-buffer

> How Elide supports Node's `Buffer` global and `node:buffer` module: one object, with `allocUnsafe` and `allocUnsafeSlow` returning zero-filled memory.

`Buffer` is a global and the same object as the `Buffer` export of `node:buffer`, which follows
[Node's `buffer`](https://nodejs.org/api/buffer.html).

## Example

```js
// buffer.mjs
const greeting = Buffer.from("héllo");
console.log(greeting.length, greeting.toString("hex"));
console.log(greeting.toString("base64"), Buffer.from("aMOpbGxv", "base64").toString());

const header = Buffer.alloc(4);
header.writeUInt32BE(0xcafebabe);
console.log(header.toString("hex"), header.readUInt16LE(2));
console.log(Buffer.concat([greeting, Buffer.from("!")]).toString());
```

`elide run buffer.mjs` prints:

```text
6 68c3a96c6c6f
aMOpbGxv héllo
cafebabe 48826
héllo!
```

## Differences from Node

- `Buffer.allocUnsafe` and `Buffer.allocUnsafeSlow` return zero-filled memory.

<!-- api-reference:start 929299403fab -->
## Reference

**Status:** Full · 56 of 62 suite tests pass (90.3%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Buffer` | class | Full | `Buffer.alloc()`, `Buffer.allocUnsafe()`, `Buffer.allocUnsafeSlow()`, `Buffer.from()`, `Buffer.isBuffer()`, `Buffer.isEncoding()`, `Buffer.byteLength()`, `Buffer.concat()`, `Buffer.compare()`, `length`, `buffer`, `byteOffset`, `compare()`, `copy()`, `equals()`, `fill()`, `includes()`, `indexOf()`, `lastIndexOf()`, `slice()`, `subarray()`, `write()`, `toString()`, `toJSON()`, `readUInt8()`, `readUInt16BE()`, `readUInt16LE()`, `readUInt32BE()`, `readUInt32LE()`, `readInt8()`, `readInt16BE()`, `readInt16LE()`, `readInt32BE()`, `readInt32LE()`, `readUIntBE()`, `readUIntLE()`, `readIntBE()`, `readIntLE()`, `readFloatBE()`, `readFloatLE()`, `readDoubleBE()`, `readDoubleLE()`, `writeUInt8()`, `writeUInt16BE()`, `writeUInt16LE()`, `writeUInt32BE()`, `writeUInt32LE()`, `writeInt8()`, `writeInt16BE()`, `writeInt16LE()`, `writeInt32BE()`, `writeInt32LE()`, `writeUIntBE()`, `writeUIntLE()`, `writeIntBE()`, `writeIntLE()`, `writeFloatBE()`, `writeFloatLE()`, `writeDoubleBE()`, `writeDoubleLE()`, `swap16()`, `swap32()`, `swap64()` |
| `atob()` | function | Full | Decodes a base64-encoded ASCII string into a Latin-1 string |
| `btoa()` | function | Full | Encodes a Latin-1 string as base64 ASCII |
| `isAscii()` | function | Full | Returns true if every byte's high bit is clear (the input contains only 7-bit ASCII) |
| `isUtf8()` | function | Full | Returns true if the bytes form a structurally valid UTF-8 sequence (no overlong forms, surrogates, or… |
| `kMaxLength` | property | Full | Largest buffer size representable as a 32-bit JS integer (2^31 - 1) |
| `kStringMaxLength` | property | Full | Largest string length the runtime will allocate (2^31 - 1) |

**Tests:** [node-api `node:buffer`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 56 pass, 6 fail, 0 error, 7 skipped. Failing: `test-buffer-alloc.js`, `test-buffer-constructor-node-modules-paths.js`, `test-buffer-constructor-node-modules.js`, `test-buffer-constructor-outside-node-modules.js`, `test-buffer-indexof.js`, `test-buffer-pool-untransferable.js`.
<!-- api-reference:end -->

---

# node:child_process

URL: https://elide.help/docs/api-node-child-process

> How Elide supports Node's `child_process`: spawn, exec, execFile and their Sync forms, fork() with IPC between Elide scripts, and sandbox flags.

`node:child_process` provides [Node's process APIs](https://nodejs.org/api/child_process.html): `spawn`, `exec`,
`execFile`, their `Sync` forms, `fork`, and `ChildProcess`.

## Example

```js
// child.mjs
import { execFile, execFileSync } from "node:child_process";
import { promisify } from "node:util";

console.log(execFileSync("echo", ["hello"], { encoding: "utf8" }).trim());

const { stdout, stderr } = await promisify(execFile)("sh", ["-c", "echo out; echo err >&2"]);
console.log(JSON.stringify({ stdout, stderr }));

try {
  execFileSync("sh", ["-c", "exit 3"]);
} catch (error) {
  console.log("exit status", error.status);
}
```

`elide run child.mjs` prints:

```text
hello
{"stdout":"out\n","stderr":"err\n"}
exit status 3
```

## Differences from Node

- `fork()` starts another Elide script; `child.send()` and `process.send()` exchange `message` events.
- `process.execPath` runs Elide: `execFileSync(process.execPath, ["--snippet", 'process.stdout.write("hi")'])`.
- `--allow-run` and `--deny-run` apply under the [sandbox](https://elide.help/docs/sandbox).

## Samples

- [Sandboxed subprocess](https://elide.help/docs/code-samples#sandboxed-subprocess)

<!-- api-reference:start ab2926d28c89 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `exec()`, `execSync()` | function | Full | Executes a command in a shell |
| `execFile()`, `execFileSync()` | function | Full | Executes a file without a shell |
| `spawn()`, `spawnSync()` | function | Full | Spawns a new process using the given command |
| `fork()` | function | Full | Spawns a new Node.js process using the given module path |
<!-- api-reference:end -->

---

# node:console

URL: https://elide.help/docs/api-node-console

> How Elide supports Node's `console` module and `Console` class: the inspector-only methods are absent and `console.table` formatting differs from Node.

`node:console` returns `globalThis.console` and exports `Console` for writing to other streams, as in
[Node's `console`](https://nodejs.org/api/console.html).

## Example

```js
// console.mjs
import { Console } from "node:console";
import { Writable } from "node:stream";

let captured = "";
const sink = new Writable({
  write(chunk, _encoding, done) {
    captured += chunk;
    done();
  },
});
const logger = new Console({ stdout: sink, stderr: sink });
logger.log("%s=%d", "retries", 3);
logger.error("failed");
logger.count("hits");
logger.count("hits");
process.stdout.write(captured);
```

`elide run console.mjs` prints:

```text
retries=3
failed
hits: 1
hits: 2
```

## Differences from Node

- `profile`, `profileEnd`, `timeStamp`, `context`, and `createTask` are absent.
- `console.table` spacing and alignment differ from Node; do not parse the output.

<!-- api-reference:start 323334e086d9 -->
## Reference

**Status:** Partial · 20 of 21 suite tests pass (95.2%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `log()` | function | Full | Prints to stdout with newline |
| `info()` | function | Full | Alias for log() |
| `warn()` | function | Full | Prints to stderr with newline |
| `error()` | function | Full | Prints to stderr with newline |
| `debug()` | function | Full | Prints to stdout with newline |
| `trace()` | function | Full | Prints to stderr the string 'Trace: ' followed by a stack trace |
| `dir()` | function | Full | Uses util.inspect() on obj and prints the resulting string to stdout |
| `dirxml()` | function | Full | Alias for log() |
| `table()` | function | Full | Prints a table representation of the data |
| `clear()` | function | Full | Clears the console (when possible) |
| `count()` | function | Full | Maintains an internal counter and outputs the number of times count() has been called with the given label |
| `countReset()` | function | Full | Resets the internal counter for the given label |
| `group()` | function | Full | Increases indentation of subsequent lines by spaces for grouping |
| `groupCollapsed()` | function | Full | Alias for group() |
| `groupEnd()` | function | Full | Decreases indentation of subsequent lines by spaces for grouping |
| `time()` | function | Full | Starts a timer with a given label |
| `timeEnd()` | function | Full | Stops a timer and prints elapsed time |
| `timeLog()` | function | Full | Prints the elapsed time for a running timer without stopping it |
| `assert()` | function | Full | Writes an error message to the console if the assertion is false |

### Not implemented

`context`, `createTask`, `profile`, `profileEnd`, `timeStamp`.

**Tests:** [node-api `node:console`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 20 pass, 1 fail, 0 error, 1 skipped. Failing: `test-console-issue-43095.js`.
<!-- api-reference:end -->

---

# node:crypto

URL: https://elide.help/docs/api-node-crypto

> How Elide supports Node's `crypto` module: hashing, ciphers, keys, signatures, ML-DSA and ML-KEM, its error strings, and the APIs that are not available.

`node:crypto` provides [Node's crypto API](https://nodejs.org/api/crypto.html) for hashing, ciphers, keys, signatures,
key agreement, key derivation, and random values, including ML-DSA and ML-KEM keys. `webcrypto` is the same object as
`globalThis.crypto`.

## Example

```js
// crypto.mjs
import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes } from "node:crypto";

console.log(createHash("sha256").update("elide").digest("hex"));
console.log(createHmac("sha256", "secret").update("elide").digest("base64url"));

const key = randomBytes(32);
const iv = randomBytes(12);
const cipher = createCipheriv("aes-256-gcm", key, iv);
const sealed = Buffer.concat([cipher.update("attack at dawn"), cipher.final()]);
const decipher = createDecipheriv("aes-256-gcm", key, iv).setAuthTag(cipher.getAuthTag());
console.log(Buffer.concat([decipher.update(sealed), decipher.final()]).toString());
```

`elide run crypto.mjs` prints:

```text
bdfdf1cc04d072e4128275829659a2296e17d52f848a06528e36bd2a5a7d142a
XtA6v3HkpDq8cpjaFeOfRO2VxSoKx5bR11f7dK9U25g
attack at dawn
```

## Differences from Node

- `process.versions.openssl` is `1.1.1` and `process.features.openssl_is_boringssl` is `true`.
- Errors use BoringSSL-style strings (`error:1e000065:Cipher functions:OPENSSL_internal:BAD_DECRYPT`) and
  `ERR_OSSL_*` codes.
- `X509Certificate` and `Certificate` are not exported.
- Ed448 and X448 throw `ERR_CRYPTO_UNSUPPORTED_OPERATION`; OCB ciphers are absent.
- `argon2` and `argon2Sync` throw `ERR_CRYPTO_ARGON2_NOT_SUPPORTED`.
- `setFips` throws `ERR_CRYPTO_FIPS_UNAVAILABLE`; `getFips()` returns `0`.
- `setEngine` throws `ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED`.

<!-- api-reference:start 912f1ca702e3 -->
## Reference

**Status:** Partial · 95 of 112 suite tests pass (84.8%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Hash` | class | Full | `update()`, `digest()`, `copy()` |
| `Hmac` | class | Full | `update()`, `digest()` |
| `createHash()` | function | Full | Creates and returns a Hash object for the given algorithm |
| `createHmac()` | function | Full | Creates and returns an Hmac object for the given algorithm and key |
| `randomBytes()` | function | Full | Generates cryptographically strong pseudorandom bytes |
| `randomFill()`, `randomFillSync()` | function | Full | Fills a buffer with random bytes |
| `randomInt()` | function | Full | Returns a random integer n such that min <= n < max |
| `randomUUID()` | function | Full | Generates a random RFC 4122 version 4 UUID string |
| `pbkdf2()`, `pbkdf2Sync()` | function | Full | Derives a key using PBKDF2 |
| `scrypt()`, `scryptSync()` | function | Full | Derives a key using scrypt |
| `timingSafeEqual()` | function | Full | Compares two buffers in constant time to prevent timing attacks |
| `getHashes()` | function | Full | Returns the list of supported hash algorithm names |
| `getCiphers()` | function | Full | Returns the list of supported cipher algorithm names |
| `constants` | property | Full | Crypto constants such as RSA_PKCS1_PADDING |
| `webcrypto` | property | Full | The Web Crypto API (SubtleCrypto) instance |

### Not implemented

`Certificate`, `X509Certificate`, `decapsulate`, `encapsulate`.

**Tests:** [node-api `node:crypto`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 95 pass, 17 fail, 0 error, 69 skipped. Failing: `test-crypto-certificate.js`, `test-crypto-dh-leak.js`, `test-crypto-encap-decap.js`, `test-crypto-key-objects-messageport.js`, `test-crypto-keyobject-hidden-slots.js`, `test-crypto-pqc-encrypted-pkcs8.js`, `test-crypto-pqc-key-objects-ml-dsa.js`, `test-crypto-pqc-key-objects-ml-kem.js`, and 9 more.
<!-- api-reference:end -->

---

# node:dgram

URL: https://elide.help/docs/api-node-dgram

> How Elide supports Node's `dgram` module: `udp4` and `udp6` sockets match Node, and `--allow-net` and `--deny-net` apply under the sandbox.

`node:dgram` matches [Node's `dgram`](https://nodejs.org/api/dgram.html) for `udp4` and `udp6` sockets; `--allow-net`
and `--deny-net` apply under the [sandbox](https://elide.help/docs/sandbox).

## Example

```js
// dgram.mjs
import dgram from "node:dgram";

const server = dgram.createSocket("udp4");
server.on("message", (message, remote) => {
  console.log("received", message.toString(), "from", remote.family);
  server.close();
  client.close();
});
const client = dgram.createSocket("udp4");
server.bind(0, "127.0.0.1", () => {
  client.send("ping", server.address().port, "127.0.0.1");
});
```

`elide run dgram.mjs` prints:

```text
received ping from IPv4
```

<!-- api-reference:start 1615e7c68200 -->
## Reference

**Status:** Full · Not measured

### `dgram` exports

`Socket`, `createSocket`
<!-- api-reference:end -->

---

# node:diagnostics_channel

URL: https://elide.help/docs/api-node-diagnostics-channel

> How Elide supports Node's `diagnostics_channel` module: channels, tracing channels and stores, which built-in channels publish, and the `boundedChannel` addition.

`node:diagnostics_channel` provides `channel`, `subscribe`, `tracingChannel`, `bindStore` and `runStores` from
[Node's `diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html).

## Example

```js
// dc.mjs
import diagnostics from "node:diagnostics_channel";

const channel = diagnostics.channel("app:query");
diagnostics.subscribe("app:query", (message, name) => console.log(name, message.sql));
console.log("subscribers:", channel.hasSubscribers);
channel.publish({ sql: "select 1" });

const tracing = diagnostics.tracingChannel("app:job");
tracing.subscribe({
  start: () => console.log("start"),
  end: () => console.log("end"),
});
console.log(tracing.traceSync(() => 42));
```

`elide run dc.mjs` prints:

```text
subscribers: true
app:query select 1
start
end
42
```

## Differences from Node

- Elide adds `boundedChannel` and `BoundedChannel`.
- Channel stores follow the propagation rules in [`node:async_hooks`](https://elide.help/docs/api-node-async-hooks).
- `net.server.socket`, `tracing:module.import`, `http2.*`, `tls.*` and Web Locks channels are not published.

Built-in modules publish on these channels:

| Module | Publishes |
| --- | --- |
| `node:http` | client and server request channels |
| `node:net` | `net.client.socket`, `tracing:net.server.listen` |
| `node:dgram`, `node:child_process`, `node:worker_threads` | their Node channels |
| `require()` | `tracing:module.require` |

<!-- api-reference:start 0082489c31cb -->
## Reference

**Status:** Full · 42 of 67 suite tests pass (62.7%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Channel` | class | Full | `name`, `hasSubscribers`, `publish()`, `subscribe()`, `unsubscribe()` |
| `channel()` | function | Full | Returns a Channel object for the given name, creating one if it does not exist |
| `hasSubscribers()` | function | Full | Returns whether the named channel has active subscribers |
| `subscribe()` | function | Full | Subscribe a handler to the named channel |
| `unsubscribe()` | function | Full | Unsubscribe a handler from the named channel |

**Tests:** [node-api `node:diagnostics-channel`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 42 pass, 25 fail, 0 error, 1 skipped. Failing: `test-diagnostics-channel-http2-client-stream-body-multiple-buffers-and-strings.js`, `test-diagnostics-channel-http2-client-stream-body-multiple-buffers.js`, `test-diagnostics-channel-http2-client-stream-body-no-chunks.js`, `test-diagnostics-channel-http2-client-stream-body-single-buffer.js`, `test-diagnostics-channel-http2-client-stream-body-single-string.js`, `test-diagnostics-channel-http2-client-stream-close-error.js`, `test-diagnostics-channel-http2-client-stream-close.js`, `test-diagnostics-channel-http2-client-stream-created.js`, and 17 more.
<!-- api-reference:end -->

---

# node:dns

URL: https://elide.help/docs/api-node-dns

> How Elide supports Node's `dns` and `dns/promises` modules: Resolver and every resolve* record type match Node, and `lookup` uses the host resolver.

`node:dns` and `node:dns/promises` match [Node's `dns`](https://nodejs.org/api/dns.html), including `Resolver` and every
`resolve*` record type. `lookup` uses the host resolver, so `lookup("localhost")` works offline.

## Example

```js
// dns.mjs
import { lookup } from "node:dns/promises";
import { isIP } from "node:net";

const { address, family } = await lookup("localhost", { family: 4 });
console.log(address, family);
const all = await lookup("localhost", { all: true });
console.log(all.every((entry) => isIP(entry.address) === entry.family));
```

`elide run dns.mjs` prints:

```text
127.0.0.1 4
true
```

<!-- api-reference:start ae1e1c55e637 -->
## Reference

**Status:** Full · 17 of 20 suite tests pass (85.0%)

### `dns` exports

`Resolver`, `getDefaultResultOrder`, `getServers`, `lookup`, `lookupService`, `promises`, `resolve`, `resolve4`, `resolve6`, `resolveAny`, `resolveCaa`, `resolveCname`, `resolveMx`, `resolveNaptr`, `resolveNs`, `resolvePtr`, `resolveSoa`, `resolveSrv`, `resolveTlsa`, `resolveTxt`, `reverse`, `setDefaultResultOrder`, `setServers`, 27 constants such as `ADDRCONFIG`

**Tests:** [node-api `node:dns`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 17 pass, 3 fail, 0 error, 10 skipped. Failing: `test-dns-get-server.js`, `test-dns-setserver-when-querying.js`, `test-dns.js`.
<!-- api-reference:end -->

---

# node:domain

URL: https://elide.help/docs/api-node-domain

> How Elide supports Node's deprecated `domain` module: create(), run() and the error event for synchronous and timer errors, and what to use instead.

`node:domain` exports `Domain`, `create()`, `createDomain()`, and `active` from
[Node's deprecated `domain`](https://nodejs.org/api/domain.html). Synchronous and timer errors thrown inside `run()`
go to the domain's `error` event. Use Promise and `EventEmitter` error handling in new code.

## Example

```js
// domain.mjs
import domain from "node:domain";

const d = domain.create();
d.on("error", (error) => console.log("caught:", error.message));
d.run(() => {
  setTimeout(() => {
    throw new Error("timer failed");
  }, 1);
});
```

`elide run domain.mjs` prints:

```text
caught: timer failed
```

<!-- api-reference:start f35764ee1a8b -->
## Reference

**Status:** Full · Not measured

### `domain` exports

`Domain`, `active`, `create`, `createDomain`
<!-- api-reference:end -->

---

# node:events

URL: https://elide.help/docs/api-node-events

> How Elide supports Node's `events` module: EventEmitter, once() and on() with an AbortSignal, captureRejections, and the EventEmitterAsyncResource and EventSource gaps.

`node:events` provides [Node's `EventEmitter`](https://nodejs.org/api/events.html), `once()` and `on()` with an
`AbortSignal`, `once()` on an `EventTarget`, `captureRejections` and `EventEmitterAsyncResource`.

## Example

```js
// events.mjs
import { EventEmitter, once } from "node:events";

const jobs = new EventEmitter();
jobs.on("done", (id) => console.log(`job ${id} done`));
jobs.emit("done", 1);

setTimeout(() => jobs.emit("idle", 3), 10);
const [pending] = await once(jobs, "idle");
console.log("idle with", pending, "listeners:", jobs.listenerCount("done"));
```

`elide run events.mjs` prints:

```text
job 1 done
idle with 3 listeners: 1
```

## Differences from Node

- `EventEmitterAsyncResource#asyncResource.eventEmitter` does not return the emitter.
- There is no `EventSource` global.

<!-- api-reference:start 05378e039bdb -->
## Reference

**Status:** Full · 34 of 38 suite tests pass (89.5%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `EventEmitter` | class | Full | `addListener()`, `on()`, `once()`, `prependListener()`, `prependOnceListener()`, `removeListener()`, `off()`, `removeAllListeners()`, `emit()`, `listenerCount()`, `listeners()`, `rawListeners()`, `eventNames()`, `setMaxListeners()`, `getMaxListeners()`, `EventEmitter.defaultMaxListeners`, `EventEmitter.once()`, `EventEmitter.listenerCount()` |

**Tests:** [node-api `node:events`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 34 pass, 3 fail, 1 error, 6 skipped. Failing: `test-event-capture-rejections.js`, `test-eventemitter-asyncresource.js`, `test-events-once.js`, `test-eventsource.js`.
<!-- api-reference:end -->

---

# node:fs

URL: https://elide.help/docs/api-node-fs

> How Elide supports Node's `fs` and `fs/promises` modules: glob, cp, statfs and watch match Node, `openAsBlob` is missing, and sandbox flags limit access.

`node:fs`, `node:fs/promises`, and `fs.promises` match [Node's `fs`](https://nodejs.org/api/fs.html), including `glob`,
`cp`, `statfs`, `opendir`, and `watch`.

## Example

```js
// fs.mjs
import { existsSync } from "node:fs";
import { mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";

const dir = await mkdtemp(join(tmpdir(), "notes-"));
await writeFile(join(dir, "todo.txt"), "ship the docs");
console.log(await readFile(join(dir, "todo.txt"), "utf8"));
console.log((await readdir(dir)).join(), (await stat(join(dir, "todo.txt"))).size);
await rm(dir, { recursive: true });
console.log(existsSync(dir));
```

`elide run fs.mjs` prints:

```text
ship the docs
todo.txt 13
false
```

## Differences from Node

- `lchmod` exists only in `fs/promises`; it has no callback or sync form.
- `fs.openAsBlob` is not available.
- Access is unrestricted until `--sandbox`, `--allow-read`, `--allow-write`, or `--fs-audit` is set; see
  [Sandbox](https://elide.help/docs/sandbox).

## Samples

- [Files and paths](https://elide.help/docs/code-samples#files-and-paths)
- [CSV report](https://elide.help/docs/code-samples#csv-report)

<!-- api-reference:start 4cd1c55e57d9 -->
## Reference

**Status:** Partial · 246 of 264 suite tests pass (93.2%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `readFile()`, `readFileSync()` | function | Full | Reads the entire contents of a file |
| `writeFile()`, `writeFileSync()` | function | Full | Writes data to a file, replacing it if it already exists |
| `appendFile()`, `appendFileSync()` | function | Full | Appends data to a file, creating it if it does not exist |
| `stat()`, `statSync()` | function | Full | Retrieves file status information |
| `mkdir()`, `mkdirSync()` | function | Full | Creates a directory |
| `rmdir()`, `rmdirSync()` | function | Full | Removes a directory |
| `unlink()`, `unlinkSync()` | function | Full | Deletes a file |
| `rename()`, `renameSync()` | function | Full | Renames (moves) a file or directory |
| `readdir()`, `readdirSync()` | function | Full | Reads the contents of a directory |
| `access()`, `accessSync()` | function | Full | Tests whether a path is accessible under the given mode |
| `copyFile()`, `copyFileSync()` | function | Full | Copies a file from src to dest |
| `chmod()`, `chmodSync()` | function | Full | Changes the permissions of a file |
| `lstat()`, `lstatSync()` | function | Full | Retrieves file status information without following symbolic links |
| `realpath()`, `realpathSync()` | function | Full | Resolves all symbolic links and returns the real absolute path |
| `mkdtemp()`, `mkdtempSync()` | function | Full | Creates a unique temporary directory using a prefix template |
| `open()`, `openSync()` | function | Full | Opens a file |
| `close()`, `closeSync()` | function | Full | Closes a file descriptor |
| `read()`, `readSync()` | function | Full | Reads from a file descriptor into a buffer |
| `write()`, `writeSync()` | function | Full | Writes to a file descriptor |
| `fsync()`, `fsyncSync()` | function | Full | Flushes data and metadata of a descriptor |
| `fdatasync()`, `fdatasyncSync()` | function | Full | Flushes data of a descriptor |
| `ftruncate()`, `ftruncateSync()` | function | Full | Truncates a file by descriptor |
| `truncate()`, `truncateSync()` | function | Full | Truncates a file by path |
| `readlink()`, `readlinkSync()` | function | Full | Reads a symbolic link's target |
| `link()`, `linkSync()` | function | Full | Creates a hard link |
| `symlink()`, `symlinkSync()` | function | Full | Creates a symbolic link |
| `rm()`, `rmSync()` | function | Full | Removes files and directories |
| `cp()`, `cpSync()` | function | Full | Copies a directory structure |
| `statfs()`, `statfsSync()` | function | Full | Returns filesystem statistics |
| `opendir()`, `opendirSync()` | function | Full | Opens a directory |
| `glob()`, `globSync()` | function | Full | Returns paths matching a glob |
| `chown()`, `chownSync()` | function | Full | Changes ownership of a file |
| `lchown()`, `lchownSync()` | function | Full | Changes ownership of a symlink |
| `fchown()`, `fchownSync()` | function | Full | Changes ownership by descriptor |
| `lchmod()`, `lchmodSync()` | function | Not implemented | Changes permissions of a symlink (macOS) |
| `fchmod()`, `fchmodSync()` | function | Full | Changes permissions by descriptor |
| `utimes()`, `utimesSync()` | function | Full | Sets file times |
| `lutimes()`, `lutimesSync()` | function | Full | Sets symlink times |
| `futimes()`, `futimesSync()` | function | Full | Sets times by descriptor |
| `fstat()`, `fstatSync()` | function | Full | Retrieves status by descriptor |
| `exists()`, `existsSync()` | function | Full | Deprecated: asynchronously tests whether a path exists |
| `createReadStream()` | function | Full | Creates a readable stream for a file |
| `createWriteStream()` | function | Full | Creates a writable stream for a file |
| `watch()` | function | Full | Watches for changes on a file or directory |
| `watchFile()` | function | Full | Watches a file for changes by polling its status at an interval |
| `unwatchFile()` | function | Full | Stops watching a file previously watched with watchFile |
| `promises` | property | Full | Promise-based variants of all fs methods (fs/promises) |
| `constants` | property | Full | File system constants such as F_OK, R_OK, W_OK, X_OK, COPYFILE_EXCL |
| top-level constants | constant | Full | `F_OK`, `R_OK`, `W_OK`, `X_OK`, `COPYFILE_EXCL`, `COPYFILE_FICLONE` and 46 more |

### `fs/promises`

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `access()` | function | Full | Test a path's accessibility |
| `appendFile()` | function | Full | Append data to a file |
| `chmod()` | function | Full | Change file permissions |
| `chown()` | function | Full | Change file ownership |
| `copyFile()` | function | Full | Copy a file |
| `cp()` | function | Full | Recursively copy a directory tree |
| `glob()` | function | Full | Match paths against a glob pattern |
| `lchmod()` | function | Full | Change permissions of a symbolic link (macOS) |
| `lchown()` | function | Full | Change ownership of a symbolic link |
| `link()` | function | Full | Create a hard link |
| `lstat()` | function | Full | Retrieve link status (does not follow symlinks) |
| `lutimes()` | function | Full | Set the times of a symbolic link |
| `mkdir()` | function | Full | Create a directory |
| `mkdtemp()` | function | Full | Create a unique temporary directory |
| `open()` | function | Full | Open a file, resolving to a FileHandle |
| `opendir()` | function | Full | Open a directory for iteration |
| `readdir()` | function | Full | Read the contents of a directory |
| `readFile()` | function | Full | Read the entire contents of a file |
| `readlink()` | function | Full | Read the target of a symbolic link |
| `realpath()` | function | Full | Resolve the canonical pathname |
| `rename()` | function | Full | Rename (move) a file or directory |
| `rm()` | function | Full | Remove files and directories |
| `rmdir()` | function | Full | Remove a directory |
| `stat()` | function | Full | Retrieve file status |
| `statfs()` | function | Full | Retrieve filesystem statistics |
| `symlink()` | function | Full | Create a symbolic link |
| `truncate()` | function | Full | Truncate a file |
| `unlink()` | function | Full | Delete a file |
| `utimes()` | function | Full | Set the access and modification times of a file |
| `watch()` | function | Full | Watch a file or directory, returning an async iterator of change events |
| `writeFile()` | function | Full | Write data to a file, replacing it if it exists |

### Not implemented

`FileReadStream`, `FileWriteStream`, `Utf8Stream`, `lchmod`, `lchmodSync`, `openAsBlob`.

**Tests:** [node-api `node:fs`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 246 pass, 18 fail, 0 error, 30 skipped. Failing: `test-fs-promises-file-handle-pull.js`, `test-fs-promises-file-handle-pullsync.js`, `test-fs-promises-file-handle-read-worker.js`, `test-fs-promises-file-handle-writer.js`, `test-fs-promises-watch.js`, `test-fs-promises.js`, `test-fs-read-stream-file-handle.js`, `test-fs-stat.js`, and 10 more.
<!-- api-reference:end -->

---

# node:http

URL: https://elide.help/docs/api-node-http

> How Elide supports Node's `http` and `https`: the HTTP/1.1 server and client and the HTTPS client; `https.createServer` and `node:http2` are unavailable.

`node:http` provides [Node's HTTP/1.1](https://nodejs.org/api/http.html) server and client; `node:https` provides the
client only. For a Fetch-style handler or HTTP/2, use [`Elide.serve`](https://elide.help/docs/api-globals-elide).

## Example

```js
// http.mjs
import { createServer } from "node:http";

const server = createServer((req, res) => {
  res.writeHead(200, { "content-type": "text/plain" });
  res.end(`${req.method} ${req.url}\n`);
});

server.listen(0, "127.0.0.1", async () => {
  const { port } = server.address();
  const response = await fetch(`http://127.0.0.1:${port}/hello`);
  console.log(response.status, response.headers.get("content-type"));
  console.log(await response.text());
  server.close();
});
```

`elide run http.mjs` prints:

```text
200 text/plain
GET /hello
```

## Differences from Node

- `https.createServer` throws `ERR_HTTPS_SERVER_UNSUPPORTED`; terminate TLS in front of `http.createServer`.
- `http.globalAgent` defaults to `keepAlive: true`, `maxSockets: Infinity`, and `maxFreeSockets: 256`.
- HTTPS certificate validation follows [fetch](https://elide.help/docs/api-whatwg-fetch).
- `node:http2` is unavailable.
- `--allow-net` and `--deny-net` apply under the [sandbox](https://elide.help/docs/sandbox).

## Samples

- [node:http server and client](https://elide.help/docs/code-samples#nodehttp-server-and-client)

<!-- api-reference:start f13d050c0262 -->
## Reference

**Status:** Partial · Not measured

### `http` exports

`Agent`, `ClientRequest`, `IncomingMessage`, `OutgoingMessage`, `Server`, `ServerResponse`, `createServer`, `get`, `globalAgent`, `maxHeaderSize`, `request`, `setMaxIdleHTTPParsers`, `validateHeaderName`, `validateHeaderValue`, 2 constants such as `METHODS`

### Not implemented

`CloseEvent`, `MessageEvent`, `WebSocket`, `setGlobalProxyFromEnv`.
<!-- api-reference:end -->

---

# node:module

URL: https://elide.help/docs/api-node-module

> How Elide supports Node's `module` helpers: createRequire, isBuiltin and builtinModules, with source-map lookups stubbed and loader hooks unsupported.

`node:module` exports `createRequire`, `isBuiltin`, `builtinModules`, and the rest of
[Node's module helpers](https://nodejs.org/api/module.html).

## Example

```js
// module.mjs
import { builtinModules, createRequire, isBuiltin } from "node:module";

const require = createRequire(import.meta.url);
const { basename } = require("node:path");
console.log(basename("/srv/app/main.js"));
console.log(isBuiltin("node:fs"), isBuiltin("fs/promises"), isBuiltin("left-pad"));
console.log(builtinModules.includes("worker_threads"));
```

`elide run module.mjs` prints:

```text
main.js
true true false
true
```

## Differences from Node

- `createRequire` returns the realm's `require`; relative paths do not resolve against the filename passed to it.
- `syncBuiltinESMExports()` is a no-op.
- `findSourceMap()` returns `undefined`; `getSourceMapsSupport()` reports source maps disabled.
- Loader customization hooks (`register`) are not supported.
- `require.resolve()` returns the specifier unchanged for built-ins.

<!-- api-reference:start 8bff62175485 -->
## Reference

**Status:** Partial · 45 of 52 suite tests pass (86.5%)

### `module` exports

`Module`, `builtinModules`, `createRequire`, `findSourceMap`, `getSourceMapsSupport`, `globalPaths`, `isBuiltin`, `runMain`, `setSourceMapsSupport`, `syncBuiltinESMExports`, `wrap`, `wrapper`

### Not implemented

`SourceMap`, `constants`, `enableCompileCache`, `findPackageJSON`, `flushCompileCache`, `getCompileCacheDir`, `register`, `registerHooks`, `stripTypeScriptTypes`.

**Tests:** [node-api `node:module-loading`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 45 pass, 7 fail, 0 error, 5 skipped. Failing: `test-module-loading-globalpaths.js`, `test-module-main-fail.js`, `test-module-main-preserve-symlinks-fail.js`, `test-module-prototype-mutation.js`, `test-module-run-main-monkey-patch.js`, `test-require-package-map.js`, `test-require-symlink.js`.
<!-- api-reference:end -->

---

# node:net

URL: https://elide.help/docs/api-node-net

> How Elide supports Node's `net` module: TCP and Unix-domain servers and clients, BlockList, SocketAddress and isIP match Node, with sandbox network flags.

`node:net` matches [Node's `net`](https://nodejs.org/api/net.html) for TCP and Unix-domain servers and clients,
`BlockList`, `SocketAddress`, and the `isIP` helpers; `--allow-net` and `--deny-net` apply under the
[sandbox](https://elide.help/docs/sandbox).

## Example

```js
// net.mjs
import net from "node:net";

const server = net.createServer((socket) => socket.pipe(socket));
server.listen(0, "127.0.0.1", () => {
  const client = net.connect(server.address().port, "127.0.0.1", () => client.end("ping"));
  client.on("data", (data) => console.log("echo:", data.toString()));
  client.on("close", () => server.close(() => console.log("server closed")));
});
console.log(net.isIP("::1"), net.isIPv4("127.0.0.1"));
```

`elide run net.mjs` prints:

```text
6 true
echo: ping
server closed
```

<!-- api-reference:start 13690a705d0b -->
## Reference

**Status:** Partial · Not measured

### `net` exports

`BlockList`, `Server`, `Socket`, `SocketAddress`, `Stream`, `connect`, `createConnection`, `createServer`, `getDefaultAutoSelectFamily`, `getDefaultAutoSelectFamilyAttemptTimeout`, `isIP`, `isIPv4`, `isIPv6`, `setDefaultAutoSelectFamily`, `setDefaultAutoSelectFamilyAttemptTimeout`

### Not implemented

`BoundSocket`.
<!-- api-reference:end -->

---

# node:os

URL: https://elide.help/docs/api-node-os

> How Elide supports Node's `os` module: it matches Node, except that `cpus()` reports each core's model and speed with every `times` field set to zero.

`node:os` matches [Node's `os`](https://nodejs.org/api/os.html).

## Example

```js
// os.mjs
import os from "node:os";

console.log(JSON.stringify(os.EOL), os.devNull);
console.log(os.constants.signals.SIGTERM, os.constants.errno.ENOENT);
console.log(os.availableParallelism() > 0, os.cpus().length > 0);
console.log(typeof os.totalmem(), typeof os.homedir(), os.endianness());
```

`elide run os.mjs` prints:

```text
"\n" /dev/null
15 2
true true
number string LE
```

## Differences from Node

- `cpus()` reports each core's model and speed; every `times` field is zero.

<!-- api-reference:start 2dc4febf64c9 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `arch()` | function | Full | Returns the CPU architecture of the process (e.g. "x64", "arm64") |
| `cpus()` | function | Full | Returns an array of objects describing each logical CPU core |
| `endianness()` | function | Full | Returns the endianness of the CPU: "BE" (big-endian) or "LE" (little-endian) |
| `freemem()` | function | Full | Returns the amount of free system memory in bytes |
| `homedir()` | function | Full | Returns the current user's home directory path |
| `hostname()` | function | Full | Returns the host name of the operating system |
| `loadavg()` | function | Full | Returns the 1, 5, and 15-minute system load averages |
| `networkInterfaces()` | function | Full | Returns an object mapping interface names to their address entries |
| `platform()` | function | Full | Returns the operating system platform (e.g. "linux", "darwin", "win32") |
| `release()` | function | Full | Returns the OS release version string |
| `tmpdir()` | function | Full | Returns the operating system's default directory for temporary files |
| `totalmem()` | function | Full | Returns the total amount of system memory in bytes |
| `type()` | function | Full | Returns the OS name (e.g. "Linux", "Darwin", "Windows_NT") |
| `uptime()` | function | Full | Returns the system uptime in seconds |
| `userInfo()` | function | Full | Returns information about the currently effective user |
| `machine()` | function | Full | Returns the machine type as a string, such as "arm64", "x86_64", etc |
| `version()` | function | Full | Returns the operating system kernel version string |
| `availableParallelism()` | function | Full | Returns an estimate of the default amount of parallelism a program should use, respecting cgroups and CPU… |
| `getPriority()` | function | Full | Returns the scheduling priority for the process specified by pid |
| `setPriority()` | function | Full | Sets the scheduling priority for the process specified by pid |
| `EOL` | property | Full | The operating system end-of-line character sequence (`\n` on POSIX, `\r\n` on Windows) |
| `devNull` | property | Full | The null device path (`/dev/null` on POSIX, `\\.\nul` on Windows) |
| `constants` | property | Full | Object containing signal, errno, dlopen, and priority constants |
| `os.constants.signals` | constant | Full | `SIGHUP`, `SIGINT`, `SIGQUIT`, `SIGILL`, `SIGTRAP`, `SIGABRT` and 27 more |
| `os.constants.errno` | constant | Full | `EPERM`, `ENOENT`, `ESRCH`, `EINTR`, `EIO`, `ENXIO` and 81 more |
| `os.constants.dlopen` | constant | Full | `RTLD_LAZY`, `RTLD_NOW`, `RTLD_GLOBAL`, `RTLD_LOCAL`, `RTLD_DEEPBIND` |
| `os.constants.priority` | constant | Full | `PRIORITY_LOW`, `PRIORITY_BELOW_NORMAL`, `PRIORITY_NORMAL`, `PRIORITY_ABOVE_NORMAL`, `PRIORITY_HIGH`, `PRIORITY_HIGHEST` |
| `os.constants` | constant | Full | `UV_UDP_REUSEADDR` |
<!-- api-reference:end -->

---

# node:path

URL: https://elide.help/docs/api-node-path

> How Elide supports Node's `path` module: `node:path`, `node:path/posix` and `node:path/win32` match Node on every host, including `matchesGlob`.

`node:path`, `node:path/posix`, and `node:path/win32` match [Node's `path`](https://nodejs.org/api/path.html) on every
host, including `matchesGlob`.

## Example

```js
// path.mjs
import path from "node:path";

console.log(path.join("/srv", "app", "../static", "index.html"));
console.log(JSON.stringify(path.parse("/srv/static/index.html")));
console.log(path.relative("/srv/app", "/srv/static"));
console.log(path.win32.join("C:\\srv", "app"));
console.log(path.matchesGlob("src/lib/main.ts", "src/**/*.ts"));
```

`elide run path.mjs` prints:

```text
/srv/static/index.html
{"root":"/","dir":"/srv/static","base":"index.html","ext":".html","name":"index"}
../static
C:\srv\app
true
```

<!-- api-reference:start 6494bb97f0da -->
## Reference

**Status:** Full · 16 of 16 suite tests pass (100.0%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `basename()` | function | Full | Return the last portion of a path, optionally removing a suffix |
| `dirname()` | function | Full | Return the directory name of a path |
| `extname()` | function | Full | Return the extension of the path, from the last '.' to end of string |
| `format()` | function | Full | Returns a path string from an object (the opposite of path.parse()) |
| `isAbsolute()` | function | Full | Determines whether path is an absolute path |
| `join()` | function | Full | Join all arguments together and normalize the resulting path |
| `normalize()` | function | Full | Normalize a path, resolving '..' and '.' segments |
| `parse()` | function | Full | Returns an object whose properties represent significant elements of the path |
| `relative()` | function | Full | Returns the relative path from 'from' to 'to' |
| `resolve()` | function | Full | Resolve a sequence of paths into an absolute path |
| `toNamespacedPath()` | function | Full | Returns an equivalent namespace-prefixed path (Windows only; no-op on POSIX) |
| `matchesGlob()` | function | Full | Returns true if the path matches the given glob pattern |
| `sep` | property | Full | The platform-specific path segment separator |
| `delimiter` | property | Full | The platform-specific path delimiter |
| `posix` | property | Full | Provides access to POSIX specific implementations of the path methods |
| `win32` | property | Full | Provides access to Windows specific implementations of the path methods |

**Tests:** [node-api `node:path`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 16 pass, 0 fail, 0 error, 1 skipped.
<!-- api-reference:end -->

---

# node:perf_hooks

URL: https://elide.help/docs/api-node-perf-hooks

> How Elide supports Node's `perf_hooks`: it shares one timeline with the Web performance globals; `constants` is empty and resource timing is absent.

`node:perf_hooks` follows [Node's `perf_hooks`](https://nodejs.org/api/perf_hooks.html); its `performance` and
constructors are the same objects as the [Performance globals](https://elide.help/docs/api-wintercg-performance).

## Example

```js
// perf.mjs
import { PerformanceObserver, performance } from "node:perf_hooks";

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) console.log(entry.entryType, entry.name, entry.duration >= 0);
  observer.disconnect();
});
observer.observe({ entryTypes: ["measure"] });

performance.mark("start");
for (let i = 0; i < 1e5; i++);
performance.mark("end");
performance.measure("loop", "start", "end");
console.log(performance.getEntriesByType("mark").map((mark) => mark.name).join());
```

`elide run perf.mjs` prints:

```text
start,end
measure loop true
```

## Differences from Node

- `constants` is an empty object.
- `PerformanceResourceTiming` is absent.
- `nodeTiming.v8Start`, `environment`, `loopExit`, and `idleTime` are zero.

<!-- api-reference:start f36df59483d9 -->
## Reference

**Status:** Partial · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `PerformanceEntry` | class | Full | `name`, `entryType`, `startTime`, `duration`, `detail`, `toJSON()` |
| `PerformanceMark` | class | Full |  |
| `PerformanceMeasure` | class | Full |  |
| `PerformanceNodeTiming` | class | Full | `nodeStart`, `v8Start`, `environment`, `bootstrapComplete`, `loopStart`, `loopExit`, `idleTime` |
| `PerformanceObserverEntryList` | class | Full | `getEntries()`, `getEntriesByName()`, `getEntriesByType()` |
| `PerformanceObserver` | class | Full | `observe()`, `disconnect()`, `takeRecords()`, `PerformanceObserver.supportedEntryTypes` |
| `now()` | function | Full | Returns the current high-resolution millisecond timestamp relative to timeOrigin |
| `mark()` | function | Full | Creates a performance mark with the given name |
| `measure()` | function | Full | Creates a performance measure between two marks or timestamps |
| `getEntries()` | function | Full | Returns a list of all performance entries |
| `getEntriesByName()` | function | Full | Returns performance entries filtered by name |
| `getEntriesByType()` | function | Full | Returns performance entries filtered by type ("mark" or "measure") |
| `clearMarks()` | function | Full | Removes all marks, or only marks with the given name |
| `clearMeasures()` | function | Full | Removes all measures, or only measures with the given name |
| `timeOrigin` | property | Full | The high-resolution millisecond timestamp at which the process started |
| `nodeTiming` | property | Full | Timing information about the Node.js process lifecycle |

### Not implemented

`Performance`, `PerformanceResourceTiming`.
<!-- api-reference:end -->

---

# node:querystring

URL: https://elide.help/docs/api-node-querystring

> How Elide supports Node's legacy `querystring` module for parsing and formatting query strings: it matches Node; prefer URLSearchParams in new code.

`node:querystring` matches [Node's `querystring`](https://nodejs.org/api/querystring.html); use `URLSearchParams` in
new code.

## Example

```js
// qs.mjs
import querystring from "node:querystring";

const parsed = querystring.parse("tag=a&tag=b&q=hello%20world");
console.log(JSON.stringify(parsed));
console.log(querystring.stringify({ q: "café & co", page: 2 }));
console.log(querystring.escape("a b"), querystring.unescape("a%20b"));
```

`elide run qs.mjs` prints:

```text
{"tag":["a","b"],"q":"hello world"}
q=caf%C3%A9%20%26%20co&page=2
a%20b a b
```

<!-- api-reference:start 533f2f2ddc1e -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `parse()` | function | Full | Parses a URL query string into a key-value object |
| `stringify()` | function | Full | Serializes an object into a URL query string |
| `escape()` | function | Full | Percent-encodes a string for use in a query string |
| `unescape()` | function | Full | Decodes a percent-encoded query string component |
| `encode()` | function | Full | Alias for stringify(); serializes an object into a query string |
| `decode()` | function | Full | Alias for parse(); parses a query string into a key-value object |
<!-- api-reference:end -->

---

# node:stream

URL: https://elide.help/docs/api-node-stream

> How Elide supports Node's `stream`, `stream/promises` and `stream/consumers`, with `stream/web` as the WHATWG stream globals and a `stream/iter` extension.

`node:stream`, `node:stream/promises`, and `node:stream/consumers` match
[Node's streams](https://nodejs.org/api/stream.html).

## Example

```js
// stream.mjs
import { Readable, Transform, Writable } from "node:stream";
import { pipeline } from "node:stream/promises";

const upper = new Transform({
  transform(chunk, _encoding, done) {
    done(null, chunk.toString().toUpperCase());
  },
});
const lines = [];
const sink = new Writable({
  write(chunk, _encoding, done) {
    lines.push(chunk.toString());
    done();
  },
});

await pipeline(Readable.from(["alpha", "beta", "gamma"]), upper, sink);
console.log(lines.join(" "));
```

`elide run stream.mjs` prints:

```text
ALPHA BETA GAMMA
```

## Differences from Node

- `node:stream/web` classes are the same objects as the [WHATWG stream](https://elide.help/docs/api-whatwg-streams) globals.
- `node:stream/iter` is an Elide extension with iterator conversion helpers.

## Samples

- [Streams and async iteration](https://elide.help/docs/code-samples#streams-and-async-iteration)
- [Transform stream pipeline](https://elide.help/docs/code-samples#transform-stream-pipeline)

<!-- api-reference:start 00c6c2800d9b -->
## Reference

**Status:** Partial · 215 of 238 suite tests pass (90.3%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Readable` | class | Full | `readable`, `readableEnded`, `readableFlowing`, `readableHighWaterMark`, `readableLength`, `readableObjectMode`, `readableEncoding`, `destroyed`, `read()`, `setEncoding()`, `pause()`, `resume()`, `isPaused()`, `unpipe()`, `unshift()`, `wrap()`, `push()`, `destroy()`, `pipe()`, `toArray()`, `forEach()`, `some()`, `every()`, `find()`, `reduce()`, `map()`, `filter()`, `flatMap()`, `drop()`, `take()` |
| `Writable` | class | Full | `writable`, `writableEnded`, `writableFinished`, `writableHighWaterMark`, `writableLength`, `writableObjectMode`, `writableCorked`, `destroyed`, `write()`, `end()`, `cork()`, `uncork()`, `destroy()`, `setDefaultEncoding()` |
| `Duplex` | class | Full | `writable`, `writableEnded`, `writableFinished`, `writableHighWaterMark`, `writableLength`, `writableObjectMode`, `writableCorked`, `write()`, `end()`, `cork()`, `uncork()`, `setDefaultEncoding()` |
| `Transform` | class | Full |  |
| `PassThrough` | class | Full |  |
| `Readable` | property | Full | The Readable stream class |
| `Writable` | property | Full | The Writable stream class |
| `Duplex` | property | Full | The Duplex stream class |
| `Transform` | property | Full | The Transform stream class |
| `PassThrough` | property | Full | The PassThrough stream class |
| `pipeline` | property | Full | Promise-based pipeline() utility for composing stream pipelines with error propagation |
| `finished` | property | Full | Promise-based finished() utility that resolves/rejects when a stream completes or errors |
| `compose` | property | Full | Composes streams into a single Duplex; pipes them and returns a Duplex that writes to the head and reads… |

### Not implemented

`stream/web.ReadableStreamTee`.

**Tests:** [node-api `node:streams`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 215 pass, 22 fail, 1 error, 9 skipped. Failing: `test-stream-auto-destroy.js`, `test-stream-compose.js`, `test-stream-consumers.js`, `test-stream-destroy.js`, `test-stream-duplex-from.js`, `test-stream-duplex.js`, `test-stream-iter-disabled.js`, `test-stream-iter-readable-interop-disabled.js`, and 15 more.
<!-- api-reference:end -->

---

# node:test

URL: https://elide.help/docs/api-node-test

> How Elide supports Node's `test` runner API: tests, suites, hooks and mocks run with `elide test`; `run()`, `mock.module()` and snapshots are unavailable.

`node:test` provides [Node's test runner API](https://nodejs.org/api/test.html) (tests, suites, hooks, test context,
and mocks). Run test files with `elide test`.

## Example

```js
// math.test.mjs
import assert from "node:assert/strict";
import { describe, it, mock } from "node:test";

describe("math", () => {
  it("adds", () => {
    assert.equal(1 + 2, 3);
  });

  it("calls the callback once", () => {
    const callback = mock.fn();
    [1].forEach(callback);
    assert.equal(callback.mock.callCount(), 1);
  });
});
```

`elide test ./math.test.mjs` prints:

```text
math.test.mjs
✓ math > adds [1ms]
✓ math > calls the callback once

 2 pass
 0 skip
 0 fail
Ran 2 tests across one file. (0.01s)
```

## Differences from Node

- `elide run` registers tests without running them and prints the `elide test` command to use.
- `run()`, `mock.module()`, and the `snapshot` serializer setters throw `ERR_METHOD_NOT_IMPLEMENTED`.
- Snapshot assertions are not available.

## Samples

- [TypeScript tests](https://elide.help/docs/code-samples#typescript-tests)

<!-- api-reference:start c3c2a6313f8a -->
## Reference

**Status:** Partial · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `test()` | function | Full | Define and run a test case |
| `it()` | function | Full | Alias for test() |
| `describe()` | function | Full | Group tests into a suite |
| `suite()` | function | Full | Alias for describe() |
| `before()` | function | Full | Register a function to run before all tests in the current suite |
| `after()` | function | Full | Register a function to run after all tests in the current suite |
| `beforeEach()` | function | Full | Register a function to run before each test in the current suite |
| `afterEach()` | function | Full | Register a function to run after each test in the current suite |
| `mock` | property | Full | The mock object for creating spies and mocking timers |

### Not implemented

`expectFailure`, `getTestContext`.
<!-- api-reference:end -->

---

# node:timers

URL: https://elide.help/docs/api-node-timers

> How Elide supports Node's `timers` and `timers/promises` modules: they match Node, including scheduler; `active()` and `unenroll()` are not exposed.

`node:timers` and `node:timers/promises` match [Node's `timers`](https://nodejs.org/api/timers.html), including
`scheduler` and `AbortSignal` support; ordering is covered under [Timers](https://elide.help/docs/api-html-timers).

## Example

```js
// timers.mjs
import { setInterval, setTimeout as sleep } from "node:timers/promises";

console.log(await sleep(10, "woke"));

let ticks = 0;
for await (const _ of setInterval(5)) {
  if (++ticks === 3) break;
}
console.log("ticks", ticks);

const controller = new AbortController();
const pending = sleep(60_000, null, { signal: controller.signal });
controller.abort();
await pending.catch((error) => console.log(error.name));
```

`elide run timers.mjs` prints:

```text
woke
ticks 3
AbortError
```

## Differences from Node

- `node:timers` functions are not the same objects as the timer globals.
- `active()` and `unenroll()` are not exposed.

<!-- api-reference:start 6e1b45e455f6 -->
## Reference

**Status:** Full · 54 of 57 suite tests pass (94.7%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `setTimeout()` | function | Full | Schedules a callback to be invoked once after `delay` milliseconds |
| `clearTimeout()` | function | Full | Cancels a timeout previously established by setTimeout() |
| `setInterval()` | function | Full | Schedules a callback to be invoked repeatedly every `delay` milliseconds |
| `clearInterval()` | function | Full | Cancels an interval previously established by setInterval() |
| `setImmediate()` | function | Full | Schedules a callback to be invoked asynchronously "immediately" (after I/O events but before timers… |
| `clearImmediate()` | function | Full | Cancels an immediate action previously established by setImmediate() |

**Tests:** [node-api `node:timers`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 54 pass, 3 fail, 0 error, 10 skipped. Failing: `test-timers-max-duration-warning.js`, `test-timers-timeout-to-interval.js`, `test-timers-unenroll-unref-interval.js`.
<!-- api-reference:end -->

---

# node:url

URL: https://elide.help/docs/api-node-url

> How Elide supports Node's `url` module: legacy parse, format and resolve, file-URL helpers, and the global URL, URLSearchParams and URLPattern classes.

`node:url` matches [Node's `url`](https://nodejs.org/api/url.html): legacy `parse`, `format`, and `resolve` plus
file-URL helpers; its `URL`, `URLSearchParams`, and `URLPattern` are the global [`URL`](https://elide.help/docs/api-whatwg-url),
[`URLSearchParams`](https://elide.help/docs/api-whatwg-url#urlsearchparams), and [`URLPattern`](https://elide.help/docs/api-whatwg-urlpattern).

## Example

```js
// url.mjs
import { fileURLToPath, format, pathToFileURL } from "node:url";

console.log(pathToFileURL("/tmp/report 1.txt").href);
console.log(fileURLToPath("file:///tmp/report%201.txt"));
console.log(format(new URL("https://user:pw@example.com/a?b=1#top"), { auth: false, fragment: false }));
```

`elide run url.mjs` prints:

```text
file:///tmp/report%201.txt
/tmp/report 1.txt
https://example.com/a?b=1
```

<!-- api-reference:start d3778894af08 -->
## Reference

**Status:** Full · 40 of 42 suite tests pass (95.2%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `parse()` | function | Full | Parses a URL string into a UrlObject (legacy API) |
| `format()` | function | Full | Formats a URL object or WHATWG URL back into a string |
| `resolve()` | function | Full | Resolves a target URL relative to a base URL (legacy API) |
| `URL` | property | Full | The WHATWG URL class (same as global URL) |
| `URLSearchParams` | property | Full | The WHATWG URLSearchParams class (same as global URLSearchParams) |
| `domainToASCII()` | function | Full | Converts a Unicode domain name to its ASCII (Punycode) representation |
| `domainToUnicode()` | function | Full | Converts an ASCII (Punycode) domain name to Unicode |
| `fileURLToPath()` | function | Full | Converts a file: URL to a filesystem path string |
| `pathToFileURL()` | function | Full | Converts an absolute filesystem path to a file: URL |
| `urlToHttpOptions()` | function | Full | Returns an object with URL components suitable for use with http.request() |
| `resolveObject()` | function | Full | Resolves a relative URL against a source URL object, similar to a browser resolving an anchor tag |

**Tests:** [node-api `node:url`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 40 pass, 2 fail, 0 error, 3 skipped. Failing: `test-whatwg-url-custom-inspect.js`, `test-whatwg-url-custom-parsing.js`.
<!-- api-reference:end -->

---

# node:util

URL: https://elide.help/docs/api-node-util

> How Elide supports Node's `util` and `util/types`: format, inspect, promisify, parseArgs and the type predicates, and the inspect options and functions that are missing.

`node:util` and `node:util/types` provide [Node's utilities](https://nodejs.org/api/util.html), including `format`,
`inspect`, `promisify`, `parseArgs`, `parseEnv`, `styleText`, `MIMEType` and the `types` predicates; `node:sys` returns
the same object.

## Example

```js
// util.mjs
import { format, inspect, isDeepStrictEqual, parseArgs, types } from "node:util";

console.log(format("%s has %d items", "cart", 3));
console.log(inspect({ tags: new Set(["a", "b"]), nested: { deep: { deeper: {} } } }, { depth: 0 }));

const { values, positionals } = parseArgs({
  args: ["--port", "8080", "-v", "app.js"],
  options: { port: { type: "string" }, verbose: { type: "boolean", short: "v" } },
  allowPositionals: true,
});
console.log(values.port, values.verbose, positionals.join());
console.log(types.isPromise(Promise.resolve()), isDeepStrictEqual({ a: [1] }, { a: [1] }));
```

`elide run util.mjs` prints:

```text
cart has 3 items
{ tags: [Set], nested: [Object] }
8080 true app.js
true true
```

## Differences from Node

- `inspect` ignores `numericSeparator` and `getters`, and does not color regular expressions.
- `getCallSites()` calls a user-defined `Error.prepareStackTrace`.
- `diff()` is missing; `toUSVString()` and `log()` throw `ERR_METHOD_NOT_IMPLEMENTED`.
- `util.types` predicates are non-enumerable; list them with `Object.getOwnPropertyNames(util.types)`.

<!-- api-reference:start 882dc6af0216 -->
## Reference

**Status:** Partial · 9 of 18 suite tests pass (50.0%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `format()` | function | Full | Formats a string using printf-style substitution patterns (%s, %d, %o, etc.) |
| `formatWithOptions()` | function | Full | Like format(), but accepts an explicit util.inspect options object for the first argument |
| `inspect()` | function | Full | Returns a string representation of an object for debugging |
| `promisify()` | function | Full | Wraps a callback-based function so it returns a Promise |
| `inherits()` | function | Full | Sets up prototype inheritance between a constructor and a superclass |
| `isDeepStrictEqual()` | function | Full | Returns true if two values are deeply equal using the strict equality algorithm |
| `deprecate()` | function | Full | Wraps a function to emit a deprecation warning when called |
| `debuglog()` | function | Full | Returns a logging function that writes to stderr only if the NODE_DEBUG env variable includes section |
| `callbackify()` | function | Full | Wraps an async function (or a function that returns a Promise) so it follows the error-first callback… |
| `getSystemErrorName()` | function | Full | Returns the string name for a numeric error code (the errno value) |
| `getSystemErrorMessage()` | function | Full | Returns the string message for a numeric error code (the errno value) |
| `getSystemErrorMap()` | function | Full | Returns a Map of all system error codes to [name, message] pairs |
| `toUSVString()` | function | Full | Returns a string after replacing any lone surrogates with the Unicode replacement character U+FFFD |
| `stripVTControlCharacters()` | function | Full | Removes ANSI escape codes (including color and cursor movement) from a string |
| `styleText()` | function | Full | Formats text with ANSI styling for terminal output |
| `getCallSites()` | function | Full | Returns an array of call site objects representing the current call stack |
| `parseEnv()` | function | Full | Parses a .env file content string into a key-value object |
| `log()` | function | Full | Writes a formatted timestamp + message to stdout (similar to console.log but with a timestamp) |
| `types` | property | Full | Object with type-checking predicates (e.g. util.types.isDate, util.types.isMap) |
| `TextEncoder` | property | Full | The WHATWG TextEncoder class |
| `TextDecoder` | property | Full | The WHATWG TextDecoder class |

### Not implemented

`convertProcessSignalToExitCode`, `debug`, `diff`, `isArray`, `setTraceSigInt`, `transferableAbortController`, `transferableAbortSignal`.

**Tests:** [node-api `node:util`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 9 pass, 8 fail, 1 error, 12 skipped. Failing: `test-util-callbackify.js`, `test-util-format.js`, `test-util-getcallsites-preparestacktrace.js`, `test-util-getcallsites-sourcemap.js`, `test-util-inspect-getters-accessing-this.js`, `test-util-inspect-long-running.js`, `test-util-inspect-namespace.js`, `test-util-inspect-regexp.js`, and 1 more.
<!-- api-reference:end -->

---

# node:v8

URL: https://elide.help/docs/api-node-v8

> How Elide supports Node's `v8` module: six exports, including heap statistics and a JSON-based `serialize` that is not V8's structured-clone format.

`node:v8` exports six members of [Node's `v8`](https://nodejs.org/api/v8.html).

## Example

```js
// v8.mjs
import v8 from "node:v8";

const bytes = v8.serialize({ id: 7, tags: ["a"] });
console.log(JSON.stringify(v8.deserialize(bytes)));
const heap = v8.getHeapStatistics();
console.log(heap.used_heap_size > 0, heap.total_heap_size >= heap.used_heap_size);
console.log(typeof v8.cachedDataVersionTag());
```

`elide run v8.mjs` prints:

```text
{"id":7,"tags":["a"]}
true true
number
```

## Differences from Node

Only these members are exported:

| Operation | Behavior |
|---|---|
| `cachedDataVersionTag()` | Returns a stable 32-bit tag for the running binary. |
| `getHeapStatistics()` | Returns a heap-statistics object in Node's format. |
| `getHeapSpaceStatistics()` | Returns one entry per memory pool, with names such as `eden space`. |
| `setFlagsFromString(flags)` | Accepts a string and has no effect. |
| `serialize(value)` | Encodes `JSON.stringify(value)` as UTF-8 in a `Uint8Array`. |
| `deserialize(buffer)` | Decodes UTF-8 and parses the JSON. |

`serialize` output is not V8's structured-clone format; circular objects throw `TypeError`.

<!-- api-reference:start 51935d7f798e -->
## Reference

**Status:** Partial · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `getHeapStatistics()` | function | Full | Returns an object with V8 heap statistics |
| `getHeapSpaceStatistics()` | function | Full | Returns statistics about V8 heap spaces |
| `setFlagsFromString()` | function | Full | Set additional V8 command-line flags |
| `serialize()` | function | Full | Serializes a value into a buffer |
| `deserialize()` | function | Full | Reads a value written by serialize() from a buffer |

### Not implemented

`DefaultDeserializer`, `DefaultSerializer`, `Deserializer`, `GCProfiler`, `Serializer`, `getCppHeapStatistics`, `getHeapCodeStatistics`, `getHeapSnapshot`, `isStringOneByteRepresentation`, `promiseHooks`, `queryObjects`, `setHeapSnapshotNearHeapLimit`, `startCpuProfile`, `startHeapProfile`, `startupSnapshot`, `stopCoverage`, `takeCoverage`, `writeHeapSnapshot`.
<!-- api-reference:end -->

---

# node:vm

URL: https://elide.help/docs/api-node-vm

> How Elide supports Node's `vm` module: Script, createContext, compileFunction and runIn*Context, and where contexts, code-generation options and modules differ.

`node:vm` provides `Script`, `createContext`, `compileFunction`, `runInContext`, `runInNewContext` and
`runInThisContext` from [Node's `vm`](https://nodejs.org/api/vm.html), including the `timeout` option.

## Example

```js
// vm.mjs
import vm from "node:vm";

const context = vm.createContext({ price: 20, qty: 3 });
console.log(vm.runInContext("price * qty", context));

const script = new vm.Script("count = (typeof count === 'number' ? count : 0) + 1");
script.runInContext(context);
script.runInContext(context);
console.log(context.count);

try {
  vm.runInNewContext("while (true) {}", {}, { timeout: 50 });
} catch (error) {
  console.log(error.code);
}
```

`elide run vm.mjs` prints:

```text
60
2
ERR_SCRIPT_EXECUTION_TIMEOUT
```

## Differences from Node

- A context shares intrinsics (`Symbol`, `Proxy`, `Object`) with the host realm; it is not a security boundary.
- `codeGeneration: { strings: false }` is not enforced; `eval` still runs in the context.
- `vm.constants.DONT_CONTEXTIFY` is rejected by `createContext`.
- `SyntaxError` messages use different wording, such as `Expected eof but found }`.
- `SourceTextModule` emits an `ExperimentalWarning` and does not support full linking and evaluation.

<!-- api-reference:start 42fec8d5a69b -->
## Reference

**Status:** Full · 80 of 95 suite tests pass (84.2%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Script` | class | Full | `runInThisContext()`, `runInNewContext()` |
| `createContext()` | function | Full | Creates a new execution context (sandbox) |
| `runInNewContext()` | function | Full | Compiles code, creates a new context, and runs the code in that context |
| `runInThisContext()` | function | Full | Compiles and runs code within the current global context |
| `isContext()` | function | Full | Returns whether the given object is a contextified sandbox |

**Tests:** [node-api `node:vm`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 80 pass, 15 fail, 0 error, 3 skipped. Failing: `test-vm-basic.js`, `test-vm-codegen.js`, `test-vm-context-dont-contextify.js`, `test-vm-function-declaration.js`, `test-vm-global-property-prototype.js`, `test-vm-global-setter.js`, `test-vm-harmony-symbols.js`, `test-vm-module-after-evaluate.js`, and 7 more.
<!-- api-reference:end -->

---

# node:worker_threads

URL: https://elide.help/docs/api-node-worker-threads

> How Elide supports Node's `worker_threads`: Worker, parentPort, MessageChannel and the other exports, which Worker options it reads, and other differences.

`node:worker_threads` runs scripts on separate threads with
[Node's `worker_threads`](https://nodejs.org/api/worker_threads.html) API. `elide run` does not exit while a worker
runs.

## Example

```js
// worker.mjs
import { Worker } from "node:worker_threads";

const source = `
  const { parentPort, workerData } = require("node:worker_threads");
  parentPort.postMessage(workerData.map((n) => n * n));
`;
const worker = new Worker(source, { eval: true, workerData: [1, 2, 3] });
worker.on("message", (squares) => {
  console.log("from worker:", squares.join(" "));
  worker.terminate();
});
worker.on("exit", (code) => console.log("worker exited", code));
```

`elide run worker.mjs` prints:

```text
from worker: 1 4 9
worker exited 0
```

## Differences from Node

- `new Worker` reads only the `workerData`, `eval`, `transferList`, and `env` options.
- A missing script file emits `error` with code `ERR_WORKER_PATH`.
- `stdout` and `stderr` are always inherited from the parent.
- `resourceLimits` is `{}`.
- Posting a `ReadableStream` throws `DataCloneError`.
- Posting to a terminated worker is a no-op.
- `--limit=workers=COUNT` limits how many workers a script may start; see [Sandbox](https://elide.help/docs/sandbox).

## Samples

- [Worker threads](https://elide.help/docs/code-samples#worker-threads)
- [Limit workers](https://elide.help/docs/code-samples#limit-workers)

<!-- api-reference:start e349d4a46a33 -->
## Reference

**Status:** Partial · 105 of 128 suite tests pass (82.0%)

### `worker_threads` exports

`BroadcastChannel`, `MessageChannel`, `MessagePort`, `Worker`, `getEnvironmentData`, `isInternalThread`, `isMainThread`, `isMarkedAsUntransferable`, `markAsUncloneable`, `markAsUntransferable`, `moveMessagePortToContext`, `parentPort`, `postMessageToThread`, `receiveMessageOnPort`, `resourceLimits`, `setEnvironmentData`, `threadId`, `threadName`, `workerData`, 1 constants such as `SHARE_ENV`

### Not implemented

`locks`.

**Tests:** [node-api `node:worker-threads`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/node-api/node-api.md): 105 pass, 22 fail, 1 error, 11 skipped. Failing: `test-worker-cleanup-handles.js`, `test-worker-cpu-profile.js`, `test-worker-data-url.js`, `test-worker-eval-typescript.js`, `test-worker-exit-heapsnapshot.js`, `test-worker-heap-profile.js`, `test-worker-heap-snapshot.js`, `test-worker-heapdump-failure.js`, and 15 more.
<!-- api-reference:end -->

---

# node:zlib

URL: https://elide.help/docs/api-node-zlib

> How Elide supports Node's `zlib` module: Deflate, Gzip, Brotli, Zstandard and crc32 match Node, plus the `node:zlib/iter` async-iterator extension.

`node:zlib` follows [Node's `zlib`](https://nodejs.org/api/zlib.html), including Brotli, Zstandard, and `crc32`. For
Web Streams, use [Compression Streams](https://elide.help/docs/api-whatwg-compression).

## Example

```js
// zlib.mjs
import { brotliCompressSync, crc32, gunzipSync, gzipSync, zstdCompressSync, zstdDecompressSync } from "node:zlib";

const text = "elide ".repeat(100);
const gz = gzipSync(text);
console.log(text.length, "->", gz.length, gunzipSync(gz).toString() === text);
console.log(zstdDecompressSync(zstdCompressSync(text)).toString().length);
console.log(brotliCompressSync(text).length < text.length, crc32("elide"));
```

`elide run zlib.mjs` prints:

```text
600 -> 35 true
600
true 2639236160
```

## Differences from Node

- Constants live only on `zlib.constants`; the top-level `Z_*`, `ZSTD_*` and mode aliases such as `zlib.Z_OK`
  are `undefined`.
- `node:zlib/iter` is an Elide extension. It exports `compress*` and `decompress*` factories (`Gzip`, `Deflate`,
  `DeflateRaw`, `Brotli`, `Zstd`, each with a `Sync` form) and the aliases `gzip`, `gunzip`, `deflate`, `inflate`,
  `deflateRaw`, and `inflateRaw`. Each factory's `.transform(asyncIterable)` yields batches of byte chunks, as in
  `for await (const batch of gzip().transform(input))`.

<!-- api-reference:start 1bb2678b653c -->
## Reference

**Status:** Partial · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `deflateSync()` | function | Full | Compress data using the deflate algorithm (RFC 1951 wrapped in zlib format RFC 1950) |
| `inflateSync()` | function | Full | Decompress data that was compressed with deflate (zlib format) |
| `deflateRawSync()` | function | Full | Compress data using the deflate algorithm in raw mode (no zlib header, RFC 1951) |
| `inflateRawSync()` | function | Full | Decompress raw deflate data (no zlib header) |
| `gzipSync()` | function | Full | Compress data using gzip (RFC 1952) |
| `gunzipSync()` | function | Full | Decompress gzip data (RFC 1952) |
| `brotliCompressSync()` | function | Full | Compress data using the Brotli algorithm (RFC 7932) |
| `brotliDecompressSync()` | function | Full | Decompress Brotli-compressed data (RFC 7932) |
| `unzipSync()` | function | Full | Decompress data with automatic format detection (gzip or deflate) |
| `constants` | property | Full | The `constants` object exposes zlib, Brotli, and Zstd numeric constants |
| top-level constants | constant | Partial | `Z_NO_COMPRESSION`, `Z_BEST_SPEED`, `Z_BEST_COMPRESSION`, `Z_DEFAULT_COMPRESSION`, `Z_FILTERED`, `Z_HUFFMAN_ONLY` and 73 more |

### Not implemented

107 top-level constants such as `DEFLATE`.
<!-- api-reference:end -->

---

# Compression streams

URL: https://elide.help/docs/api-whatwg-compression

> How Elide supports CompressionStream and DecompressionStream: gzip, deflate and deflate-raw per the standard, plus Brotli and Zstandard formats.

`CompressionStream` and `DecompressionStream` are globals from the
[Compression Streams Standard](https://compression.spec.whatwg.org/). They take a format: `gzip`, `deflate`
(zlib-wrapped), `deflate-raw`, `brotli`, or `zstd`.

## Example

```js
// compression.mjs
const input = new Blob(["elide ".repeat(100)]);
const compressed = await new Response(input.stream().pipeThrough(new CompressionStream("gzip"))).arrayBuffer();
console.log(input.size, "->", compressed.byteLength);

const restored = new Blob([compressed]).stream().pipeThrough(new DecompressionStream("gzip"));
console.log((await new Response(restored).text()).length);
```

`elide run compression.mjs` prints:

```text
600 -> 35
600
```

## Differences from browsers

- `brotli` and `zstd` are Elide additions.
- Formats are case-sensitive; an unknown format throws `TypeError`.
- Chunks must be `BufferSource` values.
- Malformed or truncated input rejects, as does decompressed output past a size limit.

For Buffer and callback APIs, see [node:zlib](https://elide.help/docs/api-node-zlib).

## Samples

- [Gzip with CompressionStream](https://elide.help/docs/code-samples#gzip-with-compressionstream)

<!-- api-reference:start a7589712fcbb -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `CompressionStream` | class | Full | `readable`, `writable` |
| `DecompressionStream` | class | Full | `readable`, `writable` |
<!-- api-reference:end -->

---

# DOM abort

URL: https://elide.help/docs/api-whatwg-dom-abort

> How Elide supports AbortController and AbortSignal per the DOM Standard, including abort(), any() and timeout(), and signals for fetch, timers and streams.

`AbortController` and `AbortSignal` are globals and follow the [DOM Standard](https://dom.spec.whatwg.org/), including
`AbortSignal.abort()`, `AbortSignal.any()`, `AbortSignal.timeout()`, and the `signal` option of `addEventListener`.
Fetch, timers, and streams accept a signal.

## Example

```js
// abort.mjs
const controller = new AbortController();
controller.signal.addEventListener("abort", () => console.log("aborted:", controller.signal.reason));
controller.abort("user cancelled");

const timeout = AbortSignal.timeout(10);
await new Promise((resolve) => timeout.addEventListener("abort", resolve));
console.log(timeout.reason.name);

const either = AbortSignal.any([new AbortController().signal, AbortSignal.abort("first")]);
console.log(either.aborted, either.reason);
```

`elide run abort.mjs` prints:

```text
aborted: user cancelled
TimeoutError
true first
```

<!-- api-reference:start 7c99b7b70225 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `AbortController` | class | Full | `signal`, `abort()` |
| `AbortSignal` | class | Full | `AbortSignal.abort()`, `AbortSignal.timeout()`, `AbortSignal.any()`, `aborted`, `reason`, `throwIfAborted()`, `onabort` |
<!-- api-reference:end -->

---

# DOM events

URL: https://elide.help/docs/api-whatwg-dom-events

> How Elide supports Event, CustomEvent and EventTarget: the DOM Standard without a DOM tree, so dispatch has one target and no capture or bubble phase.

`Event`, `CustomEvent`, and `EventTarget` are globals and follow the [DOM Standard](https://dom.spec.whatwg.org/).

## Example

```js
// domevents.mjs
const bus = new EventTarget();
bus.addEventListener("order", (event) => console.log("order", event.detail.id), { once: true });
bus.addEventListener("order", (event) => {
  event.preventDefault();
  console.log("cancelable", event.cancelable);
});

const event = new CustomEvent("order", { detail: { id: 7 }, cancelable: true });
console.log("dispatched", bus.dispatchEvent(event), event.defaultPrevented);
bus.dispatchEvent(new CustomEvent("order", { detail: { id: 8 } }));
```

`elide run domevents.mjs` prints:

```text
order 7
cancelable true
dispatched false true
cancelable false
```

## Differences from browsers

- There is no DOM tree: dispatch has one target and no capture or bubble phase.
- During dispatch, `eventPhase` is `Event.AT_TARGET` and `composedPath()` holds only the current target.
- A listener that throws is reported; the remaining listeners still run.

<!-- api-reference:start dcf40cee5081 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Event` | class | Full | `type`, `target`, `currentTarget`, `NONE`, `CAPTURING_PHASE`, `AT_TARGET`, `BUBBLING_PHASE`, `eventPhase`, `composedPath()`, `stopPropagation()`, `stopImmediatePropagation()`, `bubbles`, `cancelable`, `preventDefault()`, `defaultPrevented`, `composed`, `isTrusted`, `timeStamp`, `cancelBubble` |
| `CustomEvent` | class | Full | `detail` |
| `EventTarget` | class | Full | `addEventListener()`, `removeEventListener()`, `dispatchEvent()` |
<!-- api-reference:end -->

---

# Encoding

URL: https://elide.help/docs/api-whatwg-encoding

> How Elide supports TextEncoder, TextDecoder and their stream forms per the Encoding Standard, with UTF-8, UTF-16, legacy single-byte and CJK labels.

`TextEncoder`, `TextDecoder`, `TextEncoderStream`, and `TextDecoderStream` are globals and follow the
[Encoding Standard](https://encoding.spec.whatwg.org/). `TextDecoder` accepts the standard labels for UTF-8, UTF-16,
the legacy single-byte encodings, and the CJK encodings; an unknown label throws `RangeError`.

## Example

```js
// encoding.mjs
const bytes = new TextEncoder().encode("naïve ✓");
console.log(bytes.length, Array.from(bytes.slice(0, 4)).join(" "));
console.log(new TextDecoder().decode(bytes));

const latin1 = new Uint8Array([0x63, 0x61, 0x66, 0xe9]);
console.log(new TextDecoder("windows-1252").decode(latin1));

try {
  new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array([0xff]));
} catch (error) {
  console.log(error.name);
}
```

`elide run encoding.mjs` prints:

```text
10 110 97 195 175
naïve ✓
café
TypeError
```

<!-- api-reference:start 659216f7ebac -->
## Reference

**Status:** Full · 14,178 of 14,266 suite tests pass (99.4%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `TextDecoder` | class | Full | `encoding`, `fatal`, `ignoreBOM`, `decode()` |
| `TextEncoder` | class | Full | `encoding`, `encode()`, `encodeInto()` |

**Tests:** [wpt-wintertc `encoding`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/wpt-wintertc/wpt-wintertc.md): 14,178 pass, 86 fail, 2 error, 329 skipped. Failing: `encoding/encodeInto.any.js` (65), `encoding/textdecoder-streaming.any.js` (16), `encoding/streams/decode-bad-chunks.any.js` (2), `encoding/idlharness.any.js`, `encoding/single-byte-decoder.window.js`, `encoding/streams/decode-utf8.any.js`, `encoding/streams/realms.window.js`, `encoding/textdecoder-copy.any.js`.
<!-- api-reference:end -->

---

# Fetch

URL: https://elide.help/docs/api-whatwg-fetch

> How Elide supports fetch, Request, Response, Headers, FormData, Blob and File: supported URL schemes, no CORS or HTTP cache, the default User-Agent and response decompression.

`fetch`, `Blob`, `File`, `Headers`, `FormData`, `Request`, and `Response` are globals with the
[Fetch Standard](https://fetch.spec.whatwg.org/) API: bodies, streams, `clone()`, `Response.json()`, `AbortSignal`
and subresource integrity.

## Example

```js
// fetch.mjs
const form = new FormData();
form.append("name", "elide");
form.append("file", new File(["hello"], "hello.txt", { type: "text/plain" }));

const request = new Request("https://example.com/upload", { method: "POST", body: form });
console.log(request.method, request.headers.get("content-type").split(";")[0]);

const response = Response.json({ ok: true }, { status: 201, headers: { "x-id": "7" } });
console.log(response.status, response.headers.get("x-id"), JSON.stringify(await response.json()));

const blob = new Blob(["a", "b", "c"], { type: "text/plain" });
console.log(blob.size, await blob.slice(1).text());
```

`elide run fetch.mjs` prints:

```text
POST multipart/form-data
201 7 {"ok":true}
3 bc
```

## Differences from browsers

- `fetch` accepts `http:` and `https:` URLs; `data:` and `blob:` URLs reject with `unsupported URL scheme`.
- There is no origin: `mode`, `credentials`, `referrer` and `keepalive` are accepted and ignored, and no CORS
  checks, preflights, cookies or `Referer` headers are applied.
- Requests send `User-Agent: Elide/<version>` and `Accept: */*` unless you set those headers.
  `ELIDE_HTTP_USER_AGENT` changes the default user agent; its value must be printable ASCII.
- Gzip, deflate, Brotli, and Zstandard responses are decoded; response headers still describe the encoded body.
- An explicit `Accept-Encoding` header is sent as given; range requests default to `identity`.
- `fetch(url, { decompress: false })` sends `Accept-Encoding: identity` and returns any encoded body unchanged.
- A malformed compressed body rejects.
- There is no HTTP cache: conditional headers are sent as given, and a `304` has headers and no body.
- `Headers` applies the request, response, no-CORS and immutable guards; iteration lowercases and sorts names and
  keeps `Set-Cookie` values separate.
- Integrity checks buffer up to 100 MiB before the response resolves.
- HTTP/1.1, HTTP/2, and HTTP proxies (including HTTPS `CONNECT`) work; authenticated proxies fail.
- Certificates and hostnames are validated; for trust settings, see
  [Runtime Environment Variables](https://elide.help/docs/runtime-env-variables).

To serve HTTP, see [`Elide.serve`](https://elide.help/docs/api-globals-elide) or [node:http](https://elide.help/docs/api-node-http).

## Samples

- [Local server and fetch](https://elide.help/docs/code-samples#local-server-and-fetch)
- [HTTP handler](https://elide.help/docs/code-samples#http-handler)

<!-- api-reference:start af4506a7c6a2 -->
## Reference

**Status:** Full · 1,455 of 2,511 suite tests pass (57.9%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `Headers` | class | Full | `append()`, `delete()`, `get()`, `getSetCookie()`, `has()`, `set()`, `iteration` |
| `Request` | class | Full | `method`, `url`, `headers`, `destination`, `referrer`, `referrerPolicy`, `mode`, `credentials`, `cache`, `redirect`, `integrity`, `keepalive`, `signal`, `duplex`, `clone()`, `body`, `bodyUsed`, `arrayBuffer()`, `blob()`, `bytes()`, `formData()`, `json()`, `text()` |
| `Response` | class | Full | `Response.error()`, `Response.redirect()`, `Response.json()`, `type`, `url`, `redirected`, `status`, `ok`, `statusText`, `headers`, `clone()`, `body`, `bodyUsed`, `arrayBuffer()`, `blob()`, `bytes()`, `formData()`, `json()`, `text()` |
| `Blob` | class | Full | `size`, `type`, `slice()`, `text()`, `arrayBuffer()`, `bytes()`, `stream()` |
| `File` | class | Full | `name`, `lastModified` |
| `FormData` | class | Full | `append()`, `delete()`, `get()`, `getAll()`, `has()`, `set()`, `iteration` |

**Tests:** [wpt-wintertc `fetch`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/wpt-wintertc/wpt-wintertc.md): 1,455 pass, 1,043 fail, 13 error, 400 skipped. Failing: `fetch/api/basic/request-forbidden-headers.any.js` (96), `fetch/api/redirect/redirect-referrer-override.any.js` (91), `fetch/data-urls/processing.any.js` (68), `fetch/api/headers/header-values-normalize.any.js` (57), `fetch/api/cors/cors-keepalive.any.js` (51), `fetch/api/cors/cors-preflight-star.any.js` (34), `fetch/api/redirect/redirect-origin.any.js` (30), `fetch/api/cors/cors-preflight-status.any.js` (27), and 110 more.
<!-- api-reference:end -->

---

# Messaging

URL: https://elide.help/docs/api-wintercg-messaging

> How Elide supports MessageChannel, MessagePort and MessageEvent: same-realm channels, which values structured clone copies, and DataCloneError cases.

`MessageChannel`, `MessagePort`, and `MessageEvent` are globals and follow the
[HTML Standard](https://html.spec.whatwg.org/multipage/web-messaging.html).

## Example

```js
// messaging.mjs
const { port1, port2 } = new MessageChannel();
port2.onmessage = (event) => {
  const { when, tags } = event.data;
  console.log(when instanceof Date, tags instanceof Set, [...tags].join());
  port1.close();
  port2.close();
};
port1.postMessage({ when: new Date(0), tags: new Set(["a", "b"]) });

try {
  port1.postMessage(() => {});
} catch (error) {
  console.log(error.name);
}
```

`elide run messaging.mjs` prints:

```text
DataCloneError
true true a,b
```

## Differences from browsers

- A channel connects ports in the same realm; it does not create a worker.
- Structured clone copies primitives, arrays, plain objects, cycles, `Date`, `RegExp`, `Map`, `Set`, and `ArrayBuffer`.
- Posting a function throws `DataCloneError`.

For workers, see [node:worker_threads](https://elide.help/docs/api-node-worker-threads).

<!-- api-reference:start 664c308fbb59 -->
## Reference

**Status:** Partial · Not measured

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `MessageEvent` | class | Partial | missing WindowProxy and ServiceWorker as MessageEventSource (non-browser). `data`, `origin`, `lastEventId`, `source`, `ports`, `initMessageEvent()` |
| `MessageChannel` | class | Partial | missing WindowProxy and ServiceWorker as MessageEventSource (non-browser). `port1`, `port2` |
| `MessagePort` | class | Partial | missing WindowProxy and ServiceWorker as MessageEventSource (non-browser). `postMessage()`, `start()`, `close()`, `onclose`, `onmessage`, `onmessageerror` |
<!-- api-reference:end -->

---

# Other globals

URL: https://elide.help/docs/api-web-misc-globals

> How Elide supports the `DOMException` and `PromiseRejectionEvent` globals, and the `unhandledrejection` and `rejectionhandled` events on globalThis.

`DOMException` and `PromiseRejectionEvent` are globals and follow the
[WebIDL](https://webidl.spec.whatwg.org/#idl-DOMException) and
[HTML](https://html.spec.whatwg.org/multipage/webappapis.html#promiserejectionevent) standards, including legacy
`DOMException` codes and constants such as `DOMException.ABORT_ERR`.

## Example

```js
// misc.mjs
const error = new DOMException("upload took too long", "TimeoutError");
console.log(error.name, error.code === DOMException.TIMEOUT_ERR, error instanceof Error);

globalThis.addEventListener("unhandledrejection", (event) => {
  event.preventDefault();
  console.log("unhandled:", event.reason.message);
});
Promise.reject(new Error("lost"));
```

`elide run misc.mjs` prints:

```text
TimeoutError true true
unhandled: lost
```

Elide dispatches `unhandledrejection` on `globalThis` when a Promise rejects without a handler, and
`rejectionhandled` when a handler is attached later. `onunhandledrejection` and `onrejectionhandled` also work.

<!-- api-reference:start 0c0e5bb66439 -->
## Reference

**Status:** Full · Not measured

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `DOMException` | class | Full | `name`, `message`, `code`, `INDEX_SIZE_ERR`, `DOMSTRING_SIZE_ERR`, `HIERARCHY_REQUEST_ERR`, `WRONG_DOCUMENT_ERR`, `INVALID_CHARACTER_ERR`, `NO_DATA_ALLOWED_ERR`, `NO_MODIFICATION_ALLOWED_ERR`, `NOT_FOUND_ERR`, `NOT_SUPPORTED_ERR`, `INUSE_ATTRIBUTE_ERR`, `INVALID_STATE_ERR`, `SYNTAX_ERR`, `INVALID_MODIFICATION_ERR`, `NAMESPACE_ERR`, `INVALID_ACCESS_ERR`, `VALIDATION_ERR`, `TYPE_MISMATCH_ERR`, `SECURITY_ERR`, `NETWORK_ERR`, `ABORT_ERR`, `URL_MISMATCH_ERR`, `QUOTA_EXCEEDED_ERR`, `TIMEOUT_ERR`, `INVALID_NODE_TYPE_ERR`, `DATA_CLONE_ERR` |
| `PromiseRejectionEvent` | class | Full | `promise`, `reason` |
<!-- api-reference:end -->

---

# Performance

URL: https://elide.help/docs/api-wintercg-performance

> How Elide supports `performance`, PerformanceObserver and PerformanceEntry per the User Timing and Performance Timeline specs, shared with node:perf_hooks.

`performance`, `PerformanceObserver`, and the `PerformanceEntry` classes are globals and follow the
[User Timing](https://w3c.github.io/user-timing/) and
[Performance Timeline](https://w3c.github.io/performance-timeline/) specs.

## Example

```js
// performance.mjs
const start = performance.now();
performance.mark("parse:start");
JSON.parse(JSON.stringify(Array.from({ length: 1000 }, (_, i) => ({ i }))));
performance.mark("parse:end", { detail: { rows: 1000 } });

const measure = performance.measure("parse", "parse:start", "parse:end");
console.log(measure.entryType, measure.name, measure.duration >= 0);
console.log(performance.getEntriesByName("parse:end")[0].detail.rows);
console.log(performance.now() >= start, typeof performance.timeOrigin);
```

`elide run performance.mjs` prints:

```text
measure parse true
1000
true number
```

## Differences from browsers

- `performance` and [node:perf_hooks](https://elide.help/docs/api-node-perf-hooks) share one timeline.
- `PerformanceObserver.supportedEntryTypes` is `mark`, `measure`, `node`, and `function`.
- Mark and measure `detail` values are cloned as in [Web Messaging](https://elide.help/docs/api-wintercg-messaging); functions throw
  `DataCloneError`.

<!-- api-reference:start 67c84b4e6a82 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `PerformanceEntry` | class | Full | `name`, `entryType`, `startTime`, `duration`, `detail`, `toJSON()` |
| `PerformanceMark` | class | Full | `detail` |
| `PerformanceMeasure` | class | Full | `detail` |
| `PerformanceObserverEntryList` | class | Full | `getEntries()`, `getEntriesByName()`, `getEntriesByType()` |
| `PerformanceObserver` | class | Full | `observe()`, `disconnect()`, `takeRecords()`, `PerformanceObserver.supportedEntryTypes` |
| `Performance` | class | Full | `now()`, `timeOrigin`, `mark()`, `measure()`, `getEntries()`, `getEntriesByName()`, `getEntriesByType()`, `clearMarks()`, `clearMeasures()`, `toJSON()` |
<!-- api-reference:end -->

---

# Streams

URL: https://elide.help/docs/api-whatwg-streams

> How Elide supports ReadableStream, WritableStream and TransformStream per the Streams Standard, including byte streams, BYOB readers and `from()`.

`ReadableStream`, `WritableStream`, `TransformStream`, their readers, writers, and controllers,
`CountQueuingStrategy`, and `ByteLengthQueuingStrategy` are globals. They follow the
[Streams Standard](https://streams.spec.whatwg.org/), including byte streams, BYOB readers, and `ReadableStream.from()`.

## Example

```js
// webstreams.mjs
const numbers = ReadableStream.from([1, 2, 3, 4]);
const doubled = numbers.pipeThrough(
  new TransformStream({
    transform(n, controller) {
      controller.enqueue(n * 2);
    },
  }),
);

const seen = [];
await doubled.pipeTo(
  new WritableStream({
    write(n) {
      seen.push(n);
    },
  }),
);
console.log(seen.join(" "));

const text = await new Response(ReadableStream.from(["he", "llo"]).pipeThrough(new TextEncoderStream())).text();
console.log(text);
```

`elide run webstreams.mjs` prints:

```text
2 4 6 8
hello
```

## Differences from browsers

- A stream cannot be transferred to a worker: naming one in a `postMessage` transfer list throws `DataCloneError`.

For byte transforms, see [Compression Streams](https://elide.help/docs/api-whatwg-compression).

<!-- api-reference:start 68d53f55bc9d -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `ReadableStream` | class | Full | `locked`, `cancel()`, `getReader()`, `pipeThrough()`, `pipeTo()`, `tee()` |
| `ReadableStreamDefaultReader` | class | Full | `closed`, `read()`, `releaseLock()`, `cancel()` |
| `ReadableStreamDefaultController` | class | Full | `desiredSize`, `close()`, `enqueue()`, `error()` |
| `ReadableStreamBYOBReader` | class | Full | `closed`, `read()`, `releaseLock()`, `cancel()` |
| `ReadableByteStreamController` | class | Full | `byobRequest`, `desiredSize`, `close()`, `enqueue()`, `error()` |
| `ReadableStreamBYOBRequest` | class | Full | `view`, `respond()`, `respondWithNewView()` |
| `WritableStream` | class | Full | `locked`, `abort()`, `close()`, `getWriter()` |
| `WritableStreamDefaultWriter` | class | Full | `closed`, `desiredSize`, `ready`, `abort()`, `close()`, `releaseLock()`, `write()` |
| `WritableStreamDefaultController` | class | Full | `signal`, `error()` |
| `TransformStream` | class | Full | `readable`, `writable` |
| `TransformStreamDefaultController` | class | Full | `desiredSize`, `enqueue()`, `error()`, `terminate()` |
| `CountQueuingStrategy` | class | Full | `highWaterMark`, `size` |
| `ByteLengthQueuingStrategy` | class | Full | `highWaterMark`, `size` |
<!-- api-reference:end -->

---

# Timers

URL: https://elide.help/docs/api-html-timers

> How Elide supports setTimeout, setInterval, setImmediate and queueMicrotask: Node Timeout objects instead of numbers, and callback order at checkpoints.

`setTimeout`, `setInterval`, `setImmediate`, their `clear*` counterparts, and `queueMicrotask` are globals that follow
the [HTML timer](https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#timers) API.

## Example

```js
// htmltimers.mjs
setTimeout(() => {
  const order = [];
  setTimeout(() => order.push("timeout"), 0);
  setImmediate(() => order.push("immediate"));
  Promise.resolve().then(() => order.push("promise"));
  queueMicrotask(() => order.push("microtask"));
  process.nextTick(() => order.push("nextTick"));
  setTimeout(() => console.log(order.join(" ")), 20);
}, 0);

let runs = 0;
const interval = setInterval(() => {
  if (++runs === 2) {
    clearInterval(interval);
    console.log("interval ran", runs, "times; hasRef:", interval.hasRef());
  }
}, 5);
```

`elide run htmltimers.mjs` prints:

```text
interval ran 2 times; hasRef: true
nextTick promise microtask immediate timeout
```

## Differences from browsers

- Timers return Node `Timeout` or `Immediate` objects, not numbers, with `ref()`, `unref()`, `hasRef()`, and
  `refresh()` (`Timeout` only).
- String handlers are not supported; the callback must be callable.
- `setTimeout(callback)` without a delay prints `TimeoutNaNWarning` before running the callback; pass `0`.
- At a checkpoint, callbacks run in this order:
  1. `process.nextTick`
  2. Promise and `queueMicrotask` callbacks, in enqueue order
  3. `setImmediate`
  4. Zero-delay timers

<!-- api-reference:start 581f63d8af5c -->
## Reference

**Status:** Full · Not measured
<!-- api-reference:end -->

---

# URL

URL: https://elide.help/docs/api-whatwg-url

> How Elide supports the URL and URLSearchParams globals per the URL Standard, including `URL.parse()`, `URL.canParse()` and the live `searchParams` object.

`URL` is a global and follows the [URL Standard](https://url.spec.whatwg.org/), including `URL.parse()` and
`URL.canParse()`.

## Example

```js
// weburl.mjs
const url = new URL("../docs?page=2#intro", "https://elide.dev/guide/start");
console.log(url.href);
console.log(url.pathname, url.searchParams.get("page"), url.hash);

url.searchParams.append("tag", "node");
url.searchParams.sort();
console.log(url.search);
console.log(URL.canParse("not a url"), URL.parse("http://[::1]:8080/")?.host);
```

`elide run weburl.mjs` prints:

```text
https://elide.dev/docs?page=2#intro
/docs 2 #intro
?page=2&tag=node
false [::1]:8080
```

## URLSearchParams

`URLSearchParams` is a global and follows the same standard. `url.searchParams` returns the same live object on every
access.

<!-- api-reference:start 0f26d93f1e27 -->
## Reference

**Status:** Full · 8,682 of 9,046 suite tests pass (96.0%) · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `URL` | class | Full | `URL.parse()`, `URL.canParse()`, `href`, `origin`, `protocol`, `username`, `password`, `host`, `hostname`, `port`, `pathname`, `search`, `searchParams`, `hash`, `toJSON()` |
| `URLSearchParams` | class | Full | `size`, `append()`, `delete()`, `get()`, `getAll()`, `has()`, `set()`, `sort()`, `iteration` |

**Tests:** [wpt-wintertc `url`](https://github.com/elide-dev/testsuite/blob/main/reports/1.6.0%2B6e718933f/4cbcae6c33a8/wpt-wintertc/wpt-wintertc.md): 8,682 pass, 364 fail, 0 error, 2,251 skipped. Failing: `url/toascii.window.js` (298), `url/IdnaTestV2.any.js` (30), `url/url-constructor.any.js` (12), `url/url-setters.any.js` (12), `url/urlsearchparams-constructor.any.js` (6), `url/urlencoded-parser.any.js` (2), `url/idlharness.any.js`, `url/url-origin.any.js`, and 2 more.
<!-- api-reference:end -->

---

# URLPattern

URL: https://elide.help/docs/api-whatwg-urlpattern

> How Elide supports the URLPattern global for matching URLs against patterns per the URL Pattern Standard, including `ignoreCase` and `hasRegExpGroups`.

`URLPattern` is a global and follows the [URL Pattern Standard](https://urlpattern.spec.whatwg.org/), including the
`ignoreCase` option and `hasRegExpGroups`.

## Example

```js
// urlpattern.mjs
const route = new URLPattern({ pathname: "/users/:id(\\d+)/:tab?" });

console.log(route.test("https://example.com/users/42"));
console.log(JSON.stringify(route.exec("https://example.com/users/42/posts").pathname.groups));
console.log(route.test("https://example.com/users/alice"));
```

`elide run urlpattern.mjs` prints:

```text
true
{"tab":"posts","id":"42"}
false
```

## Samples

- [Routes with URLPattern](https://elide.help/docs/code-samples#routes-with-urlpattern)

<!-- api-reference:start 17c72debced1 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `URLPattern` | class | Full | `protocol`, `username`, `password`, `hostname`, `port`, `pathname`, `search`, `hash`, `hasRegExpGroups`, `test()`, `exec()` |
<!-- api-reference:end -->

---

# Web Crypto

URL: https://elide.help/docs/api-whatwg-web-crypto

> How Elide supports the Web Crypto API: getRandomValues, randomUUID, and the digest, key, sign, encrypt and derive algorithms of `crypto.subtle`.

The global `crypto` provides `getRandomValues()`, `randomUUID()`, and `crypto.subtle` from the
[Web Cryptography API](https://w3c.github.io/webcrypto/); validation, error names, and messages match Node.

| Operation | Algorithms |
|---|---|
| `digest` | SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256/384/512, cSHAKE128/256 (no function name or customization) |
| `generateKey`, `importKey`, `exportKey` | RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH (P-256, P-384, P-521), Ed25519, X25519, HMAC, AES-CTR/CBC/GCM/KW, ChaCha20-Poly1305; HKDF and PBKDF2 import only |
| `sign`, `verify` | RSASSA-PKCS1-v1_5, RSA-PSS, ECDSA, Ed25519, HMAC |
| `encrypt`, `decrypt` | RSA-OAEP, AES-CTR, AES-CBC, AES-GCM, ChaCha20-Poly1305 |
| `wrapKey`, `unwrapKey` | AES-KW and every `encrypt`/`decrypt` algorithm |
| `deriveBits`, `deriveKey` | ECDH, X25519, HKDF, PBKDF2 |
| `getPublicKey`, `SubtleCrypto.supports` | As in Node |

Key formats: `raw` (with `raw-public` and `raw-secret` aliases), `spki`, `pkcs8`, and `jwk`.

## Example

```js
// webcrypto.mjs
const data = new TextEncoder().encode("elide");
const digest = await crypto.subtle.digest("SHA-256", data);
console.log(Buffer.from(digest).toString("hex").slice(0, 16));

const key = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, false, ["sign", "verify"]);
const signature = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key.privateKey, data);
console.log(signature.byteLength, await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key.publicKey, signature, data));

console.log(crypto.randomUUID().length, crypto.getRandomValues(new Uint8Array(4)).length);
```

`elide run webcrypto.mjs` prints:

```text
bdfdf1cc04d072e4
64 true
36 4
```

## Differences from Node

- `CryptoKey` and [node:crypto](https://elide.help/docs/api-node-crypto) `KeyObject` share key material: `KeyObject.from(cryptoKey)` and
  `keyObject.toCryptoKey()` convert without copying.
- Ed448, X448, AES-OCB, KMAC, Argon2, ML-DSA, ML-KEM, TurboSHAKE, and KangarooTwelve reject with `NotSupportedError`.
  Use `node:crypto` `generateKeyPair` for ML-DSA and ML-KEM keys.

## Samples

- [Sign data with Web Crypto](https://elide.help/docs/code-samples#sign-data-with-web-crypto)

<!-- api-reference:start c722e9014b50 -->
## Reference

**Status:** Full · Not measured · since 1.1.0

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `crypto` | object | Full | `randomUUID()`, `getRandomValues()`, `subtle` |
| `SubtleCrypto` | class | Full | `digest()`, `encrypt()`, `decrypt()`, `sign()`, `verify()`, `generateKey()`, `importKey()`, `exportKey()`, `deriveBits()`, `deriveKey()`, `wrapKey()`, `unwrapKey()` |
<!-- api-reference:end -->

---

# WorkerNavigator

URL: https://elide.help/docs/api-wintercg-navigator

> How Elide supports the `navigator` global: a WorkerNavigator whose userAgent, platform, language and other values are fixed at startup.

`globalThis.navigator` is a [`WorkerNavigator`](https://html.spec.whatwg.org/multipage/workers.html#the-workernavigator-object);
its values are fixed at startup, and the constructor throws if called.

| Attribute | Value |
|---|---|
| `appCodeName` | `"Mozilla"` |
| `appName` | `"Netscape"` |
| `product` | `"Gecko"` |
| `appVersion` | Elide version and platform. |
| `userAgent` | Elide user-agent string. |
| `platform` | `linux`, `darwin`, `win32`, another known host label, or `unknown`. |
| `language` | Runtime locale, normally a BCP-47 tag. |
| `languages` | Frozen one-element array containing `language`. |
| `onLine` | Always `true`. |
| `hardwareConcurrency` | Available processor count, at least 1. |

## Example

```js
// navigator.mjs
console.log(navigator instanceof WorkerNavigator, navigator.onLine);
console.log(navigator.hardwareConcurrency >= 1, navigator.userAgent.includes(" Elide/"));
console.log(navigator.languages.length, Object.isFrozen(navigator.languages));
```

`elide run navigator.mjs` prints:

```text
true true
true true
1 true
```

<!-- api-reference:start 94735135bc29 -->
## Reference

**Status:** Full · Not measured

### Exports

| Export | Kind | Status | Notes |
| --- | --- | --- | --- |
| `WorkerNavigator` | class | Full | `appCodeName`, `appName`, `appVersion`, `platform`, `product`, `userAgent`, `language`, `languages`, `onLine`, `hardwareConcurrency` |
<!-- api-reference:end -->

---

# JVM APIs

URL: https://elide.help/docs/api-jvm

> What Java and Kotlin programs run by Elide can use: the bundled JDK 25 and Kotlin 2.5 standard library, the libraries Elide puts on each classpath, and what is not available.

Elide compiles Java and Kotlin with its bundled `javac` and `kotlinc` and runs the program on the bundled JDK in a
separate process. The program can use the JDK, the Kotlin standard library, the libraries listed below and its own
Maven dependencies.

```kotlin
// Versions.kt
fun main() {
  println("JDK ${Runtime.version().feature()}, Kotlin ${KotlinVersion.CURRENT}")
}
```

```bash
elide run Versions.kt
```

```text
JDK 25, Kotlin 2.5.0
```

| Component | Version |
| --- | --- |
| JDK | 25 |
| Kotlin compiler and standard library | 2.5.0-Beta2 |
| [Elide annotations](https://elide.help/docs/api-jvm-annotations) (`dev.elide:elide-api`) | 1.0.0 |

## Single-file runs

`elide run Main.java` or `elide run Main.kt` outside a project compiles against this classpath:

| Language | Classpath besides the JDK |
| --- | --- |
| Java | Elide annotations |
| Kotlin | Elide annotations, Standard library, `kotlin-reflect`, kotlinx coroutines, serialization (core and JSON), datetime, io, collections-immutable, html and atomicfu |

Kotlin files compile with the kotlinx.serialization and atomicfu compiler plugins. A Kotlin file cannot import
Metro; use a project for that.

Inside a project directory (one with an `elide.pkl`, or below one), a single file also gets that project's
dependencies.

## Projects

`elide build`, `elide run` and `elide test` add these libraries to Kotlin source sets. Java source sets get only the
JUnit libraries on test sets. The switches go in `kotlin.features`, except JUnit's: `jvm.features.testing`, which
removes the bundled JUnit compile APIs and runtime when `false`; JVM test runs then need `junit-platform-console` in
`testPackages`.

| Library | Version | Main | Tests | Turn off with |
| --- | --- | --- | --- | --- |
| Elide annotations (`dev.elide:elide-api`) | 1.0.0 | Compile, run | Inherited | — |
| `kotlin-stdlib` | 2.5.0-Beta2 | Compile, run | Inherited | — |
| `kotlin-reflect` | 2.5.0-Beta2 | Compile, run | Inherited | `reflection = false` |
| `kotlinx-coroutines-core` | 1.11.0 | Compile, run | Inherited | `coroutines = false` or `kotlinx = false` |
| `kotlinx-serialization-core`, `-json` | 1.12.0 | Compile, run | Inherited | `serialization = false` or `kotlinx = false` |
| Metro runtime (`dev.zacsweers.metro:runtime`) | 1.5.0 | Compile, run | Inherited | `metro = false` |
| `kotlin-test`, `kotlin-test-junit5` | 2.5.0-Beta2 | — | Compile, run | `testing = false` |
| `kotlinx-coroutines-test` | 1.11.0 | — | Compile, run | `coroutines = false` |
| JUnit Jupiter API and params | 6.1.3 | — | Compile, run | `jvm.features.testing` |
| JUnit Jupiter engine and Platform | 6.1.3 | — | Run | `jvm.features.testing` |

A Java project adds Elide annotations as a `compileOnly` dependency; see
[Elide annotations](https://elide.help/docs/api-jvm-annotations#add-to-a-project). Other bundled libraries are linked from the binary,
without a download, when a project declares them at the bundled version; see
[Bundled libraries](https://elide.help/docs/api-jvm-libraries#other-kotlinx-libraries).

`elide classpath` prints the main classpath; `elide classpath test:compile` prints what a test set adds.

## Not available

| Not available | Detail |
| --- | --- |
| Elide runtime API | JVM programs have no `Elide` global or other runtime object; `dev.elide.annotations` is the only Elide package. |
| Calls to or from JavaScript and Python | The program runs in its own process, and `--interop` does not apply. See [Languages](https://elide.help/docs/languages). |
| OpenTelemetry | Elide injects no OpenTelemetry API, agent or trace context into JVM programs. See [OpenTelemetry](https://elide.help/docs/opentelemetry). |

## Reference

| Page | Covers |
| --- | --- |
| [Elide annotations](https://elide.help/docs/api-jvm-annotations) | Every annotation in `dev.elide.annotations`: targets, retention and effect. |
| [Bundled libraries](https://elide.help/docs/api-jvm-libraries) | kotlinx coroutines and serialization, other kotlinx libraries, Metro, JUnit and `kotlin.test`. |
| [Insight for JVM programs](https://elide.help/docs/api-jvm-insight) | `--insights` scripts and classes on a JVM project run. |

## Samples

- [Kotlin coroutines](https://elide.help/docs/code-samples#kotlin-coroutines)
- [Kotlin JSON serialization](https://elide.help/docs/code-samples#kotlin-json-serialization)
- [Java with a Maven dependency](https://elide.help/docs/code-samples#java-with-a-maven-dependency)
- [Elide annotations in Kotlin](https://elide.help/docs/code-samples#elide-annotations-in-kotlin)

---

# Elide annotations

URL: https://elide.help/docs/api-jvm-annotations

> Every annotation in `dev.elide.annotations` (`dev.elide:elide-api`) for Java and Kotlin programs: targets, retention, what each one does in Elide, and how to add the package to a project.

`dev.elide.annotations` ships in the bundled `dev.elide:elide-api` 1.0.0 JAR. It is not published to Maven Central.
Two annotations change what Elide does: `@Delicate` (Kotlin opt-in) and `@Generated` (coverage). The others are
markers that a program or library can read; Elide does not act on them.

| Annotation | Kotlin targets | Java targets | Retention | Effect in Elide |
| --- | --- | --- | --- | --- |
| [`@API`](#api) | class, type | type, type use | Runtime | None |
| [`@Delicate`](#delicate) | class, property, field, local variable, value parameter, constructor, function, getter, setter, typealias | type, field, method, parameter, constructor, local variable | Runtime | Kotlin callers must opt in |
| [`@Eager`](#eager) | class, annotation class | type, annotation type | Class file | None |
| [`@Factory`](#factory) | class | type | Runtime | None |
| [`@Generated`](#generated) | class, function, file, type | type, method, type use | Class file | Left out of JVM coverage reports |
| [`@Inject`](#inject-and-singleton) | Alias of `jakarta.inject.Inject` | Not available | Runtime | None |
| [`@Nonnull`](#nonnull-and-nullable) | class, type | type, type use | Runtime | None |
| [`@Nullable`](#nonnull-and-nullable) | class, type | type, type use | Runtime | None |
| [`@Secret`](#secret) | property, class | type | Runtime | None |
| [`@Singleton`](#inject-and-singleton) | Alias of `jakarta.inject.Singleton` | Not available | Runtime | None |

None of them take parameters. "Class file" retention means the annotation is in the bytecode but not visible to
reflection.

## Add to a project

| Program | Elide annotations |
| --- | --- |
| Java file run with `elide run` | On the classpath |
| Kotlin file run with `elide run` | On the classpath |
| Kotlin source set | On the compile and run classpaths |
| Java source set | Declare it: |

```pkl
dependencies {
  maven {
    compileOnly { "dev.elide:elide-api:1.0.0" }
  }
}
```

The annotations are compiled from Kotlin, so Elide puts the Kotlin standard library on the Java compile classpath
alongside `elide-api`; Java compiles emit no `unknown enum constant` warnings.

## @API

Marks an interface or abstract class as the API surface of a unit of logic. Readable by reflection.

```java
@API
interface Greeter {
  String greet(String name);
}
```

```kotlin
@API
interface Greeter {
  fun greet(name: String): String
}
```

## @Delicate

Marks an API that callers should use with care. In Kotlin it is a `@RequiresOptIn` marker: a call without
`@OptIn(Delicate::class)` fails to compile.

```kotlin
@Delicate
fun reset() {}

@OptIn(Delicate::class)
fun main() {
  reset()
}
```

Without the `@OptIn`:

```text
error: kotlinc: This API is marked delicate; opt in with @OptIn(Delicate::class) if you understand its caveats.
```

Java has no opt-in check, so Java callers compile without it:

```java
@Delicate
static void reset() {}
```

## @Eager

Marks a class for eager initialization. Class-file retention only; Elide does not act on it.

```java
@Eager
static class Startup {}
```

```kotlin
@Eager
class Startup
```

## @Factory

Marks a class that creates instances of another type. Readable by reflection.

```java
@Factory
static class GreeterFactory {
  static Greeter create() {
    return name -> "Hello, " + name;
  }
}
```

```kotlin
@Factory
object GreeterFactory {
  fun create(): Greeter = Polite()
}
```

## @Generated

Marks generated code. JVM coverage reports from `elide test --coverage` and `elide run --coverage` leave out annotated
classes, methods and Kotlin files ([Coverage](https://elide.help/docs/toolchain/testing#coverage)).

```java
@Generated
static String banner() {
  return "generated";
}
```

```kotlin
@Generated
fun banner() = "generated"
```

A whole Kotlin file:

```kotlin
@file:Generated

import dev.elide.annotations.Generated

fun mapAll(xs: List<Int>) = xs.map { it * 2 }
```

## @Inject and @Singleton

Kotlin type aliases of `jakarta.inject.Inject` and `jakarta.inject.Singleton`. They need
`jakarta.inject:jakarta.inject-api` on the classpath, which Elide does not add. Elide has no dependency injection
container that reads them; for compile-time injection in Kotlin, use [Metro](https://elide.help/docs/api-jvm-libraries#metro). Java code
cannot import them; use `jakarta.inject` directly.

```pkl
dependencies {
  maven {
    packages { "jakarta.inject:jakarta.inject-api:2.0.1" }
  }
}
```

```kotlin
@Singleton
class Polite @Inject constructor() : Greeter {
  override fun greet(name: String) = "Hello, $name"
}
```

## @Nonnull and @Nullable

Type-use annotations for documenting nullability. Neither compiler checks them, and Kotlin does not read them as
nullability: a Java method returning `@Nullable String` is still a platform type in Kotlin.

```java
static @Nullable String find(@Nonnull String id) {
  return USERS.get(id);
}
```

```kotlin
fun find(id: @Nonnull String): @Nullable String? = users[id]
```

## @Secret

Marks a class or property that holds secret material. Readable by reflection; generated `toString` output is not
redacted. In Java it applies to classes only.

```java
@Secret
record Token(String value) {}
```

```kotlin
data class Credentials(val user: String, @Secret val token: String)
```

## Complete examples

The snippets above come from these two programs. The Java file runs on its own:

```java
// Annotations.java
import dev.elide.annotations.API;
import dev.elide.annotations.Delicate;
import dev.elide.annotations.Eager;
import dev.elide.annotations.Factory;
import dev.elide.annotations.Generated;
import dev.elide.annotations.Nonnull;
import dev.elide.annotations.Nullable;
import dev.elide.annotations.Secret;
import java.util.Arrays;
import java.util.Map;

public class Annotations {
  @API
  interface Greeter {
    String greet(String name);
  }

  @Factory
  static class GreeterFactory {
    static Greeter create() {
      return name -> "Hello, " + name;
    }
  }

  @Eager
  static class Startup {}

  @Secret
  record Token(String value) {}

  static final Map<String, String> USERS = Map.of("ada", "Ada Lovelace");

  static @Nullable String find(@Nonnull String id) {
    return USERS.get(id);
  }

  @Delicate
  static void reset() {}

  @Generated
  static String banner() {
    return "generated";
  }

  public static void main(String[] args) {
    System.out.println(GreeterFactory.create().greet("Ada"));
    System.out.println(find("ada") + ", " + find("bob"));
    reset();
    for (Class<?> type : new Class<?>[] {Greeter.class, GreeterFactory.class, Startup.class, Token.class}) {
      System.out.println(type.getSimpleName() + " " + Arrays.toString(type.getAnnotations()));
    }
    System.out.println(new Token("s3cr3t"));
  }
}
```

```bash
elide run Annotations.java
```

```text
Hello, Ada
Ada Lovelace, null
Greeter [@dev.elide.annotations.API()]
GreeterFactory [@dev.elide.annotations.Factory()]
Startup []
Token [@dev.elide.annotations.Secret()]
Token[value=s3cr3t]
```

The Kotlin program is a project, because `@Inject` and `@Singleton` need `jakarta.inject`, which a project adds:

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "annotations"

jvm {
  main = "MainKt"
}

dependencies {
  maven {
    packages { "jakarta.inject:jakarta.inject-api:2.0.1" }
  }
}
```

```kotlin
// src/main/kotlin/Main.kt
import dev.elide.annotations.API
import dev.elide.annotations.Delicate
import dev.elide.annotations.Eager
import dev.elide.annotations.Factory
import dev.elide.annotations.Generated
import dev.elide.annotations.Inject
import dev.elide.annotations.Nonnull
import dev.elide.annotations.Nullable
import dev.elide.annotations.Secret
import dev.elide.annotations.Singleton

@API
interface Greeter {
  fun greet(name: String): String
}

@Singleton
class Polite @Inject constructor() : Greeter {
  override fun greet(name: String) = "Hello, $name"
}

@Factory
object GreeterFactory {
  fun create(): Greeter = Polite()
}

@Eager
class Startup

data class Credentials(val user: String, @Secret val token: String)

val users = mapOf("ada" to "Ada Lovelace")

fun find(id: @Nonnull String): @Nullable String? = users[id]

@Delicate
fun reset() {}

@Generated
fun banner() = "generated"

@OptIn(Delicate::class)
fun main() {
  println(GreeterFactory.create().greet("Ada"))
  println("${find("ada")}, ${find("bob")}")
  reset()
  for (type in listOf(Greeter::class, Polite::class, GreeterFactory::class, Startup::class)) {
    println("${type.simpleName} ${type.java.annotations.filterNot { it is Metadata }}")
  }
  println(Credentials("ada", "s3cr3t"))
}
```

```bash
elide run
```

```text
Hello, Ada
Ada Lovelace, null
Greeter [@dev.elide.annotations.API()]
Polite [@jakarta.inject.Singleton()]
GreeterFactory [@dev.elide.annotations.Factory()]
Startup []
Credentials(user=ada, token=s3cr3t)
```

## Samples

- [Elide annotations in Kotlin](https://elide.help/docs/code-samples#elide-annotations-in-kotlin)

---

# Bundled libraries

URL: https://elide.help/docs/api-jvm-libraries

> Libraries Elide bundles for Java and Kotlin programs: kotlinx coroutines and serialization, the other kotlinx libraries, Metro dependency injection, JUnit and kotlin.test, with versions, switches and examples.

These libraries ship inside Elide and need no download. Which ones are on a classpath by default is listed in
[JVM APIs](https://elide.help/docs/api-jvm#projects).

| Library | Version | Kotlin file | Kotlin project | Switch |
| --- | --- | --- | --- | --- |
| [kotlinx.coroutines](#kotlinxcoroutines) | 1.11.0 | Yes | Yes | `kotlin.features.coroutines` |
| [kotlinx.serialization](#kotlinxserialization) (core, JSON) | 1.12.0 | Yes | Yes | `kotlin.features.serialization` |
| [kotlinx-datetime](#other-kotlinx-libraries) | 0.8.0-0.6.x-compat | Yes | Declare | — |
| [kotlinx-io](#other-kotlinx-libraries) (core, bytestring) | 0.9.1 | Yes | Declare | — |
| [kotlinx-collections-immutable](#other-kotlinx-libraries) | 0.5.2 | Yes | Declare | — |
| [kotlinx-html](#other-kotlinx-libraries) | 0.12.0 | Yes | Declare | — |
| [atomicfu](#other-kotlinx-libraries) | 0.33.0 | Yes | Yes | `kotlin.features.atomicfu` |
| [Metro](#metro) | 1.5.0 | No | Yes | `kotlin.features.metro` |
| [JUnit](#junit-and-kotlintest) (Jupiter, Platform) | 6.1.3 | — | Test sets | `jvm.features.testing` |
| [`kotlin.test`](#junit-and-kotlintest) | 2.5.0-Beta2 | — | Test sets | `kotlin.features.testing` |
| [kotlinx-coroutines-test](#junit-and-kotlintest) | 1.11.0 | — | Test sets | `kotlin.features.coroutines` |

`kotlin.features.kotlinx = false` turns off coroutines and serialization together. JUnit's switch is
`jvm.features.testing`; setting it to `false` removes the bundled JUnit, and JVM test runs then need `junit-platform-console` in `testPackages`. All Kotlin switches:
[Kotlin compiler](https://elide.help/docs/toolchain/jvm/kotlinc#plugins-and-features).

```pkl
kotlin {
  features {
    serialization = false
  }
}
```

## kotlinx.coroutines

```kotlin
// Fetch.kt
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking

suspend fun load(name: String, ms: Long): Int {
  delay(ms)
  println("loaded $name")
  return name.length
}

fun main() = runBlocking {
  val sizes = listOf("users" to 300L, "orders" to 200L, "prices" to 100L)
    .map { (name, ms) -> async { load(name, ms) } }
    .awaitAll()
  println("sizes in request order: $sizes")
}
```

```bash
elide run Fetch.kt
```

```text
loaded prices
loaded orders
loaded users
sizes in request order: [5, 6, 6]
```

## kotlinx.serialization

The serialization compiler plugin is on with the runtime, so `@Serializable` classes need no setup.

```kotlin
// Config.kt
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class Server(val host: String, val port: Int = 8080, val tags: List<String> = emptyList())

fun main() {
  val json = Json { prettyPrint = true }
  val server = json.decodeFromString<Server>("""{"host": "localhost", "tags": ["dev"]}""")
  println(server)
  println(json.encodeToString(server.copy(port = 9090)))
}
```

```bash
elide run Config.kt
```

```text
Server(host=localhost, port=8080, tags=[dev])
{
    "host": "localhost",
    "port": 9090,
    "tags": [
        "dev"
    ]
}
```

## Other kotlinx libraries

A Kotlin file run on its own can import every kotlinx library marked Yes under "Kotlin file" in the table:

```kotlin
// Extras.kt
import kotlinx.atomicfu.atomic
import kotlinx.collections.immutable.persistentListOf
import kotlinx.datetime.DatePeriod
import kotlinx.datetime.LocalDate
import kotlinx.datetime.plus
import kotlinx.html.p
import kotlinx.html.stream.createHTML

private val n = atomic(1)

fun main() {
  n.incrementAndGet()
  println(n.value)
  println(persistentListOf(1, 2).add(3))
  println(LocalDate(2026, 10, 11) + DatePeriod(days = 30))
  println(createHTML().p { +"hi" }.trim())
}
```

```bash
elide run Extras.kt
```

```text
2
[1, 2, 3]
2026-11-10
<p>hi</p>
```

A project declares them. At the bundled version, `elide install` links the bundled JAR instead of downloading it:

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "dates"

jvm {
  main = "MainKt"
}

dependencies {
  maven {
    packages { "org.jetbrains.kotlinx:kotlinx-datetime-jvm:0.8.0-0.6.x-compat" }
  }
}
```

```kotlin
// src/main/kotlin/Main.kt
import kotlinx.datetime.DatePeriod
import kotlinx.datetime.LocalDate
import kotlinx.datetime.plus

fun main() {
  println(LocalDate(2026, 10, 11) + DatePeriod(days = 30))
}
```

```bash
elide run
```

```text
2026-11-10
```

atomicfu is the exception: `atomicfu-jvm` is bundled whenever the atomicfu plugin is on (`kotlin.features.atomicfu`).

## Metro

Metro generates dependency injection code at compile time. Kotlin projects get its compiler plugin and runtime; Kotlin
files run on their own do not. Metro's own documentation is at
[zacsweers.github.io/metro](https://zacsweers.github.io/metro/).

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "metro-demo"

jvm {
  main = "MainKt"
}
```

```kotlin
// src/main/kotlin/Main.kt
import dev.zacsweers.metro.AppScope
import dev.zacsweers.metro.Binds
import dev.zacsweers.metro.DependencyGraph
import dev.zacsweers.metro.Inject
import dev.zacsweers.metro.Provides
import dev.zacsweers.metro.createGraph

interface Greeter {
  fun greet(name: String): String
}

@Inject
class Polite(private val punctuation: String) : Greeter {
  override fun greet(name: String) = "Hello, $name$punctuation"
}

@DependencyGraph(AppScope::class)
interface AppGraph {
  val greeter: Greeter

  @Binds val Polite.bind: Greeter

  @Provides fun punctuation(): String = "!"
}

fun main() {
  println(createGraph<AppGraph>().greeter.greet("Ada"))
}
```

```bash
elide run
```

```text
Hello, Ada!
```

## JUnit and kotlin.test

Test sets in Java and Kotlin projects get JUnit Jupiter (`org.junit.jupiter.api`, `org.junit.jupiter.params`) and the
JUnit Platform that `elide test` runs them on. Kotlin test sets also get `kotlin.test` and `kotlinx-coroutines-test`.
Test sets see the main set's libraries too. Running tests: [Testing](https://elide.help/docs/toolchain/testing).

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "slugs"
```

```java
// src/main/java/app/Slugs.java
package app;

public class Slugs {
  public static String slugify(String text) {
    return text.trim().toLowerCase().replaceAll("[^a-z0-9]+", "-").replaceAll("(^-|-$)", "");
  }
}
```

```java
// src/test/java/app/SlugsTest.java
package app;

import static org.junit.jupiter.api.Assertions.assertEquals;

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;

class SlugsTest {
  @ParameterizedTest
  @CsvSource({"Hello World,hello-world", "' Elide 1.0 ',elide-1-0"})
  void slugifies(String input, String expected) {
    assertEquals(expected, Slugs.slugify(input));
  }
}
```

```bash
elide test
```

```text
app.SlugsTest > slugifies(String, String)
✓ [1] input = "Hello World", expected = "hello-world" [120ms]
✓ [2] input = " Elide 1.0 ", expected = "elide-1-0" [4ms]

 2 pass
 0 skip
 0 fail
Ran 2 tests across one file. (4.94s)
```

`kotlinx-coroutines-test` runs suspending tests on virtual time:

```kotlin
// src/test/kotlin/DelayTest.kt
import kotlinx.coroutines.delay
import kotlinx.coroutines.test.runTest
import kotlin.test.Test
import kotlin.test.assertEquals

class DelayTest {
  @Test fun skipsDelays() = runTest {
    delay(60_000)
    assertEquals(60_000, testScheduler.currentTime)
  }
}
```

```text
DelayTest
✓ skipsDelays() [923ms]
```

## Samples

- [Kotlin coroutines](https://elide.help/docs/code-samples#kotlin-coroutines)
- [Kotlin JSON serialization](https://elide.help/docs/code-samples#kotlin-json-serialization)
- [Kotlin tests](https://elide.help/docs/code-samples#kotlin-tests)

---

# Insight for JVM programs

URL: https://elide.help/docs/api-jvm-insight

> Trace Java and Kotlin project runs with `elide run --insights`: JavaScript Insight scripts or a Java insight class, method filters, frames, and what differs from Insight on JavaScript.

`elide run --insights=<VALUE>` in a Java or Kotlin project attaches an instrumentation agent to the program's JVM.
The value is either a JavaScript [Insight script](https://elide.help/docs/api-insight) or a Java class:

| Value | Runs | Repeatable |
| --- | --- | --- |
| `trace.js` | A JavaScript script that calls `insight.on` | Yes |
| `class:app.Trace` | A class on the program's classpath with `public static void insightmain(String, JvmInsight)` | No; cannot be mixed with scripts |

`--insights` applies to project runs (`elide run` with a `jvm.main`) and single-file Java or Kotlin runs (`elide run Main.java`).

The examples trace this program:

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "insight-demo"

jvm {
  main = "app.Main"
}
```

```java
// src/main/java/app/Main.java
package app;

public class Main {
  static int add(int a, int b) {
    return a + b;
  }

  public static void main(String[] args) {
    System.out.println(add(1, 2));
  }
}
```

## Scripts

```javascript
// trace.js
insight.on("enter", (ctx, frame) => {
  console.log("enter " + ctx.name + " a=" + frame.a + " b=" + frame.b);
}, { roots: true, rootNameFilter: "Lapp/Main;\\.add.*" });

insight.on("return", (ctx, frame) => {
  console.log("return " + ctx.name);
}, { roots: true, rootNameFilter: "Lapp/Main;\\.add.*" });
```

```bash
elide run --insights=trace.js
```

```text
enter Lapp/Main;.add(II)I a=1 b=2
return Lapp/Main;.add(II)I
3
```

The first run downloads the JavaScript engine for the agent (about 67 MB of JARs) into the Maven cache. JVM warnings and
agent log lines go to stderr.

| Script API | On a JVM program |
| --- | --- |
| Events | `enter` and `return`; no `source` |
| `rootNameFilter` | Required; without it the handler never runs. A regular expression that must match the whole method name, `L<class path>;.<method><descriptor>` |
| `roots`, `statements` | Match method entries, or each statement; no `expressions` |
| `sourceFilter` | Not supported |
| `ctx.name` | The method name in the form above |
| `ctx.line` | Source line for `statements`; `-1` for `roots` |
| `frame` | Arguments and locals by name (`frame.a`) |
| `ctx.returnValue` | Not available |

Handlers see only the program's own classes: a broad filter such as `.*` skips JDK classes and the insight engine itself.

## Classes

A class on the program's classpath receives the agent's API and registers handlers with `onMethod`. The API is in the
bundled `org.apidesign.jvm:jvm-insight:0.2`, which a project declares as `compileOnly`:

```pkl
dependencies {
  maven {
    compileOnly { "org.apidesign.jvm:jvm-insight:0.2" }
  }
}
```

```java
// src/main/java/app/Trace.java
package app;

import org.apidesign.jvm.insight.JvmInsight;

public class Trace {
  public static void insightmain(String args, JvmInsight insight) {
    insight.onMethod((method, builder) -> {
      if (method.clazz().name().equals("app.Main") && method.name().equals("add")) {
        builder.when(JvmInsight.When.ENTER).roots(true)
            .call((at, frame) -> System.out.println("enter " + at.method().name() + " " + frame));
      }
    });
  }
}
```

```bash
elide run --insights=class:app.Trace
```

```text
enter add {a=1, b=2}
3
```

| `JvmInsight` API | Use |
| --- | --- |
| `onMethod((method, builder) -> …)` | Called for each method as its class loads; `method.clazz().name()`, `method.name()`, `method.descriptor()` identify it |
| `builder.when(When.ENTER or When.RETURN)` | When the handler runs |
| `builder.roots(true)`, `builder.statements(true)` | Method entry, or each statement |
| `builder.call((at, frame) -> …)` | The handler; `at.method()`, `at.line()`, and `frame` as a `Map` of arguments and locals |

Class handlers need no download.

---

# CLI reference

URL: https://elide.help/docs/cli-references

> Every Elide command and flag: run, build, test, install, the JVM tools, setup commands, global options, instruments, exit codes and output streams.

`elide --help` lists everyday commands; `elide --help-all` adds the Advanced group and every flag.
`elide help <command>` prints that command's section of this page.

## Run and develop

### `run`

Run a file, a named script, or the project entrypoint. Resolution order: [Project setup](https://elide.help/docs/projects#add-a-script).

```bash
elide run app.ts -- --port 3000
```

| Flag | Effect |
| --- | --- |
| `-s, --snippet CODE` | Run inline code instead of a file. |
| `-l, --language LANG` | Snippet language: `js` (default), `ts`, `python`, `java`, or `kotlin`. |
| `--contexts=<N\|auto>` | Application contexts to prespawn; `auto` sizes from physical cores. Default `1`. |

Java and Kotlin snippets are whole programs with a `main`; arguments after `--` reach it:

```bash
elide run -l java -s 'void main() { System.out.println("hello from java " + (6 * 7)); }'
elide run -l kotlin -s 'fun main(args: Array<String>) = println(args.joinToString())' -- a b
```

```text
hello from java 42
a, b
```

A Java snippet without a class or `main` fails with `Could not find a top-level class/record/enum or a main in the
Java snippet.`; a Kotlin snippet without `main` fails with ``Could not find a `main` function in the Kotlin
snippet; declare `fun main() { ... }`.``

Pkl and PCF files render directly to stdout, without an Elide project:

```bash
elide --format=json config.pkl > config.json
elide run --format yaml config.pcf > config.yaml
elide config.pkl
```

Supported formats are `json`, `yaml`, and `pcf`. Without `--format`, the module's output
configuration applies (PCF by default). Imports resolve relative to the input file. Evaluation
errors go to stderr and exit nonzero; unsupported formats exit with status 2. `--quiet` preserves
the rendered output. TOML output is not currently supported. See [Render Pkl configuration](https://elide.help/docs/pkl-configuration)
for format selection, shared defaults, and CI examples (coming in 1.6.3).

Markdown files render as terminal documents. See [Markdown in the terminal](https://elide.help/docs/terminal-markdown)
for runbooks, paging, and text exports (coming in 1.6.3):

```bash
elide README.md
elide --no-color notes.markdown
```

Headings, lists, quotes, tables, task lists, links, and syntax-highlighted fenced code use terminal
layout. Paragraphs wrap at word boundaries to fit terminal width. Redirected output is plain unless color is explicitly forced. `--format` applies only to
Pkl and PCF files. Document rendering currently rejects `--sandbox` and `--limit`.

Debugger, profiler, and coverage flags: [Diagnostics flags](#diagnostics-flags).

### `serve` (alias `start`)

Serve a directory as static files, or a script that exports a fetch handler ([Development Server](https://elide.help/docs/dev-server)).

```bash
elide serve ./public
elide serve server.ts -- --verbose
```

| Flag | Effect |
| --- | --- |
| `--host HOST` | Bind host. Default `127.0.0.1`. |
| `--port PORT` | Bind port. Default `8080`. |
| `--contexts=<N\|auto>` | Application contexts to prespawn, as for `run`. |
| `--no-tui` | Plain log output instead of the dashboard. |
| `-- SCRIPT_ARGS` | Arguments for the served script. |

### `dev`

Like `serve`, with the same flags, on port `3000`. For a directory, HTML pages reload in the browser when files
change; a script is not reloaded. `--no-watch` turns off watching and reload.

### `install`

Install project dependencies.

| Flag | Effect |
| --- | --- |
| `--ecosystems LIST` | Ecosystems to install, e.g. `maven,npm`. Default `maven`. |
| `--workspace` | Install every ecosystem the project declares. |
| `--with CLASSIFIER` | Also download `sources`, `docs`, or `javadoc`. |
| `--slim` | Download classes only. |
| `--fresh` | Download all dependencies, refreshing artifacts in the global cache. |
| `--direct` | Copy artifacts into the project instead of linking them. |

### `repl`

Start the interactive REPL. A bare `elide` in a terminal does the same.

### `python`

Run Python like `python`; tokens after the script go to the program. Install it with [`setup`](#setup) first.

```bash
elide python script.py --flag-for-the-script
```

| Flag | Effect |
| --- | --- |
| `-c CMD` | Run a program passed as a string. |
| `-s` | Leave the user site directory off `sys.path`. |

Interpreter flags (`-B`, `-W`, `-m`, …): [Python options](#python-options).

### `uv`

Manage packages in the active project's automatic Python environment. Requires the Python component.

```bash
elide uv install attrs
elide uv compile requirements.in --generate-hashes --output-file requirements.txt
elide uv sync requirements.txt
elide uv list
```

Package operations: `install`, `sync`, `compile`, `check`, `list`, `freeze`, and `show`, with an optional
`pip` prefix. `elide uv tool run` executes tools in bounded, isolated environments; `tool list`,
`tool uninstall KEY`, and `tool prune --all` manage that cache. Elide selects its own interpreter. Runtime downloads,
self-update, and upstream project/runtime management commands are unavailable. See
[Packages and virtual environments](https://elide.help/docs/python-packages).

## Build and test

### `build`

Build what `elide.pkl` declares. Bare tokens name tasks (`deps`, `compile`, `test`, `clean`; leading `:` optional).
Arguments after `--` go to the subprocess.

```bash
elide build deps compile
```

| Flag | Effect |
| --- | --- |
| `-i, --inspect` | List the project's tasks. |
| `--workers=<N>` | Run at most N tasks at once. |
| `--no-cache` | Disable the build cache for this run. |
| `--offline` | Do not fetch remote resources. |
| `-f, --flag NAME[=VALUE]` | Set a manifest build flag ([Build Flags](https://elide.help/docs/toolchain/build-flags)). |

### `test`

Run tests, or only those under the given paths. JVM tests come from a test source set: `src/test/java` or
`src/test/kotlin` by convention, or one declared in `elide.pkl` (see [Source sets](https://elide.help/docs/toolchain/source-sets)).

| Flag | Effect |
| --- | --- |
| `-t, --test-name-pattern REGEX` | Run tests whose name matches. |
| `--where CEL` | JS: run tests for which a [CEL](https://elide.help/docs/api-cel) expression over `name`, `parents` and `file` is true. |
| `--select SELECTOR` | JVM: run what a selector names: `class:`, `method:`, or `package:`. Repeatable. |
| `--include-tag EXPR` | JVM: run tests matching any include. Repeatable. |
| `--exclude-tag EXPR` | JVM: skip tests matching any exclude. Repeatable. |
| `--bail[=N]` | Stop after N failures. Default `1`. |
| `--test-timeout MS` | Per-test timeout. `--timeout` limits the whole run. |
| `--only` | Run only tests marked `.only`. |
| `--concurrency N` | Tests at once (JS files, JVM classes). Default `1`. |
| `--reporter NAME` | `console`, `junit`, or `tap`. |
| `--reporter-outfile DIR` | Reporter output directory. |

Debugging tests: [Debugging](https://elide.help/docs/debugging).

### `format` (alias `fmt`)

Format Java and Kotlin sources. Paths and formatter flags follow `--`: `elide format -- src`.

| Flag | Effect |
| --- | --- |
| `--list-files` | Print each file that fails the check or is changed. |
| `--list-diffs[=N]` | Print a diff per file in check mode; with `N`, only when N or fewer fail. |
| `--install` | Run `elide install` first, so `--jfmt` resolves imports against the project's dependencies. |

`--dry-run` (after `--`) checks without writing; it exits `1` if a file would change.

### `project`

| Command | Purpose |
| --- | --- |
| `elide project info` | Show resolved project metadata. |
| `elide project advice` | Show project advice for coding agents. |
| `elide project export` | Print the project as JSON, a `pom.xml`, or an IntelliJ model. |

### `publish`

```
elide publish [PROJECT...] [--to <name>] [--skip-existing] [--dry-run] [--sign | --no-sign] [--no-wait]
              [--allow-http-repositories] [--offline]
```

Builds the project's JARs and installs them with a POM into the local Maven repository (`~/.m2/repository` unless
`publishing.maven.localRepository` says otherwise). From a workspace root it publishes every project. From a member it
publishes that member and every workspace project its POM depends on, so the coordinates it names are installed too.
Every project is built, staged and signed before any is published, so a failure there publishes nothing; a failed
upload can still leave the projects uploaded before it in place. Configure it in the manifest's
[`publishing`](https://elide.help/docs/elide-pkl-reference#publishing) block.

Naming workspace projects publishes exactly those, for example only the ones that changed since the last release:
`elide publish core util --to central`. A workspace project they depend on but that isn't named must already be in the
target, at the version its manifest declares, or nothing is published. Projects you leave out keep their `publishing`
configuration, so a later run can publish them again.

| Flag | Effect |
| --- | --- |
| `--to <name>` | Publish to the repository of that name in `publishing.maven.repositories` instead of the local one. |
| `--skip-existing` | Leave out every project whose version is already in the target, and say which. A snapshot version is always published. Useful to rerun a release that failed halfway. |
| `--dry-run` | Stage (and sign) the POM and JARs under `.dev/staging/publish/maven` and list them, without publishing. With Maven Central, also writes and lists the bundle, and needs no Portal token, but still signs, so it needs a usable signing key. With named projects or `--skip-existing`, it still looks versions up in the target, so it lists what a real run would publish; for Central that needs the token. |
| `--sign`, `--no-sign` | Sign the files with `gpg`, or don't. Remote publishes sign by default when `signing` is set. |
| `--no-wait` | For Maven Central, return once the deployment is uploaded instead of waiting for validation. |
| `--allow-http-repositories` | Allow a plain `http://` repository other than localhost. |
| `--offline` | Build without fetching remote resources. |

A version is in the target when its POM is in the local repository, when the remote repository serves its POM, or when
the Central Portal reports it published. A Central deployment that was validated but not yet released doesn't count.
A lookup that fails for any other reason, such as refused credentials, stops the run instead of counting as missing.

## Project export formats

`elide project export --format=<json|pom|intellij>` prints to stdout. Default `json`.

| Format | Output |
| --- | --- |
| `json` | The evaluated manifest. Type discriminators use `@type` and Pkl type names. |
| `pom` | Coordinates, dependencies by scope, repositories, compiler levels, source and resource roots. |
| `intellij` | One module per source set, with content roots, dependencies, SDK level and Kotlin facet. |

### pom

| POM element | Value |
| --- | --- |
| `<artifactId>` | The project name. |
| `<groupId>` | The workspace root's name, or the project name outside a workspace. |
| `<version>` | The manifest's version, or `0.0.0`. |
| `<modules>` | A workspace root's members. |
| `<parent>` | A member's workspace root. |

| Manifest | Maven scope |
| --- | --- |
| `packages`, `modules` | `compile` |
| `compileOnly`, `devPackages`, `processors` | `provided` |
| `runtimeOnly` | `runtime` |
| `testPackages` | `test` |

Sibling projects become coordinate dependencies and local JARs `system`-scoped. `exclusions` and `kotlinPlugins`
are omitted. Extra source roots use `build-helper-maven-plugin`.

### intellij

Modules are named `<project>.<sourceSet>`. Paths are relative to `root`, the workspace or project root. Libraries
resolve from `localRepository` (default `.dev/dependencies/m2`), so run `elide install` first. The
[IntelliJ IDEA plugin](https://elide.help/docs/intellij) imports this model.

## JVM toolchain

Elide bundles JDK 25 and Kotlin. Elide's flags go before `--`; tool arguments follow it.

### `java`

Run JVM programs, like `java`.

```bash
elide java -- -jar app.jar
```

### `javac`

Compile Java, like `javac`. See [Java Compiler](https://elide.help/docs/toolchain/jvm/javac).

| Flag | Effect |
| --- | --- |
| `--jar JAR` | Pack a JAR at this path after compiling. |
| `--manifest MANIFEST` | Manifest for the `--jar` output. |
| `--max-errors N` | Show at most N distinct errors; `0` shows all. |
| `--report-used-deps PATH` | Write the classpath entries the compiler read, supertypes included (Bazel strict-deps). |
| `--jdeps PATH` | Write a Bazel `.jdeps` proto with each entry's kind and the classes used from it, with SHA-256 hashes. |
| `--target-label LABEL` | Target label recorded in the `--jdeps` proto. |
| `--unused-inputs PATH` | Write classpath entries the compile neither used nor searched (Bazel `unused_inputs_list`). |
| `--persistent_worker` | Run as a Bazel persistent worker. |
| `--classpath-cache` | Reuse classpath state across worker compilations. Worker only. |
| `--capabilities` | Print compiler capabilities as JSON. |
| `--abi-only` | Emit only an ABI (header) JAR to `--emit-abi`, `--jar` or `-d`. |
| `--emit-abi PATH` | Also emit an ABI (header) JAR next to the full compile. |
| `--bindings NAME` | Select a named `java.bindings` group from the project; repeat to combine groups. |
| `--jextract GLOB` | Generate and compile Java FFM bindings for matching C headers; repeat for more headers. |
| `--jextract-package NAME` / `--jextract-class NAME` | Package and header-class name for ad hoc bindings. |
| `--jextract-include-dir DIR` | Header include directory for ad hoc bindings; repeatable. |
| `--jextract-define NAME[=VALUE]` | Preprocessor definition for ad hoc bindings; repeatable. |
| `--jextract-library NAME` | Native library for ad hoc bindings; repeatable. |
| `--emit-bindings DIR` | Also export generated Java sources to this directory for IDEs or other tools. |

Header generation runs in memory before javac attribution. The native library is a separate runtime dependency.
See [C header bindings](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings) for named groups, source-set selection,
generation-only builds, and a complete example.

### `kotlinc`

Compile Kotlin, like `kotlinc`. See [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc).

| Flag | Effect |
| --- | --- |
| `--incremental` | Compile incrementally; state goes in `.dev/artifacts/kotlinc/incremental/`. |
| `--incremental-cache-dir DIR` | Incremental state directory. |
| `--plugins LIST` | Built-in plugins: `metro`, `serialization`, `atomicfu`, `power-assert`, `compose`. |
| `--metro` / `--no-metro` | Force the Metro DI plugin on or off. |
| `--compose` / `--no-compose` | Force the opt-in Compose compiler plugin on or off; requires a Compose runtime dependency when enabled. |
| `--tests` | Enable test plugins (power-assert). |
| `--abi-only` | Emit only an ABI (header) JAR to `-d`; `--emit-abi PATH` after `--` adds one to a full compile. |
| `--kapt-sources PATH` | Run annotation processors over the sources instead of compiling; see [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc). |
| `--ksp-output DIR` | Run KSP2 symbol processors over the sources instead of compiling (`--ksp-sources`/`--ksp-classes` write jars); see [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc). |
| `--max-errors N` | Show at most N distinct errors; `0` shows all. |
| `--report-used-deps PATH` | Write the classpath entries the compiler read, supertypes included (Bazel strict-deps). |
| `--jdeps PATH` | Write a Bazel `.jdeps` proto with each entry's kind and the classes used from it, with SHA-256 hashes. |
| `--target-label LABEL` | Target label recorded in the `--jdeps` proto. |
| `--unused-inputs PATH` | Write classpath entries the compile neither used nor searched (Bazel `unused_inputs_list`). |
| `--persistent_worker` | Run as a Bazel persistent worker. |

### `jar`

Build JARs, like `jar`. See [JAR Assembly](https://elide.help/docs/toolchain/jvm/jar).

## Native toolchain

### `cc`

Embedded C compiler and linker via LLVM. Compile one freestanding C17 translation unit to a host object or
LLVM IR, or compile and link a function in memory with LLVM ORC LLJIT. Backend arguments follow `--`:

```bash
elide cc -- -c answer.c -o answer.o
elide cc -- -S -emit-llvm answer.c -o answer.ll
elide cc -- --run answer answer.c
```

| Backend option | Effect |
| --- | --- |
| `-c` | Emit a native object; default output is the input basename with `.o` in the current directory. |
| `-S -emit-llvm` | Emit textual LLVM IR; default output has an `.ll` extension. |
| `-o PATH` | Select the output path for object or IR emission. |
| `--run SYMBOL` | JIT-compile and link, invoke a zero-argument `long long` function, and print its value. |
| `--help`, `-h` | Show backend usage. |

Select exactly one output mode. A JIT result is printed to stdout; a successful invocation exits with status zero.
The current command exposes object output, IR output, and in-memory linking rather than executable or shared-library
output. See [Embedded C compiler and linker via LLVM](https://elide.help/docs/toolchain/native/cc) for the complete frontend contract
and distribution support.

### `jextract`

Generate Java FFM sources from C headers with the embedded OpenJDK generator. Generator arguments follow `--`:

```bash
elide jextract -- --output generated --target-package example.ffi --header-class-name NativeApi native/api.h
```

Common generator options are `--output`, `--target-package`, `--header-class-name`, `-I`, `-D`, and `-l`.
`elide jextract -- --help` lists the bundled generator's options. Compile the generated Java and provide the native
library and native-access permission at runtime. For generation and compilation in one invocation, use
[`javac --jextract`](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings).

See [C header bindings with jextract](https://elide.help/docs/toolchain/native/jextract) for a complete shared-library example, symbol
selection, library lookup, and FFM memory lifetimes.

## Setup and tooling

`elide agent` commands are for coding agents and other non-interactive callers; see
[Elide for AI Agents](https://elide.help/docs/agents).

| Command | Flags | Effect |
| --- | --- | --- |
| `elide agent help [TOPIC]` | `-l, --lang LANG` | Print the agent guide, or a documentation topic, as Markdown. |
| `elide agent diagnostics` | `--json` | Print the version, platform, crash-report directory and terminal state. |
| `elide agent bug` | `--kind bug\|perf\|expectation\|feature`, `--json` | Print an issue URL and report body; `--json` prints an `elide.report/1` skeleton. Submits nothing. |
| `elide agent perf -- COMMAND` | `--runs N` (`10`), `--warmup N` (`3`), `--baseline COMMAND`, `--against VERSION`, `--json` | Time a command locally, optionally against another runtime or an installed Elide version. |

```bash
elide agent perf --runs 5 --warmup 1 -- elide run hi.mjs
```

```text
elide run hi.mjs (5 runs, 1 warmup)
  wall 83.4 ms ± 20.1  min 57.7  max 107.0
  cpu  user 15.8 ms  sys 33.1 ms
  rss  max 66.8 MiB
For servers, measure with wrk or oha and paste the results
```

The command after `--` is a full command line, including `elide`. Report fields and flags in detail:
[Report a problem](https://elide.help/docs/agentic-reporting#elide-agent-perf).

### `init`

Create a project from a template. With no flags, opens an editor.

Templates: `android` (Kotlin and Compose app), `java`, `ktjvm`, `web-demo`, `web-simple`, `workspace` (Kotlin library
plus app).

| Flag | Effect |
| --- | --- |
| `--templates` | List template IDs. |
| `-t, --template TEMPLATE` | Select a template. |
| `--parameters` | List template parameters. |
| `--json` | Print `--templates` or `--parameters` as JSON. |
| `-i, --plain` | Ask plain questions instead of opening the editor. |
| `-d, --skip-defaults` | Skip parameters with defaults. Needs `--plain`. |
| `-s, --skip-run` | Do not run Elide after generating. |
| `--overwrite` | Replace existing files. |

### `adopt`

Migrate the project in the current directory to Elide with an AI coding harness
([Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt)). With no flags, it asks for each choice. Exits `0` when the harness
succeeds, `1` when it fails or cannot start, `130` on Ctrl+C.

| Flag | Effect |
| --- | --- |
| `--build STRATEGY` | `elide` (create an Elide build) or `existing` (keep Maven/Gradle). |
| `--harness HARNESS` | `codex`, `claude`, or `omp`. |
| `--approval MODE` | `auto-approve`, `manual-approve`, or `yolo` (bypasses protections). |
| `--log` | Stream harness output as well as logging it. |
| `--prompt-append FILE` | Append guidance to the prompt. Repeatable. |
| `--non-interactive` | Batch mode. Needs all three choices; not `manual-approve`. |

### `help`

Read this documentation offline. A command name prints its section, a slug or title prints the page, and
`options` lists every flag.

<img src="https://elide.help/assets/demos/help.gif" alt="elide help — the complete manual, available offline" width="1591" height="1056" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

| Flag | Effect |
| --- | --- |
| `--format FORMAT` | `auto` (default), `interactive`, or `markdown`. |
| `-w, --width WIDTH` | Maximum width. Default `110`. |
| `-l, --lang LANG` | Display language. |
| `--languages` | List display languages. |
| `--no-animation` | Hide the snow animation; Tab toggles it. |

### `info`

Show binary, platform, language, and network transport details. `--cargo-lockfile` prints the embedded lockfile.

### `studio`

Download and launch Elide Studio for Linux amd64 or macOS arm64:

```bash
elide studio
elide studio --studio-version 0.2.0 --install
```

| Flag | Effect |
| --- | --- |
| `--studio-version VERSION` | Select an exact Studio version, without a `v` prefix. Default: the platform's stable channel. |
| `--install` | Install without launching the desktop UI. |

Studio is installed under Elide's managed user root in `studio/VERSION/PLATFORM`. The root is
`ELIDE_HOME`, then `XDG_DATA_HOME/elide`, then `~/.local/share/elide`. Downloads are checked against
the published size and SHA-256 before installation; matching installations are reused. Each invocation
checks the distribution manifest, so network access is required even when Studio is installed.

The launcher passes its canonical Elide executable path in `ELIDE_BIN`. Studio must consume this
variable to select that runtime. Project-path arguments are not supported yet. Linux requires a
graphical session, WebKitGTK 4.1, and Studio's desktop system dependencies.

### `discord`

Print the community invite link, https://elide.dev/discord, then open it in the Discord desktop app
when one is installed, or in the default browser. Under WSL it opens on the Windows side. `--print`
prints the link only. Nothing is opened when stdout is not a terminal, `CI` is set, or no display is
available; the command exits 0 either way.

### `upgrade`

Update Elide.

| Flag | Effect |
| --- | --- |
| `--check` | Report without applying. |
| `--force` | Update even when current. |
| `--channel CHANNEL` | `release` or `nightly`. Default: this build's channel. |

### `setup`

Install an optional component: `elide setup python`.

| Flag | Effect |
| --- | --- |
| `--channel CHANNEL` | `release` or `nightly`. Default: this build's channel. |
| `--force` | Re-apply an installed component. |

`setup` installs the component for the running version and never upgrades or downgrades Elide. `elide upgrade` keeps installed components.
`setup` refuses package manager installs (Homebrew, apt, RPM, MSI, nix, snap); use the install script:

```bash
curl -sSL --tlsv1.2 elide.sh | bash -s -- --with-python
```

### `use`

Pin a version in `.elideversion` and download it: `elide use 1.6.0`.

| Flag | Effect |
| --- | --- |
| `--channel CHANNEL` | `release` or `nightly`. |
| `--no-install` | Write the pin without downloading. |

Versions are releases (`1.6.0`, `v1.6.0`) or nightly datestamps (`20260921`). `--ignore-version` runs this
binary anyway.

### `lsp`

Start a Language Server Protocol server over stdio. Serves Java; see [Other editors](https://elide.help/docs/connect-ide).

### `mcp`

Start a Model Context Protocol server. See [Project MCP server](https://elide.help/docs/mcp).

| Flag | Effect |
| --- | --- |
| `--mode MODE` | `stdio` (default) or `http` (legacy HTTP+SSE). |
| `--host HOST` | HTTP bind host. Default `localhost`. |
| `--port PORT` | HTTP bind port. Default `8125`. |

## Advanced

Listed by `elide --help-all`.

### `classpath`

Print a resolved classpath for `[<sourceSet>:]<usage>`, e.g. `test:runtime`. Usages: `toolchain`, `processor`,
`compile`, `modules`, `runtime`, `provided`. Default `main:compile`; an unknown usage exits `2`.

| Flag | Effect |
| --- | --- |
| `--offline` | Do not fetch remote resources. |

### `index`

Index the project's resolved Maven dependencies and query that index. Actions: `build`, `status` (default),
`get <address>`, `references <address>`, `used-by <name>`, `resolve <name>`. An address is `maven:group:artifact:version`,
optionally followed by `/symbol` and `#member`; a member is `name(paramType,...)` for methods and
constructors (`<init>`) and the bare name for fields. `build` writes the layers named by `--layers`
(default `l0,l1`; `l2` adds member signatures, `l3` adds outbound references) beside any already built.
`get`, `references` and `resolve` exit `1` for an unknown artifact, symbol, member or name, and `2` when
a layer they need has not been built; run `elide index build --layers=...`.

`build` also compiles main Java and Kotlin sources and refreshes their local reference index.
`references local:<project>/<type>` reads a local class's outbound references; `used-by <type>[#member]` prints
matching package-relative local source files. Queries do not refresh those compiled references.
See [Dependency code index](https://elide.help/docs/toolchain/jvm/code-index) for examples and experimental scope.

| Flag | Effect |
| --- | --- |
| `--layers=<l0,l1,l2,l3>` | Layers `build` writes; `l0` is always included. |
| `--offline` | Do not fetch remote resources. |

### `javadoc`

Generate Javadoc, like `javadoc`. Arguments follow `--`.

| Flag | Effect |
| --- | --- |
| `--theme THEME` | `default` or `elide`. |

### `javaformat`

Format Java with google-java-format, or with the Netflix jfmt dialect given `--jfmt`. Arguments follow `--`. Takes `format`'s `--list-files` and `--list-diffs`. See
[Formatting](https://elide.help/docs/toolchain/jvm/formatting).

### `javap`

Disassemble JVM bytecode, like `javap`. Arguments follow `--`.

### `jdeps`

Analyze JVM class dependencies, like `jdeps`. Arguments follow `--`.

### `ktfmt`

Format Kotlin with ktfmt. Arguments follow `--`. Takes `format`'s `--list-files` and `--list-diffs`.

### `mvn`

Run Maven, like `mvn`: `elide mvn -- package`. See [Native Maven](https://elide.help/docs/toolchain/jvm/native-maven).

| Flag (after `--`) | Effect |
| --- | --- |
| `--flavor NAME` | Plugin set, e.g. `spring@4.1.0`. Detected from `pom.xml` by default. |
| `--mode=MODE` | `native` (default), `mixed`, or `legacy`. |
| `--yes` | Approve downloads without prompting. |
| `--porcelain` | Stream Maven's own output. |

### `native-image`

Build a JVM program into a native executable. Arguments follow `--`. See [Native Image](https://elide.help/docs/toolchain/jvm/native-image).

### `rewrite`

Run OpenRewrite recipes on the project's main Java sources (experimental in 1.6.0). Recipes come from the bundled
libraries and `dependencies.maven.devPackages`; dependency types come from the code index.
`elide rewrite --list` prints available recipes; `elide rewrite <name>…` applies them in order.
The default workflow compiles main sources and filters candidate files when recipe preconditions support it.
See [OpenRewrite](https://elide.help/docs/toolchain/jvm/rewrite) for setup, examples, and compatibility limits.
Exit `1` for an unknown recipe, `2` for a usage error.

| Flag | Effect |
| --- | --- |
| `--dry-run` | Print diffs without applying source changes; build state can still be written. |
| `--list` | List available recipes without compiling main sources. |
| `--no-prefilter` | Skip main-source compilation and parse every main Java source. |
| `--offline` | Do not fetch remote resources. |

### `web`

Web tooling: `elide web build app.ts page.md --out dist` builds files without a manifest. See
[Web Toolchain](https://elide.help/docs/toolchain/web).

| Flag | Effect |
| --- | --- |
| `-o, --out DIR` | Output directory. |

## Global options

Accepted before or after the command name, before any `--`.

### Common flags

| Option | Effect |
| --- | --- |
| `-p, --project PATH` | Project directory. |
| `-f, --flag NAME[=VALUE]` | Set a manifest build flag. |
| `-q, --quiet` | Hide progress. Warnings, errors, and program output still print. |
| `-v, --verbose` / `--debug` | More logging. |
| `--color` / `--no-color` | Force color on or off. |
| `--timeout DURATION` | Time limit, e.g. `30s`, `5m`; `0` disables it. Kills child processes and exits `124`. |
| `--max-mem SIZE` | Heap limit, e.g. `512m`, `8g`. One-shot runs default to `4g`. |
| `--limit NAME=COUNT` | Resource limit: `workers` or `fds`. Repeatable. |
| `--interop` | Share one context across languages ([Languages](https://elide.help/docs/languages)). |
| `-V, --version` | Print the version. |

### Configuration files

Application commands load `.env` then `.env.local` from the invocation directory. `--project` selects
the project directory, including enclosing Elide projects. Existing environment variables win,
including empty values. `.properties` and `.properties.local` supply Java system properties; explicit
VM/engine assignments win. Properties use Java syntax, including escapes and continuations.

| Option | Effect |
| --- | --- |
| `--env-file PATH` | Use explicit dotenv files instead of automatic discovery; repeat to layer files. |
| `--properties-file PATH` | Use explicit Java properties files instead of automatic discovery; repeat to layer files. |
| `--no-env` | Disable dotenv loading. |
| `--no-properties` | Disable properties file loading. |

The current standalone Java `run` path can still read an automatic `.properties` file despite
`--no-properties`. See the [documented isolation limitation](https://elide.help/docs/environment#choose-files-explicitly).

Explicit paths are relative to the invocation directory; later files win. A file flag and its disable
switch cannot be combined. Missing automatic files are silent; malformed or explicitly missing files fail.

Both formats accept dotenvx `encrypted:` values. Supply private keys through `DOTENV_PRIVATE_KEY*` or
`.env.keys` beside the selected files. Key files are read only when decryption is needed and are never
exported as application variables. The dotenvx CLI's file authoring format remains dotenv; Java properties
files use unquoted ciphertext as property values. Shell substitutions are not executed.

Use `${NAME}` for dotenv interpolation. Properties and decrypted payloads are not interpolated. File
loading does not grant additional manifest environment access or sandbox capabilities. In JVM mode,
file variables reach guest environment APIs and child processes; the already-running JVM's own
`System.getenv()` remains its launch environment.

Automatic discovery applies to application and project execution commands, not every standalone tool. Explicit file
flags also select a context for tool commands. See [Environment and properties](https://elide.help/docs/environment) for the exact command
scope, project-directory layering, per-file interpolation, encrypted-value authoring, key lookup order, and examples.

### Sandbox flags

Programs run unconfined until you pass a sandbox flag. See [Sandbox](https://elide.help/docs/sandbox).

| Option | Effect |
| --- | --- |
| `--sandbox[=PROFILE]` | Profile: `trusted`. Bare `--sandbox` confines filesystem access. |
| `--allow-read[=PATHS]` | Grant reads; bare grants all. |
| `--allow-write[=PATHS]` | Grant writes; bare grants all. |
| `--allow-net[=HOSTS]` | Permit network; bare permits all. |
| `--deny-net=HOSTS` | Deny hosts; overrides `--allow-net`. |
| `--allow-run[=CMDS]` | Permit subprocesses; bare permits all. |
| `--deny-run=CMDS` | Deny commands; overrides `--allow-run`. |
| `--allow-env[=NAMES]` | Variables the manifest may read; bare allows all. |
| `--fs-audit` | Log each filesystem access decision. |
| `--allow-threads` | Permit guest threads. Denied by default. |
| `--allow-native` / `--no-native` | Permit or deny guest native access. |

### Diagnostics flags

| Option | Effect |
| --- | --- |
| `--debugger[=MODE\|ADDRESS]` | Attach a debugger: `auto`, `cdp`, `dap`, or a JDWP address (`5005`, `host:5005`). See [Debugging](https://elide.help/docs/debugging). |
| `--debugger-host HOST` | Debugger bind host. Default `127.0.0.1`. |
| `--debugger-port PORT` | Debugger port. Default `4711` (DAP) or `1337` (CDP). |
| `--profiler[=PROFILER]` | `cputracing`, `cpusampling`, or `memtracing`. |
| `--coverage[=auto]` | Collect coverage. |
| `--insights INSIGHTS` | Inject [Insight](https://elide.help/docs/api-insight) scripts. |
| `--error-format FORMAT` | Uncaught errors: `auto` (default), `pretty`, or `plain`. |
| `--abort-on-uncaught-exception` | Abort with `SIGABRT` on an uncaught exception. |
| `--redirect-warnings FILE` | Write warnings to FILE instead of stderr. |

### Version flags

| Option | Effect |
| --- | --- |
| `--use-version VERSION` | Run another installed Elide version. |
| `--ignore-version` | Ignore `.elideversion` and `--use-version`. |

### Advanced flags

| Option | Effect |
| --- | --- |
| `--transport TRANSPORT` | Network transport ([Network transport](#network-transport)). |
| `--locale LOCALE` | CLI locale, e.g. `fr`. |
| `--progress=MODE` | Build progress: `auto` (default), `plain`, or `json`. Also `ELIDE_PROGRESS`. See [Progress output](#progress-output). |
| `-X, --vm KEY=VALUE` | Set a VM property. |
| `--safe-close` | Shut down fully even for one-shot runs. |
| `--pkgst` / `--no-pkgst` | Enable or disable Pkgst routing for embedded package resolvers, overriding `ELIDE_PKGST`. Maven uses its separate setting; see [Repositories](https://elide.help/docs/toolchain/dependencies#repositories). |
| `--otel-endpoint=URL` | Send OpenTelemetry data to this OTLP endpoint. |
| `--otel-provider=PROVIDER` | Send OpenTelemetry data to a provider: `otlp`, `sentry`, `datadog`, `posthog`, `honeycomb`, `grafana`. |
| `--otel-protocol=PROTOCOL` | OTLP protocol: `grpc`, `http/protobuf`, `http/json`. |
| `--otel-shutdown=MODE` | How the final export leaves at exit: `sidecar`, `inline`, `drop`. |
| `--no-otel` | Turn OpenTelemetry export off. |
| `--help-instruments` | List [instrument](#instruments) flags. |

### Python options

CPython flags; put them before the script.

| Option | Effect |
| --- | --- |
| `-I` | Isolated mode. |
| `-B` | Do not write bytecode files. |
| `-E` | Ignore `PYTHON*` environment variables. |
| `-S` | Do not `import site` on startup. |
| `-u` | Unbuffered stdout and stderr. |
| `-P` | Do not prepend an unsafe path to `sys.path`. |
| `-O` | Optimize. Repeatable. |
| `-b` | Warn on bytes/str comparisons. Repeatable. |
| `-x` | Accepted; no effect. |
| `-W ARG` | Warning control. Repeatable. |
| `-m MODULE` | Run a module as `__main__`. |

## Network transport

| `--transport=` | Effect |
| --- | --- |
| `auto` | Default: `v2` on Linux and macOS, `nio` elsewhere. |
| `v2` | Elide's native transport. |
| `epoll`, `kqueue`, `io_uring` | `v2` with that driver. Fails on other platforms. |
| `nio` | Portable transport. |

## Instruments

| Option | Effect |
| --- | --- |
| `--jfr FILE` | Record a JFR file, saved on exit. |
| `--jfr-settings SETTINGS` | `default`, `profile` (default), or a `.jfc` file. |
| `--jitdump DIR` | Write JIT metadata for Linux `perf`. |
| `--heap-dump FILE` | Dump the heap on exit. |
| `--heap-dump-on-oom FILE` | Dump the heap on out-of-memory, then exit `3`. |
| `--vmstat` | Make the process visible to `jps`, `jstat`, and `jcmd`. |

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success, help, or version output. |
| `1` | The command or program failed. |
| `2` | Invalid usage, unknown run target, or a removed command. |
| `3` | Out of memory; `--heap-dump-on-oom` wrote a heap dump. |
| `124` | `--timeout` expired. |
| other | Set by the program or tool. |

Once a timeout starts terminating the process tree, its `124` status takes precedence over child
exit codes produced during cleanup (for example, `137` after `SIGKILL`).

## Output streams

- Program output, test reports, and machine-readable output go to stdout.
- Progress and diagnostics go to stderr.
- Color is off when the stream is not a terminal. `--color`, `FORCE_COLOR`, or `CLICOLOR_FORCE` force
  it on; `--no-color` or `NO_COLOR` turn it off.
- `--quiet` hides progress only.
- `--progress=json` records go to stderr with the rest of the progress; stdout stays the command's product.

## Progress output

`--progress=MODE`, or `ELIDE_PROGRESS=MODE`, picks how builds report progress on stderr.

| Mode | Output |
| --- | --- |
| `auto` | A live display on a terminal. Otherwise, one line per finished task and the verdict. |
| `plain` | A `>` line when each task starts and a line when it finishes, terminal or not. No cursor control. |
| `json` | One JSON object per line for every build event, for editors and other programs. |

Every `json` record has a `type` and a `time` in epoch milliseconds. Other fields:

| `type` | Fields |
| --- | --- |
| `build-started` | `plannedTasks`; `workspace` and `projects` in a workspace |
| `build-configured` | `totalTasks`: tasks the build will run |
| `build-progress` | `completedTasks`, `message` |
| `task-started` | `task`, `project`, `message`, `total` |
| `task-progress` | `task`, `project`, `progress`, `total`, `message` |
| `task-finished` | `task`, `project`, `outcome` (`success`, `failure`, `skipped`), `reason`, `durationMs`, `message` |
| `step-started` | `task`, `project`, `step`, `message`, `total` |
| `step-progress` | `task`, `project`, `step`, `progress`, `message`, `detail` |
| `step-finished` | `task`, `project`, `step` |
| `message` | `level` (`output`, `hint`, `warning`, `error`), `text`, `task`; for a compiler diagnostic, `file` (absolute), `line`, `column` |
| `build-finished` | `outcome` (`success`, `failure`), `exitCode` on failure, `durationMs`, `message` |

Fields without a value are left out. Progress records arrive at most every 100 ms per task or step. A
program's own stderr is passed through unchanged, so read records as the lines that parse as JSON objects.
A `task-finished` record's `durationMs` covers the whole task, its up-to-date check included, so a skipped task
reports the time it took to find it had nothing to do. A `task-finished` record without a `message` belongs to a
task that prints no completion line of its own; label it with its `task`.
`--quiet` keeps only `message` records for warnings and errors.

### Package CDN session default

`ELIDE_PKGST=1` enables Pkgst routing by default for embedded package resolvers.
`true`, `yes`, and `on` also enable it, ignoring case and surrounding whitespace.
Unset, empty, or other values leave routing disabled unless `--pkgst` is passed.
Explicit `--pkgst` and `--no-pkgst` flags take precedence; if both are supplied,
the last flag wins. A launcher can set this environment variable for a session
without changing project files or package-cache locations.

Maven's `--use-pkgst` setting remains independent of this environment default.

---

# elide.pkl reference

URL: https://elide.help/docs/elide-pkl-reference

> Every block and field of Elide's elide.pkl project manifest: metadata, sources, dependencies, JVM, Kotlin, JavaScript, artifacts, testing and workspaces.

`elide.pkl` is the project manifest: it declares builds, dependencies, tests and artifacts. Every file starts with:

```pkl
amends "elide:project.pkl"
```

`elide:` resolves to the schema bundled with the running Elide, for this and every other module (`elide:Jvm.pkl`).
To pin a schema version, amend the published URL:
[`pkl.elide.dev/1.6.3/project.pkl`](https://pkl.elide.dev/1.6.3/project.pkl).

Schema versions are independent of the Elide runtime version. A development schema can be locked before it is
published; the URL above stays on a published version. Published development versions follow `main` until their
stable release, after which they are immutable.

Patch releases within a `MAJOR.MINOR` line only add properties. A minor release can remove, rename or retype
properties and change defaults.

| Pinned version | Result |
| --- | --- |
| Older than the bundled schema | Uses that version; a property removed since fails, naming the version. |
| Newer than the bundled schema | Allowed; a property the running Elide lacks fails, naming the upgrade. |
| Another major version | Refused. |

`elide project export` prints the evaluated manifest as JSON; `elide build --inspect` lists its tasks.

## Project metadata

| Property | Purpose |
| --- | --- |
| `name`, `version`, `description` | Project identity; `version` also names application archives. |
| `entrypoint` | File(s) `elide run` uses when given none. |
| `scripts` | Named shell commands for `elide run NAME`. |
| `sources` | Source sets; see [Sources](#sources). |
| `dependencies` | Maven, npm and PyPI packages; see [Dependencies](#dependencies). |
| `jvm`, `kotlin`, `javascript` | Language and compiler settings. |
| `nativeImage` | Accepted and not applied; set each artifact's `options`. |
| `engine` | Serving contexts; see [Engine contexts](#engine-contexts). |
| `toolchain` | Accepted Elide versions; see [Toolchain](#toolchain). |
| `dev` | Source info, MCP, dev server; see [Dev](#dev). |
| `web` | Web asset settings; see [Web](#web). |
| `artifacts` | Build outputs; see [Artifacts](#artifacts). |
| `testing` | Test reports; see [Testing](#testing). |
| `coverage` | Coverage; see [Testing › Coverage](https://elide.help/docs/toolchain/testing#coverage). |
| `workspace` | Member projects; see [Workspaces](#workspaces). |

`build.flags` holds the `-f`/`--flag` values; see [Build Flags](https://elide.help/docs/toolchain/build-flags).

## Engine contexts

```pkl
engine {
  topology = "prespawn"
  contexts { spawn = "auto"; reserve = 2; min = 1; max = 16 }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `topology` | `"prespawn"`, the only value. | `"prespawn"` |
| `contexts.spawn` | Context count: a positive integer, or `"auto"` (physical cores minus `reserve`, clamped). | `1` |
| `contexts.reserve` | Cores subtracted for `"auto"`; does not pin CPUs. | `2` |
| `contexts.min`, `contexts.max` | Bounds for any count. | `1`, none |
| `maxContexts` | Deprecated fixed count; cannot combine with `contexts`. | — |

Each context evaluates the entry module once, with its own globals, before the server is ready.
`--contexts=N|auto` on `run`, `serve` and `dev` overrides `spawn`. More than one context requires Linux.

## OpenTelemetry block

```pkl
opentelemetry {
  service { name = "checkout"; version = "1.4.2"; environment = "production" }
  resource { ["cloud.region"] = "us-east-1" }

  destinations {
    ["collector"] { endpoint = "http://localhost:4317"; protocol = "grpc" }
    ["datadog"] { provider = "datadog"; site = "us5" }
    ["sentry"] { provider = "sentry" }
  }

  traces { sampler = "parentbased_traceidratio"; ratio = 0.25 }
  metrics { interval = 30.s }
  logs { level = "info" }
  runtime { logs = "warn" }
}
```

Telemetry is off until a destination exists here, in `OTEL_*`/`ELIDE_OTEL_*` variables, or in `--otel-*`
flags. Those override this block, flags first; see [Runtime Environment Variables](https://elide.help/docs/runtime-env-variables#opentelemetry-variables).
`elide run`, `elide serve`, `elide test`, `elide build` and `elide install` in a project read this block; `elide run file.js`
inside a project reads it when `elide.pkl` contains the word `opentelemetry`. See [Configuration](https://elide.help/docs/opentelemetry/configuration). Credentials are never written here: name the environment variable that holds them.

| Property | Meaning | Default |
| --- | --- | --- |
| `enabled` | `false` turns telemetry off, whatever the environment says. | — |
| `service.name`, `.version`, `.namespace`, `.environment` | `service.*` and `deployment.environment.name` resource attributes. | `unknown_service:elide` |
| `resource` | Extra resource attributes. | — |
| `destinations` | Named places to send telemetry. | none |
| `traces.enabled`, `.sampler`, `.ratio`, `.propagators` | Application spans. Samplers as `OTEL_TRACES_SAMPLER`. | on, `parentbased_always_on`, `tracecontext` + `baggage` |
| `metrics.enabled`, `.interval`, `.temporality` | Application metrics. | on, `60.s`, `cumulative` |
| `logs.enabled`, `.level`, `.console` | Application logs; `console` exports `console.*`, Python `logging` and similar output. | on, `info`, on |
| `profiles.enabled`, `.frequency` | Guest CPU profiles (experimental). | off, 100 per second |
| `runtime.traces`, `.metrics`, `.logs` | Elide's own spans, metrics, and log threshold. | on, on, `warn` |
| `propagation.baggage` | W3C baggage on Elide's HTTP server and clients; see [Baggage](#baggage). | off |
| `shutdownTimeout` | Final export deadline at exit. | `5.s` |

Each destination:

| Property | Meaning | Default |
| --- | --- | --- |
| `provider` | `otlp`, `sentry`, `datadog`, `posthog`, `honeycomb`, or `grafana`. | `otlp` |
| `endpoint` | Base URL; replaces a provider's host. `/v1/<signal>` is appended for HTTP. | `http://localhost:4318` (`4317` for gRPC) |
| `protocol` | `grpc`, `http/protobuf`, or `http/json`. | `http/protobuf` |
| `headers`, `headerEnv` | Literal headers, and headers read from named variables. | — |
| `credential` | Variable holding the provider's key: `DD_API_KEY`, `POSTHOG_PROJECT_TOKEN`, `HONEYCOMB_API_KEY`, `GRAFANA_CLOUD_OTLP_CREDENTIAL`. | as listed |
| `dsn` | Variable holding a Sentry DSN. | `SENTRY_DSN` |
| `site` | Datadog site: `us1`, `us3`, `us5`, `eu`, `ap1`, `ap2`, `gov`, or a domain. | `DD_SITE`, then `us1` |
| `region` | `us`/`eu` (PostHog, Honeycomb), or a Grafana Cloud zone such as `prod-us-east-0`. | `us` |
| `signals` | `traces`, `metrics`, `logs`, `profiles`. | what the provider accepts |
| `compression`, `timeout` | Request compression and deadline. | `gzip`, `10.s` |
| `perSignal` | Per-signal `endpoint`, `protocol`, `headers`, `headerEnv`, `compression`, `timeout`. | — |

| Provider | Signals sent by default | Also accepted | Protocols |
| --- | --- | --- | --- |
| `otlp` | traces, metrics, logs | profiles | all |
| `sentry` | traces, logs | — | `http/protobuf` |
| `datadog` | metrics (delta), logs | traces (agentless intake preview) | `http/protobuf`; `http/json` except logs |
| `posthog` | logs | traces | `http/protobuf` |
| `honeycomb` | traces, metrics, logs | — | all |
| `grafana` | traces, metrics, logs | — | `http/protobuf` |

Errors are sent as `exception` log records and span events, plus the `elide.errors` metric, so every provider that
accepts logs, traces, or metrics receives them. See [OpenTelemetry](https://elide.help/docs/opentelemetry) for usage and [Providers](https://elide.help/docs/opentelemetry/providers) for each provider. Asking a provider for a signal or protocol it does not accept is an error.

### Baggage

Elide's HTTP server and clients propagate `traceparent` and `tracestate`. They pass W3C `baggage` only when you turn a
direction on, because baggage arriving from a client is untrusted input:

```pkl
opentelemetry {
  propagation {
    baggage {
      inbound = true
      outbound = true
      allow { "tenant"; "region" }
      spanAttributes { "tenant" }
    }
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `inbound` | Served requests' `baggage` headers become the handler's baggage. | `false` |
| `outbound` | Outgoing `fetch` and HTTP client requests carry the current baggage, unless the request sets `baggage` itself. | `false` |
| `allow` | Keys allowed in both directions. | all keys |
| `spanAttributes` | Inbound keys recorded on the server span as `baggage.<key>`; each must be in `allow`. | none |

A header over 8,192 bytes or 180 members, or with any malformed member, is dropped whole. Baggage received from a
client reaches outgoing requests only when both directions are on. Application code can always read, set and send
baggage through the OpenTelemetry API; `OTEL_PROPAGATORS` affects only that API.

## Sources

```pkl
sources {
  ["main"] = "lib/**/*.kt"
  ["integrationTest"] {
    type = "test"
    dependsOn { "main" }
    paths { "it/**/*.kt" }
    resources { "it/fixtures"; new { from = "it/config"; into = "META-INF" } }
  }
}
```

| Property | Meaning | Empty or absent |
| --- | --- | --- |
| `type` | `"source"`, `"test"`, `"example"` or `"other"`. | Inferred from the name. |
| `paths` | Globs or directories. | `src/<name>/<language>`. |
| `resources` | Paths, or `new { from; into }` roots. | `src/<name>/resources`. |
| `dependsOn` | Source sets visible to this one. | Absent: test and example sets see `main`. Empty: nothing. |

See [Source Sets](https://elide.help/docs/toolchain/source-sets).

## Dependencies

```pkl
dependencies {
  maven {
    packages { "com.google.guava:guava:33.5.0-jre" }
    testPackages { "org.junit.jupiter:junit-jupiter:5.13.4" }
    substitutions { ["com.google.guava:guava"] = "libs/guava-patched.jar" }
  }
  npm { packages { "react@19.0.0" }; devPackages { "typescript@5.6.2" } }
  pypi { packages { "requests>=2" }; optionalPackages { ["dev"] { "pytest>=8" } } }
  spring { version = "4.0.0"; starter { "web" }; testStarter { "test" } }
}
```

| Block | Properties |
| --- | --- |
| `maven` | `packages`, `devPackages`, `modules`, `compileOnly`, `runtimeOnly`, `processors`, `testPackages`, `kotlinPlugins`, `exclusions`, `resolutions`, `substitutions`, `repositories`, `enableDefaultRepositories`, `localRepository` |
| `npm` | `packages`, `devPackages` |
| `pypi` | `packages`, `optionalPackages` (named groups); `elide install` does not install them. |
| `spring` | `version`, `starter`, `testStarter`; expands into `maven`. |

| Value | Form |
| --- | --- |
| Maven entry | `"group:artifact:version[:classifier]"`, a `MavenPackageSpec` (`group`, `name`, `version`, `classifier` or `coordinate`), a local JAR path, or a [project reference](#workspaces). |
| Repository | A URL, or a spec with `url`, `name`, `description`, `credentials` (`username`, `password`, `ntlmDomain`, `ntlmWorkstation`). |
| `resolutions` key | `group:artifact`; the value is an exact version overriding direct and transitive requests, without adding a dependency. See [version resolutions](https://elide.help/docs/toolchain/dependencies#maven-version-resolutions). |
| `substitutions` key | `group:artifact` (any version) or `group:artifact:version`; the value is a file path. |

A substitution keeps the coordinate's transitive dependencies and puts the file on every classpath in its place.
Paths resolve against the declaring manifest; members inherit the root's. Order the task that generates the file
first. Buckets and repositories: [Dependencies](https://elide.help/docs/toolchain/dependencies).

## JVM

```pkl
jvm {
  main = "example.Main"
  target = 25
  flags { "--add-opens=java.base/java.lang=ALL-UNNAMED" }
  defs { ["app.env"] = "dev" }
  java { release = 25; compiler { flags { "-Xlint:all" } } }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `main` | Entrypoint class for `elide run`, JARs, applications and native images. | — |
| `target` | Bytecode target: `8` … `29`, `1.8`, `"latest"`, `"stable"` or `"auto"`. | `"auto"` (21) |
| `javaHome` | Java home for external compiles and forked JVMs. | Elide's own |
| `preferBali` | External JVM runs launch `bali` from `PATH` instead of `java`, or warn and use `java`. | `false` |
| `features.testing` | JUnit dependencies on test sets. | `true` |
| `features.automodules` | Automatic modules for JARs without a descriptor. | `true` |
| `features.graalvm` | `org.graalvm` SDK APIs on the compile classpath. | `false` |
| `java.source`, `java.release` | Source and `--release` levels; see [Java Compiler](https://elide.help/docs/toolchain/jvm/javac#build-projects). | `"auto"` |
| `java.compiler.mode` | `"embedded"` or `"external"`. | `"embedded"` |
| `java.compiler.flags` | Extra `javac` flags. | none |
| `java.sourceSets` | Per-source-set `release` and `flags`; see [Java Compiler](https://elide.help/docs/toolchain/jvm/javac#build-projects). | none |
| `java.bindings` | Named C-header binding groups for jextract; see below. | none |
| `java.sourceSets["<set>"].bindings` | Binding-group names compiled into that source set. | none |
| `flags` | JVM flags for `elide run`, the test JVM and start scripts. | none |
| `defs` | System properties (`-D`), applied wherever `flags` are. | none |
| `debug` | Compile with `-g`. | `true` |

### C header bindings

In 1.6.2, declare native bindings under `jvm.java.bindings` and select them for the Java source set that owns
their generated classes:

```pkl
jvm {
  java {
    bindings {
      ["api"] {
        headers { "native/api.h" }
        packageName = "example.nativeapi"
        headerClassName = "NativeApi"
        includeDirs { "native/include" }
        libraries { "answer" }
      }
    }
    sourceSets {
      ["main"] { bindings { "api" } }
    }
  }
}
```

| Binding property | Contract | Default |
| --- | --- | --- |
| `headers` | Header paths or globs; unmatched globs fail. | required |
| `packageName` | Java package for generated bindings. | required |
| `headerClassName` | Generated header class name. | required |
| `includeDirs` | Header search directories. | empty |
| `defines` | Preprocessor definitions, such as `API_VERSION=1`. | empty |
| `libraries` | Shared-library specifications used by generated lookup code. | empty |
| `useSystemLoadLibrary` | Use system library loading for the declared libraries. | `false` |

Paths resolve against the owning project. A group has one owning source set; dependent sets use its classes
through their normal dependencies. Declaring a group does not select it for compilation. These bindings require
a distribution with native tools. See [C header bindings](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings) for
generation-only targets, exported sources, incremental inputs, and command-line selections, and
[jextract](https://elide.help/docs/toolchain/native/jextract) for native-library loading at runtime.

## Kotlin

```pkl
kotlin {
  apiLevel = "auto"
  languageLevel = "auto"
  compilerOptions { allWarningsAsErrors = true; optIn { "kotlin.time.ExperimentalTime" } }
  features { serialization = true; metro = false }
  toolchain = "embedded"
  plugins { ["org.jetbrains.kotlinx.serialization"] { ["mode"] = "json" } }
}
```

| Property | Meaning |
| --- | --- |
| `apiLevel`, `languageLevel` | `"auto"`, `"latest"`, `"stable"`, or `"2.2"` … `"2.5"`. |
| `compilerOptions` | `optIn`, `progressiveMode`, `extraWarnings`, `allWarningsAsErrors`, `suppressWarnings`, `verbose`, `freeCompilerArgs`, `apiVersion`, `languageVersion`, `includeRuntime`, `noStdlib`, `javaParameters`, `jvmTarget`, `noJdk`, `jvmTargetValidationMode`, `incremental` |
| `features` | `testing`, `kotlinx`, `defaultPlugins`, `serialization`, `coroutines`, `atomicfu`, `powerAssert`, `metro`, `compose`, `reflection`. `compose` defaults to `false` and requires an explicit Compose runtime dependency. |
| `toolchain` | `"embedded"`, `new Kotlin.ManagedKotlinToolchain { version }` or `new Kotlin.CustomKotlinToolchain { path }`. |
| `plugins` | Options per compiler-plugin id, passed as `-P plugin:<id>:<key>=<value>`. |

Defaults: [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc#build-projects).

## JavaScript

| Property | Meaning | Default |
| --- | --- | --- |
| `javascript.ecma` | Declared ECMAScript edition: a year `2015` … `2025`, `"stable"` or `"latest"`. `elide project info` shows it; it does not change which syntax runs or how code is built ([JavaScript language](https://elide.help/docs/javascript-language)). | `"stable"` |

## Toolchain

```pkl
toolchain { engines { ["elide"] = ">=1.6.0" } }
```

| Property | Meaning |
| --- | --- |
| `engines["elide"]` | Version or semver range, or `new { version = "…" }`; a running Elide outside it fails validation. |
| `engines[<other>]` | Accepted, not enforced. |

## Dev

```pkl
dev {
  source { platform = "github"; project = "example/app" }
  mcp {
    registerElide = true
    advice = true
    resources { new { path = "docs/ARCHITECTURE.md"; name = "architecture" } }
  }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `source.platform`, `source.project`, `source.subpath` | Source host: `"github"`, `"gitlab"`, `"bitbucket"`, `"git"` or another name. | — |
| `mcp.registerElide` | Register Elide as an MCP tool. | `true` |
| `mcp.advice` | Expose `elide project advice` as an MCP resource. | `true` |
| `mcp.resources` | Extra MCP resources: `path`, `name`, `description`, `mimeType` (detected if omitted). | none |
| `server.host`, `server.port` | Unused by `elide dev`, which takes `--host`/`--port` (default `127.0.0.1:3000`). | `"0.0.0.0"`, `8080` |

## Web

| Property | Meaning | Default |
| --- | --- | --- |
| `web.css.minify` | Minify built CSS. | `true` |
| `web.css.targets` | Browser targets: `new { browser = "chrome"; version = "120" }`. | none |
| `web.minifyHtml` | Minify rendered HTML. | `true` |
| `web.browsers` | Browser targets for all outputs; `css.targets` overrides it for CSS. | none |

See [Web Toolchain](https://elide.help/docs/toolchain/web#manifest-settings).

## Artifacts

```pkl
import "elide:Jvm.pkl" as Jvm

artifacts {
  ["app"] = new Jvm.Jar {
    name = "app.jar"
    options { entrypoint = "example.Main" }
    sources { "main" }  // optional; empty packages every non-test source set
  }
}
```

The key names the build task. Outputs go under `.dev/artifacts/<kind>/`.

| Type | Module | Fields |
| --- | --- | --- |
| `Jar`, `SourceJar`, `JavadocJar`, `JvmApplication` | `elide:Jvm.pkl` | [JAR Assembly](https://elide.help/docs/toolchain/jvm/jar#project-artifacts) |
| `NativeImage` | `elide:NativeImage.pkl` | [Native Image](https://elide.help/docs/toolchain/jvm/native-image#project-artifact) |
| `WebImage` | `elide:NativeImage.pkl` | [WebImage](#webimage) |
| `ContainerImage` | `elide:Container.pkl` | [JVM Containers](https://elide.help/docs/toolchain/jvm/containers) |
| `StaticSite` | `elide:Web.pkl` | [Static Sites](https://elide.help/docs/toolchain/web/static-site) |

| Common field | Meaning |
| --- | --- |
| `dependsOn` | Artifact names to build first. |
| `name` (JARs) | `"app"` and `"app.jar"` both give `app.jar`; a `SourceJar` gives `app-sources.jar`. |

### WebImage

`WebImage` takes the [`NativeImage`](https://elide.help/docs/toolchain/jvm/native-image#project-artifact) fields `from`, `name`, `entrypoint`,
`moduleName`, `dependsOn` and `options`, has no `type`, and adds:

| Property | Values | Default |
| --- | --- | --- |
| `backend` | `"wasm-gc"` (host GC) or `"wasm-lm"` (linear memory). | `"wasm-gc"` |
| `runtime` | `"generic"`, `"browser"` or `"node"`. | `"generic"` |
| `autoRun` | Start the program when the loader loads. | `true` |
| `sourceMap` | Emit a JavaScript source map. | `false` |

`entrypoint` (or `jvm.main`) is required even with `autoRun = false`. Do not pass raw flags for these four settings.
Guide: [WebImage](https://elide.help/docs/toolchain/jvm/webimage#build-a-complete-project); flag-based artifacts:
[migration](https://elide.help/docs/toolchain/jvm/webimage#compile-without-a-project-manifest).

## Publishing

```pkl
publishing {
  maven {
    groupId = "dev.example"
    artifactId = "example"                 // default: the project name
    localRepository = "~/.m2/repository"   // the default
    artifacts { "lib"; "lib-sources" }      // default: every Jar, SourceJar and JavadocJar
    pom {
      name = "Example"
      description = "An example library."  // default: the project description
      url = "https://example.dev"
      licenses { new { name = "Apache-2.0"; url = "https://www.apache.org/licenses/LICENSE-2.0" } }
      developers { new { id = "jdoe"; name = "J. Doe" } }
      scm { url = "https://github.com/example/example" }
    }
    repositories {
      ["internal"] = "https://repo.example.dev/releases"  // or new Jvm.MavenRepositorySpec { url = … }
      ["central"] = new Publishing.CentralPortal {}       // Maven Central; import "elide:Publishing.pkl" as Publishing
    }
    signing { gpg { keyName = "0123ABCD" } }  // optional; omit keyName for gpg's default key
  }
}
```

`elide publish` builds the selected JARs and installs them with a POM into the local Maven repository. The version is
the project's `version`. A publication needs a `groupId`, a `version` and exactly one `Jar`. A `SourceJar` publishes
under its `classifier` (default `sources`), a `JavadocJar` under `javadoc`. A relative `localRepository` resolves
against the manifest that declares it.

| Manifest | Published POM |
| --- | --- |
| `packages`, `modules` | `compile` dependencies |
| `runtimeOnly` | `runtime` dependencies |
| `compileOnly`, `devPackages`, `processors`, `kotlinPlugins`, `testPackages` | Omitted |
| Versionless `exclusions` | An `<exclusion>` on every dependency |
| A sibling project | The sibling's own publishing coordinates |
| A `Jar.from` sibling | Its `packages`, `modules` and `runtimeOnly`, unless already listed |
| A local JAR path | An error; consumers cannot resolve it |

The POM also lists libraries Elide puts on a Kotlin project's classpath without a declaration, as `compile`
dependencies, because consumers need them at run time: `kotlin-stdlib` and `kotlin-reflect` at the project's Kotlin
version, and the runtimes `kotlin.features` turns on (`kotlinx-coroutines-core`, `kotlinx-serialization`, the Metro
runtime). These appear in the published POM even though `elide.pkl` doesn't name them. Turn one off where it comes
from (`kotlin.features`, or `kotlin.compilerOptions.noStdlib`), or declare it yourself to pin a different version.
`jvm.features.graalvm` adds the GraalVM SDK at `runtime` scope.

`elide publish --to <name>` publishes to a repository from `repositories` instead, with `.md5`, `.sha1`, `.sha256` and
`.sha512` checksums for every file. Credentials come from `ELIDE_MAVEN_<NAME>_USERNAME` and
`ELIDE_MAVEN_<NAME>_PASSWORD`, where `<NAME>` is the repository name uppercased with every character other than a
letter or digit turned into `_` (`internal` → `ELIDE_MAVEN_INTERNAL_USERNAME`, `my-repo` → `ELIDE_MAVEN_MY_REPO_…`),
and otherwise from the repository's `credentials`. Two names that map to the same variables (`my-repo` and `my_repo`)
are refused. Plain `http://` repositories other
than localhost are refused without `--allow-http-repositories`.

With `signing` set, a remote publish signs every file with the `gpg` binary (`<file>.asc`); `signing {}` signs with
`gpg`'s default key, and `signing { gpg { keyName = "…" } }` picks one. A local publish signs only with
`--sign`, and `--no-sign` turns signing off. `gpg-agent` asks for the passphrase. For CI, set `ELIDE_GPG_PASSPHRASE` and
Elide passes it to `gpg` through loopback pinentry. Elide never reads the key itself.

A `CentralPortal` repository publishes to Maven Central through the Central Publisher Portal. Create a user token in the
Portal and pass it as `ELIDE_MAVEN_<NAME>_USERNAME` and `ELIDE_MAVEN_<NAME>_PASSWORD`. Every project of the run goes
into one signed, checksummed bundle and one deployment, which the Portal validates and releases as a unit. Elide waits
until the Portal has validated it, and fails with the Portal's errors if it does not pass. `--no-wait` returns right
after the upload instead.

| `CentralPortal` property | Meaning | Default |
| --- | --- | --- |
| `publishingType` | `USER_MANAGED`: release the validated deployment in the Portal yourself. `AUTOMATIC`: release once validated. | `USER_MANAGED` |
| `url` | Portal to upload to. | `https://central.sonatype.com` |

Before building, Elide checks what Central requires and reports everything missing at once: `pom` `name`,
`description`, `url`, `licenses`, `developers` and `scm.url`; a `SourceJar` and a `JavadocJar` artifact; signing (so
`--no-sign` is refused); and a version that is not a `-SNAPSHOT`.

In a workspace, members inherit the root's `publishing` block except `artifactId` and `artifacts`, and a member's own
settings win field by field. Repositories are inherited by name. A project that builds no JAR publishes nothing it
inherits.

To publish only some of a workspace's projects, name them (`elide publish core util`) rather than changing their
`publishing` blocks, or pass `--skip-existing` to leave out every version already in the target; see
[`elide publish`](https://elide.help/docs/cli-references#publish).

## Testing

```pkl
import "elide:Testing.pkl" as Testing

testing { reports { Testing.xmlReport() } }
```

| Property | Meaning |
| --- | --- |
| `testing.reports` | Report formats for every runner, written to `.dev/reports/tests/<language>/<source-set>/`; same as `--reporter=junit`. |

## Coverage

```pkl
import "elide:Coverage.pkl" as Coverage

coverage {
  enabled = true
  scope = "tests"
  jvm {
    excludes { "org.example.generated.*" }
    reports { Coverage.xmlReport(); Coverage.htmlReport() }
  }
  js { paths { "src" } }
}
```

| Property | Meaning | Default |
| --- | --- | --- |
| `coverage.enabled` | Collect coverage without `--coverage`. | `false` |
| `coverage.scope` | Tasks that collect: `"tests"`, `"runs"` or `"all"`. `--coverage` always covers the task it is passed to. | `"tests"` |
| `coverage.jvm.reports` | JVM report formats: `Coverage.htmlReport()`, `xmlReport()`, `csvReport()`, written to `.dev/reports/coverage/jvm/<task>/`. | none |
| `coverage.jvm.excludes` | Class-name patterns (`*`, `?`) left uninstrumented, such as generated code. | none |
| `coverage.js.paths` | JavaScript and TypeScript source roots to report, as LCOV in `.dev/reports/coverage/js/lcov.info`. Empty reports the whole project. | none |

See [Testing › Coverage](https://elide.help/docs/toolchain/testing#coverage).

## Workspaces

```pkl
workspace { members { "core"; "app" } }
```

Each member is a directory with its own `elide.pkl`; members cannot have members. `elide init --template workspace`
creates a root with a `core` library and an `app` that depends on it.

| Behavior | Rule |
| --- | --- |
| Build scope | From the root, `elide build`/`elide test` cover every project; from a member, only that member. |
| Cross-project tasks | `elide build core:compile-kotlin-main`, or `elide build core` for its default tasks. |
| Shared state | Resolved dependencies and build state live in the root `.dev`; outputs stay in each project's `.dev`. |
| Version pins | A member can omit a Maven version and take the root's; a conflicting version is an error. |

```pkl
// core/elide.pkl
import "elide:Jvm.pkl" as Jvm

dependencies {
  maven {
    packages { "com.google.guava:guava" }  // version from the root
  }
}

artifacts {
  ["jar"] = new Jvm.Jar { name = "core" }
}
```

```pkl
// app/elide.pkl
local core = project("core")

dependencies { maven { packages { core } } }
```

| Reference | Meaning |
| --- | --- |
| `project("core")` | The project's `Jvm.Jar` artifact and its compile classpath, built when needed. JVM sources alone do not count. |
| `project("core").artifact("fat")` | Pick one JAR when the project declares several. |
| `project("core").friend()` | Also see `core`'s Kotlin `internal` declarations, not its dependencies'. Only in `packages`, `modules`, `compileOnly`, `testPackages`. |
| `new Jvm.Jar { from { core } }` | Unpack `core`'s JAR into this one, building it first; no dependency needed. |
| `module.project("core")` | Use in place, inside an object body; bare `project(…)` does not resolve there. |
| `new Artifacts.ProjectArtifact { project = "core"; artifact = "fat" }` | Explicit form; `import "elide:Artifacts.pkl" as Artifacts`. |

A reference to a project with no JAR, or a misplaced `friend()`, fails when the build is configured.

## Micronaut

See the [Micronaut guide](https://elide.help/docs/toolchain/jvm/micronaut) for complete build, test, and Native Image workflows.

Use the **Micronaut Core version**, not the platform BOM version. Core module names expand to
`io.micronaut:micronaut-<name>:<version>`; the matching `micronaut-inject-java` processor is installed
and used by Java compilation. Independently versioned modules, such as Micronaut Serialization,
remain ordinary Maven coordinates.

```pkl
dependencies {
  micronaut {
    version = "4.10.23"
    modules { "runtime"; "http-server-netty" }
    testModules { "http-client" }
  }
}
jvm {
  micronaut {
    config {
      micronaut {
        application { name = "example" }
        server { port = 8080 }
      }
      custom {
        enabled = true
        origins = new Listing { "https://example.com" }
      }
    }
  }
}
```

The optional `jvm.micronaut.config` accepts arbitrary JSON-compatible keys and values. Elide renders
it with Pkl's JSON renderer and stages `application.json` on production classpaths and in JARs.
Elide adds the matching `micronaut-jackson-core` runtime dependency for the JSON configuration loader.
When supplying your own JSON resources, declare that loader yourself.
An authored `application.json` conflicts with this generated resource and fails the build; omit the
block to supply your own configuration through resources. Environment-specific files may still be
provided through resources. Changes to generated configuration invalidate resource and JAR tasks.

Direct `io.micronaut:micronaut-*` Core dependencies also select the matching processor after workspace
version pins are applied. Conflicting Core or processor versions fail validation. Satellite-module
versions and transitive-only framework dependencies do not select a processor: declare a Core module
or use the shorthand. This integration uses the existing Java annotation-processing path; it does not
enable KSP or Kotlin-source annotation processing in project builds.

Runnable examples are in
[`tools/smoketests/micronaut-pkl`](https://github.com/elide-dev/elide/tree/main/tools/smoketests/micronaut-pkl)
and
[`tools/smoketests/micronaut-resources`](https://github.com/elide-dev/elide/tree/main/tools/smoketests/micronaut-resources).
The [sample guide](https://github.com/elide-dev/elide/blob/main/docs/micronaut-samples.md) includes run,
packaging, and smoke-test commands.

## Test containers

`testing.testcontainers` describes disposable infrastructure shared by the project's selected test runners.
Declare named entries in `containers`, each with an `image`, optional `command` and `environment`, exposed
TCP `ports`, and a `wait` strategy. `environment` on the outer block binds container connection values
into JavaScript/TypeScript and JVM test environments. `startupTimeoutSeconds` bounds total startup.

See [Shared test containers](https://elide.help/docs/toolchain/testing#shared-test-containers) for the complete configuration,
readiness options, prerequisites, and lifecycle.

---

# Environment variables

URL: https://elide.help/docs/env-variables

> Which environment variables Elide programs see in `process.env`, the TMPDIR and ELIDE_SYS_TMP values Elide sets, loading .env files, and `--allow-env`.

Programs read their application environment through `process.env`; writes do not reach subprocesses.

## Variables Elide sets

| Variable | Value |
| --- | --- |
| `TMPDIR` | A per-run directory, removed on exit. `TMP` and `TEMP` on Windows. |
| `ELIDE_SYS_TMP` | The system temporary directory. `os.tmpdir()` returns it. |

Elide does not set `NODE_ENV`.

## Dotenv files

Since Elide 1.6.2, application commands load `.env` and then `.env.local` before the program starts. Inherited
environment variables take precedence. Use `--env-file` to choose files explicitly or `--no-env` to disable automatic
loading. See [Environment and properties](https://elide.help/docs/environment) for directory selection, precedence and encrypted values.

`process.loadEnvFile([path])` also remains available to load a file from JavaScript; its default path is `./.env`.

## Security

`elide.pkl` reads only a short list of variables; `--allow-env[=NAMES]` lets it read more
([Build Flags](https://elide.help/docs/toolchain/build-flags#environment-variables)). It does not filter `process.env`.

Variables that configure Elide itself: [Runtime Environment Variables](https://elide.help/docs/runtime-env-variables).

---

# Runtime environment variables

URL: https://elide.help/docs/runtime-env-variables

> Environment variables that configure Elide itself, such as ELIDE_HOME, ELIDE_LOG, ELIDE_ERROR_FORMAT and ELIDE_EDITOR, plus diagnostic variables and variables from other tools that Elide honors.

These variables configure Elide. Programs also see them in [`process.env`](https://elide.help/docs/env-variables).
For application dotenv files, Java properties, file selection, and encryption, see
[Environment and properties](https://elide.help/docs/environment).

| Variable | Purpose |
| --- | --- |
| `ELIDE_HOME` | Install directory for Elide versions. Default `$XDG_DATA_HOME/elide` or `~/.local/share/elide`. |
| `ELIDE_AUTO_INSTALL` | `1` downloads a pinned `.elideversion` without asking. |
| `ELIDE_LOCALE` | CLI locale, as `--locale`. |
| `ELIDE_LOG` | Log filter, e.g. `debug`. |
| `ELIDE_LOG_STYLE` | Log color: `auto`, `always`, or `never`. |
| `ELIDE_ERROR_FORMAT` | `plain` forces plain uncaught-error output, as `--error-format=plain`. |
| `ELIDE_REPL_HISTORY` | REPL history database. Default `~/.local/share/elide/repl/history.db` (Linux). |
| `ELIDE_EDITOR` | `code` or `idea` links error locations to VS Code or IntelliJ. Uses `EDITOR` if unset. |
| `ELIDE_CRASH_ROOT` | Directory for crash reports. |
| `ELIDE_AGENT` | `1` forces agent output; `0` turns agent detection off. See [AI Agents](https://elide.help/docs/agents). |
| `ELIDE_MCP_TOKEN` | Token for `elide mcp --mode http`. Random if unset. |
| `ELIDE_DEFER_EXIT` | Linux: `0` makes the process free its memory before it exits. |
| `ELIDE_SYS_TMP` | Set by Elide: the system temporary directory. |
| `ELIDE_HTTP_USER_AGENT` | `User-Agent` for `fetch`. Default `Elide/<version>`. |
| `ELIDE_HTTP_NATIVE_WORKERS` | `v2` transport workers for a server outside an application context (default cores ÷ 4, 1 to 8). `run`, `serve` and `dev` ignore it; their I/O threads follow the context count. |
| `ELIDE_NETTY_EVENT_LOOPS` | HTTP client and server I/O threads. Default `min(4, cores)`. |
| `ELIDE_TRANSPORT_V2` | `1`, `true`, `yes`, or `on` selects `--transport=v2` when no flag is given. |
| `ELIDE_HTTP_FALLBACK` | `v1` serves Unix domain socket requests through `nio`; `none` (default) fails them. |
| `NODE_TLS_REJECT_UNAUTHORIZED` | `0` disables TLS certificate checks for `fetch`. Warns once. |
| `NODE_USE_SYSTEM_CA` | `1` trusts the system certificate store for `fetch`. |
| `NODE_EXTRA_CA_CERTS` | PEM file of extra CA certificates for `fetch`. |
| `ELIDE_MAVEN_TLS_EXTRA_CA` | PEM file of extra CA certificates for Maven downloads. |
| `ELIDE_MAVEN_<NAME>_USERNAME`, `ELIDE_MAVEN_<NAME>_PASSWORD` | Credentials for `elide publish --to <NAME>`; `<NAME>` is the repository name uppercased with other characters turned to `_`. See [Maven publishing](https://elide.help/docs/toolchain/jvm/publishing). |
| `ELIDE_GPG_PASSPHRASE` | Passphrase for `elide publish` to sign with `gpg` in CI. See [Maven publishing](https://elide.help/docs/toolchain/jvm/publishing). |
| `ELIDE_PKGST_NPM_ENDPOINT` | npm proxy URL for `--pkgst`. Default `https://npm.pkg.st`. |
| `ELIDE_PKGST_PYPI_ENDPOINT` | PyPI proxy URL for `--pkgst`. Default `https://pypi.pkg.st`. |
| `ELIDE_REMOTE_CACHE` | Shared build cache URL. See [Build cache](https://elide.help/docs/toolchain/build-tasks#build-cache). |
| `ELIDE_REMOTE_CACHE_TOKEN` | Bearer token for the shared cache. |
| `ELIDE_REMOTE_CACHE_USERNAME` | Basic-auth user for the shared cache. |
| `ELIDE_REMOTE_CACHE_PASSWORD` | Basic-auth password for the shared cache. |
| `ELIDE_REMOTE_CACHE_POLICY` | `eager` (default) or `smart`. |
| `ELIDE_REMOTE_CACHE_PULL` | `false` stops downloads from the shared cache. |
| `ELIDE_REMOTE_CACHE_PUSH` | `false` stops uploads to the shared cache. |
| `ELIDE_BUILD_TELEMETRY` | `1`, a file, or a directory writes a build trace ([Build Tasks](https://elide.help/docs/toolchain/build-tasks)). |
| `ELIDE_KOTLINC_ABI_STRIP` | `0` makes `kotlinc --abi-only` keep full code generation instead of stripping function bodies. |
| `ELIDE_WORKER_CLASSPATH_CACHE` | `0` turns `javac --classpath-cache` off. |
| `ELIDE_WORKER_CLASSPATH_CACHE_MAX_HANDLES` | Most classpath JARs `javac --classpath-cache` keeps open. Default one per MiB of heap, between 512 and 65536. |

## Configuration decryption keys

Elide 1.6.2 accepts dotenvx-compatible encrypted values in dotenv and Java properties files.

| Variable | Purpose |
| --- | --- |
| `DOTENV_PRIVATE_KEY` | Private key for decrypting `encrypted:` configuration values. |
| `DOTENV_PRIVATE_KEY_*` | Additional named private keys, such as `DOTENV_PRIVATE_KEY_PRODUCTION`. A suffix does not select a configuration file. |

Supply keys through the inherited environment or `.env.keys` beside selected configuration sources.
Inherited assignments override matching names in key files. Key files are read only when an effective encrypted value
requires decryption; their entries are not exported as application configuration. Inherited key variables retain
ordinary inherited-environment visibility. Do not put private-key assignments in application dotenv or properties
files: Elide rejects them. `DOTENV_PUBLIC_KEY*` configuration entries are metadata and are omitted from loaded values.

Keep `.env.keys` out of version control and use your CI secret store for inherited keys. See
[Encrypted values](https://elide.help/docs/environment#encrypted-values) for file lookup order, supported formats, and examples.

## Diagnostics

| Variable | Purpose |
| --- | --- |
| `ELIDE_ENGINE_LOG` | Print low-level runtime log records to stderr. |
| `ELIDE_DIAG_STARTUP` | Print startup phase timings to stderr. |
| `ELIDE_TRANSPORT_DIAGNOSTICS` | `1` prints network transport statistics to stderr. |
| `ELIDE_TRACE_PROCESSORS` | `1` prints each Java annotation processor class to stderr as it loads. |

## Variables from other tools

| Variable | Read by | Purpose |
| --- | --- | --- |
| `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG` | CLI | Locale when `ELIDE_LOCALE` is unset, first one set wins. Give a region (`fr_FR.UTF-8`); a bare language such as `fr` is ignored. |
| `JDK_JAVAC_OPTIONS` | `elide javac` | Extra `javac` options, as with the JDK's `javac`. Output then uses `javac`'s own format. |
| `DOCKER_CONFIG` | Container builds | Directory of the Docker `config.json` whose `auths`, `credHelpers` and `credsStore` supply registry credentials. Default `~/.docker`. |
| `UV_DEFAULT_INDEX`, `UV_INDEX_URL` | Python installs | PyPI index; when set, `--pkgst` leaves it unchanged. |
| `NODE_REDIRECT_WARNINGS` | JavaScript | Append process warnings to this file instead of stderr. |

## OpenTelemetry variables

Elide reads the standard OpenTelemetry variables. They override the [`opentelemetry` block](https://elide.help/docs/elide-pkl-reference#opentelemetry-block)
and are overridden by `--otel-*` flags; see [Configuration](https://elide.help/docs/opentelemetry/configuration). Invalid values are ignored.

| Variable | Purpose |
| --- | --- |
| `OTEL_SDK_DISABLED` | `true` turns telemetry off. |
| `OTEL_SERVICE_NAME` | `service.name`. |
| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes, `key=value,...` (percent-encoded values). |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL; `/v1/<signal>` is appended for HTTP. Creates an `otlp` destination if none exists. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/protobuf` (default), or `http/json`. |
| `OTEL_EXPORTER_OTLP_HEADERS` | Request headers, `key=value,...`. Treated as secrets. |
| `OTEL_EXPORTER_OTLP_COMPRESSION` | `gzip` (default) or `none`. |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | Request timeout in milliseconds. Default `10000`. |
| `OTEL_EXPORTER_OTLP_CERTIFICATE` | PEM file of trusted certificates, replacing the system trust store. |
| `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, `OTEL_EXPORTER_OTLP_CLIENT_KEY` | PEM client certificate chain and private key for mutual TLS. Set both. |
| `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_*` | Per-signal `ENDPOINT` (used as given), `PROTOCOL`, `HEADERS`, `COMPRESSION`, `TIMEOUT`, `CERTIFICATE`, `CLIENT_CERTIFICATE`, `CLIENT_KEY`. |
| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | `always_on`, `always_off`, `traceidratio`, or `parentbased_*` (default `parentbased_always_on`), and the ratio. |
| `OTEL_PROPAGATORS` | `tracecontext`, `baggage`, or `none`, for the OpenTelemetry API in applications. Default `tracecontext,baggage`. Does not turn on baggage for Elide's HTTP server and clients. |
| `OTEL_METRIC_EXPORT_INTERVAL` | Metric export interval in milliseconds. Default `60000`. |
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `cumulative` (default) or `delta`. |
| `OTEL_METRICS_EXEMPLAR_FILTER` | `trace_based` (default: measurements inside a sampled span), `always_on`, or `always_off`. |
| `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` | `logs` records exceptions as log records only; `logs/dup` (default) also adds `exception` span events. |
| `OTEL_{TRACES,METRICS,LOGS}_EXPORTER` | `none` turns that signal off, for applications and Elide alike. `otlp` with no destination configured sends that signal to `http://localhost:4318` (`4317` for gRPC). |

`OTEL_EXPORTER_OTLP_*` apply to every destination using the `otlp` provider. Elide adds a shorthand
for the [provider presets](https://elide.help/docs/elide-pkl-reference#opentelemetry-block):

| Variable | Purpose |
| --- | --- |
| `ELIDE_OTEL_PROVIDER` | Adds a destination for a provider: `otlp`, `sentry`, `datadog`, `posthog`, `honeycomb`, or `grafana`. |
| `ELIDE_OTEL_REGION` | Provider site or region, e.g. `us5` (Datadog), `eu` (PostHog, Honeycomb), `prod-us-east-0` (Grafana). |
| `ELIDE_OTEL_SIGNALS` | Signals for that destination, e.g. `traces,logs`. Default: the provider's default signals. |
| `ELIDE_OTEL_BAGGAGE_INBOUND` | `true` admits served requests' `baggage` headers. Default `false`. |
| `ELIDE_OTEL_BAGGAGE_OUTBOUND` | `true` sends the current baggage on outgoing HTTP requests. Default `false`. |
| `ELIDE_OTEL_BAGGAGE_ALLOW` | Comma-separated baggage keys allowed in both directions. Default: all keys. |
| `ELIDE_OTEL_PROFILES` | `true` samples guest CPU profiles at 100 per second, or set a frequency such as `49`. Default off. |
| `ELIDE_OTEL_RUNTIME_INTERNAL_TRACES` | `true` includes high-volume library spans such as Compio task polls. Requires runtime tracing and a configured destination. Default `false`. |

Provider credentials come from their usual variables: `SENTRY_DSN`, `DD_API_KEY` (and `DD_SITE`),
`POSTHOG_PROJECT_TOKEN`, `HONEYCOMB_API_KEY`, and `GRAFANA_CLOUD_OTLP_CREDENTIAL` (`<instance id>:<token>`).

```sh
ELIDE_OTEL_PROVIDER=honeycomb HONEYCOMB_API_KEY=... elide serve app.ts
```

---

# Elide for Node users

URL: https://elide.help/docs/elide-for-node

> Switching from Node.js to Elide: what runs unchanged, which commands and APIs change, TypeScript without a compile step, benchmarks and trade-offs.

Elide runs JavaScript and TypeScript with Node APIs and npm packages. Check your application's modules and framework
before switching.

## Check your application

For an HTTP app, start with [framework compatibility](https://elide.help/docs/http-service#frameworks): Hono has a runnable example;
Express 5 has body-middleware limitations; Fastify 5 imports an unavailable module. Check the
[API Overview](https://elide.help/docs/api-overview) for other `node:*` modules your app imports.

The [Compatibility Matrix](https://elide.help/docs/compatibility) reports API test-suite results. Run your application's tests and exercise
its request handlers to check the dependencies and code paths you use.

## Run the same code

```bash
elide app.js                    # or: elide run app.js
elide app.ts                    # no compile step, no tsconfig.json
elide install --ecosystems=npm  # dependencies from package.json
elide test                      # node:test files
```

- Built-ins load with or without the `node:` prefix.
- CommonJS and ES modules both work.
- `http.createServer` serves as in Node, as does a module that default-exports a `fetch` handler or calls
  `Elide.serve({ fetch })`.

For a complete first example, follow [JavaScript and TypeScript](https://elide.help/docs/web). For a server, follow
[Build an HTTP service](https://elide.help/docs/http-service). If an installed package cannot be imported, see
[Module not found after `elide install`](https://elide.help/docs/troubleshooting#module-not-found-after-elide-install).

## What changes

| Node | Elide |
| --- | --- |
| `node app.js` | `elide app.js` |
| `npm install` | `elide install --ecosystems=npm`; plain `elide install` skips npm |
| `package-lock.json` | `aube-lock.yaml` |
| `npm run build` | `elide run build` |
| `npx tool` | `elide run tool` for a tool in `node_modules/.bin`; no download-and-run |
| `node --test` | `elide test` |
| `node --inspect app.js` | `elide run --debugger=cdp app.js` |
| `node --watch app.js` | No equivalent |
| `node --env-file=.env app.js` | Call `process.loadEnvFile()` in code |
| `node --permission --allow-fs-read=.` | `elide --allow-read=. app.js`; see [Sandbox and Limits](https://elide.help/docs/sandbox) |
| `node:worker_threads` | Same module; `new Worker` honors only `workerData`, `eval`, `transferList` and `env` |
| `node:sqlite` `DatabaseSync` | `Database` from `elide:sqlite`; see [SQLite](https://elide.help/docs/api-sqlite#nodesqlite-and-bunsqlite) |

Elide does not set `NODE_ENV`.

## Weaknesses

- `node:http2`, `node:cluster`, `node:inspector` and `node:wasi` throw `ERR_UNKNOWN_BUILTIN_MODULE`.
- `https.createServer` throws `ERR_HTTPS_SERVER_UNSUPPORTED`; terminate TLS in front of `http.createServer`.
- No `WebSocket` global.
- No bundler: `elide web build` transforms each file and keeps its imports.
- No macOS Intel build; macOS releases are Apple Silicon only.

## Benchmarks

Hello-world startup with `hyperfine -N -w 10 -r 100` on a 24-core AMD Ryzen Threadripper PRO 9965WX Linux workstation:

| Runtime | Command | Mean |
| --- | --- | --- |
| Node | `node hello.js` | 11.70 ± 0.90 ms |
| Elide | `elide run hello.js` | 1.43 ± 0.06 ms |
| Bun | `bun hello.js` | 1.63 ± 0.18 ms |
| Deno | `deno run hello.js` | 6.31 ± 0.30 ms |

Elide's measured mean is lower than Bun's in this recording. In the separate non-pipelined HTTP comparison,
Elide served 635,510 requests/s and Node 24.22.0 LTS served 123,519 requests/s with the same load and CPU budget.
See [HTTP serving](https://elide.help/docs/benchmarks#http-serving) for the settings, latency, and raw reports.

Versions, setup, and recordings: [Benchmarks](https://elide.help/docs/benchmarks).

## Strengths

- Runs `.ts`, `.mts` and `.cts` files directly.
- Scopes network access by host and subprocesses by command: `--allow-net=api.example.com`, `--allow-run=git`.
- Limits workers, open files, heap and run time: `--limit=workers=4`, `--limit=fds=128`, `--max-mem=512m`,
  `--timeout=30s`.
- Includes SQLite, PostgreSQL and MySQL drivers as `elide:sqlite`, `elide:postgres` and `elide:mysql`.

## Next steps

- [Installation](https://elide.help/docs/installation)
- [JavaScript and TypeScript](https://elide.help/docs/web)
- [Build an HTTP service](https://elide.help/docs/http-service)
- [Troubleshooting](https://elide.help/docs/troubleshooting)
- [Sandbox and Limits](https://elide.help/docs/sandbox)

---

# Elide for Bun users

URL: https://elide.help/docs/elide-for-bun

> Switching from Bun to Elide: what runs unchanged, which commands and APIs differ, benchmarks, strengths, weaknesses and the security model.

Elide runs the TypeScript, `node:*` modules and npm packages a Bun program uses; the `Bun` global is absent.

## Run the same code

```bash
elide app.ts                    # or: elide run app.ts
elide install --ecosystems=npm  # dependencies from package.json
elide test                      # node:test files
```

- TypeScript runs with no compile step and no `tsconfig.json`.
- Built-ins load with or without the `node:` prefix.
- A module that default-exports `{ fetch }` serves when run, as in Bun.

See [JavaScript and TypeScript](https://elide.help/docs/web), module status in the [API Overview](https://elide.help/docs/api-overview), and suite results
in the [Compatibility Matrix](https://elide.help/docs/compatibility).

## What changes

| Bun | Elide |
| --- | --- |
| `bun app.ts` | `elide app.ts` |
| `bun install` | `elide install --ecosystems=npm`; plain `elide install` skips npm |
| `bun.lock` | `aube-lock.yaml` |
| `bun run build` | `elide run build` |
| `bunx tool` | `elide run tool` for a tool in `node_modules/.bin`; no download-and-run |
| `bun test` with `expect` | `elide test` with `node:test` and `node:assert`; `expect` is unavailable |
| `bun --inspect app.ts` | `elide run --debugger=cdp app.ts` |
| `bun --watch`, `bun --hot` | No equivalent |
| `.env` loaded automatically | Call `process.loadEnvFile()` in code |
| `Bun.serve({ fetch })` | `Elide.serve({ fetch })` |
| `bun:sqlite` | `elide:sqlite`; see [SQLite](https://elide.help/docs/api-sqlite) |
| `Bun.file`, `Bun.write`, `Bun.$` | `node:fs` and `node:child_process` |
| Web `Worker` | `node:worker_threads` |
| `bun build`, `bun build --compile` | No equivalent |

## Benchmarks

Hello-world startup with `hyperfine -N -w 10 -r 100` on a 24-core AMD Ryzen Threadripper PRO 9965WX Linux workstation:

| Runtime | Command | Mean |
| --- | --- | --- |
| Bun | `bun hello.js` | 1.63 ± 0.18 ms |
| Elide | `elide run hello.js` | 1.43 ± 0.06 ms |
| Node | `node hello.js` | 11.70 ± 0.90 ms |
| Deno | `deno run hello.js` | 6.31 ± 0.30 ms |

Hello-world serving with `wrk -t12 -c256 -d10s --latency`. Each server ran on the same 24 logical CPUs, `wrk` on 24
others.

| Runtime | Requests/s | p50 latency | p99 latency |
| --- | --- | --- | --- |
| Bun | 156,974 | 1.60 ms | 1.80 ms |
| Elide | 635,510 | 0.38 ms | 0.59 ms |
| Deno | 163,511 | 1.54 ms | 1.58 ms |

Each server used its defaults: Bun and Deno serve on one thread, Elide on several.

Versions, setup, and recordings: [Benchmarks](https://elide.help/docs/benchmarks).

## Strengths

- `elide serve --contexts=auto server.ts` runs several copies of the app, sized from the CPU cores, on Linux.
- Flags restrict filesystem, network and subprocess access and limit resources; see [Security model](#security-model).
- The same binary runs WebAssembly, compiles and runs Java and Kotlin, and runs Python after `elide setup python`.

## Weaknesses

- Node-API compatibility is 86.8% and WinterTC 95.9% on their test suites.
- `node:http2`, `node:cluster`, `node:inspector` and `node:wasi` throw `ERR_UNKNOWN_BUILTIN_MODULE`.
- `https.createServer` throws `ERR_HTTPS_SERVER_UNSUPPORTED`, and there is no `WebSocket` global.
- No macOS Intel build; macOS releases are Apple Silicon only.

## Security model

Bun has no permission model. Elide allows everything too, until you pass a flag.

| Flag | Effect |
| --- | --- |
| `--sandbox` | Deny filesystem access; network and subprocesses stay allowed. |
| `--allow-read[=PATHS]`, `--allow-write[=PATHS]` | Allow reads or writes, everywhere or at the listed paths. |
| `--allow-net[=HOSTS]` | Allow network access, to every host or only the listed ones. |
| `--allow-run[=CMDS]` | Allow subprocesses, any or only the listed commands. |
| `--deny-net=HOSTS`, `--deny-run=CMDS` | Deny hosts or commands even when allowed. |
| `--fs-audit` | Log each filesystem decision to stderr. |
| `--limit=workers=N`, `--limit=fds=N` | Limit live workers and open `node:fs` handles. |
| `--max-mem=SIZE` | Limit the heap size. |
| `--timeout=DURATION` | Stop the run after `DURATION` with exit `124`. |

```bash
elide --allow-read=. --allow-net=localhost --allow-run=git app.ts
```

A denied call names the flag to add:

```text
TypeError: fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com
```

`--sandbox=trusted` is the only available profile. See [Sandbox and Limits](https://elide.help/docs/sandbox).

## Next steps

- [Installation](https://elide.help/docs/installation)
- [JavaScript and TypeScript](https://elide.help/docs/web)
- [Sandbox and Limits](https://elide.help/docs/sandbox)

---

# Elide for Deno users

URL: https://elide.help/docs/elide-for-deno

> Switching from Deno to Elide: what runs unchanged, how commands and permission flags map, benchmarks, strengths, weaknesses and the security model.

Elide runs TypeScript, Web APIs, `node:*` modules and npm packages; the `Deno` global is absent.

## Run the same code

```bash
elide app.ts                    # or: elide run app.ts
elide install --ecosystems=npm  # dependencies from package.json
elide test                      # node:test files
elide serve server.ts           # a module that default-exports { fetch }
```

- TypeScript runs with no compile step and no `tsconfig.json`.
- `fetch`, `Request`, `Response`, Streams, `URL` and Web Crypto are globals.
- Built-ins load with or without the `node:` prefix.
- A module that default-exports `{ fetch }`, as `deno serve` expects, serves under `elide serve` and `elide run`.

See [JavaScript and TypeScript](https://elide.help/docs/web), module status in the [API Overview](https://elide.help/docs/api-overview), and suite results
in the [Compatibility Matrix](https://elide.help/docs/compatibility).

## What changes

| Deno | Elide |
| --- | --- |
| `deno run app.ts` | `elide app.ts` |
| `npm:`, `jsr:` and `https:` imports | Bare specifiers resolved from `node_modules` |
| `deno add`, `deno install` | Add to `package.json`, then `elide install --ecosystems=npm` |
| `deno.lock` | `aube-lock.yaml` |
| `deno task build` | `elide run build`; reads `package.json` scripts, not `deno.json` tasks |
| `deno test`, `Deno.test` | `elide test` with `node:test` and `node:assert` |
| `deno run --inspect app.ts` | `elide run --debugger=cdp app.ts` |
| `deno run --watch app.ts` | No equivalent |
| `--env-file` | Call `process.loadEnvFile()` in code |
| `Deno.serve({ fetch })` | `Elide.serve({ fetch })` |
| `Deno.readTextFile`, `Deno.Command` | `node:fs` and `node:child_process` |
| Web `Worker` | `node:worker_threads` |
| `deno fmt`, `deno lint`, `deno compile` | No equivalent for JavaScript or TypeScript |

## Benchmarks

Hello-world startup with `hyperfine -N -w 10 -r 100` on a 24-core AMD Ryzen Threadripper PRO 9965WX Linux workstation:

| Runtime | Command | Mean |
| --- | --- | --- |
| Deno | `deno run hello.js` | 6.31 ± 0.30 ms |
| Elide | `elide run hello.js` | 1.43 ± 0.06 ms |
| Node | `node hello.js` | 11.70 ± 0.90 ms |
| Bun | `bun hello.js` | 1.63 ± 0.18 ms |

Elide's measured mean is lower than Bun's in this recording.

Hello-world serving with `wrk -t12 -c256 -d10s --latency`. Each server ran on the same 24 logical CPUs, `wrk` on 24
others.

| Runtime | Requests/s | p50 latency | p99 latency |
| --- | --- | --- | --- |
| Deno | 163,511 | 1.54 ms | 1.58 ms |
| Elide | 635,510 | 0.38 ms | 0.59 ms |
| Bun | 156,974 | 1.60 ms | 1.80 ms |

Each server used its defaults: Deno and Bun serve on one thread, Elide on several.

Versions, setup, and recordings: [Benchmarks](https://elide.help/docs/benchmarks).

## Strengths

- `elide serve --contexts=auto server.ts` runs several copies of the app, sized from the CPU cores, on Linux.
- Limits workers, open files, heap and run time, and logs each filesystem decision; see [Security model](#security-model).
- The same binary runs WebAssembly, compiles and runs Java and Kotlin, and runs Python after `elide setup python`.

## Weaknesses

- Everything is allowed until you pass a flag, and no flag denies all network or subprocess access.
- Node-API compatibility is 86.8% and WinterTC 95.9% on their test suites.
- `node:http2`, `node:cluster`, `node:inspector` and `node:wasi` throw `ERR_UNKNOWN_BUILTIN_MODULE`.
- `https.createServer` throws `ERR_HTTPS_SERVER_UNSUPPORTED`, and there is no `WebSocket` global.
- No macOS Intel build; macOS releases are Apple Silicon only.

## Security model

Deno denies access until an `--allow-*` flag grants it. Elide allows access until a flag restricts it.

| Deno | Elide |
| --- | --- |
| No flags: everything denied | No flags: everything allowed |
| `-A`, `--allow-all` | No flags |
| `--allow-read[=PATHS]` | `--allow-read[=PATHS]`; denies all other filesystem access |
| `--allow-write[=PATHS]` | `--allow-write[=PATHS]`; denies all other filesystem access |
| `--allow-net[=HOSTS]` | `--allow-net[=HOSTS]` |
| `--allow-run[=CMDS]` | `--allow-run[=CMDS]` |
| `--deny-net=HOSTS`, `--deny-run=CMDS` | `--deny-net=HOSTS`, `--deny-run=CMDS` |
| `--deny-read`, `--deny-write` | No equivalent; grant only the paths you need |
| `--allow-env[=NAMES]` | No equivalent; `process.env` is always readable, and `--allow-env` scopes `elide.pkl` |
| `--allow-ffi` | Allowed; `--no-native` denies native access |
| Prompt for a missing permission | No prompt; the call fails and names the flag to add |

Elide is also more permissive in two ways:

- `--sandbox` restricts the filesystem only. Network and subprocesses stay open until `--allow-net=HOSTS`,
  `--allow-run=CMDS` or a `--deny-*` flag scopes them.
- A bare `--allow-net` or `--allow-run`, or an empty value, allows everything.

Elide also has these controls:

| Flag | Effect |
| --- | --- |
| `--fs-audit` | Log each filesystem decision to stderr. |
| `--limit=workers=N`, `--limit=fds=N` | Limit live workers and open `node:fs` handles. |
| `--max-mem=SIZE` | Limit the heap size. |
| `--timeout=DURATION` | Stop the run after `DURATION` with exit `124`. |

A Deno command and the closest Elide command:

```bash
deno run --allow-read=. --allow-net=api.example.com app.ts
elide --allow-read=. --allow-net=api.example.com --allow-run=git --timeout=30s app.ts
```

`--sandbox=trusted` is the only available profile. See [Sandbox and Limits](https://elide.help/docs/sandbox).

## Next steps

- [Installation](https://elide.help/docs/installation)
- [JavaScript and TypeScript](https://elide.help/docs/web)
- [Sandbox and Limits](https://elide.help/docs/sandbox)

---

# Elide for Python users

URL: https://elide.help/docs/elide-for-python

> Switching from CPython to Elide: running Python 3.13 with the same command-line arguments, what changes, benchmarks, strengths and weaknesses.

Elide runs Python 3.13 programs with CPython's command-line arguments, from the same binary that runs JavaScript,
TypeScript, Java and Kotlin.

Python support is experimental in 1.6.0.

## Run the same code

Add the optional Python component once:

```bash
elide setup python
```

Then use `elide python` in place of `python`:

```bash
elide python app.py --name Elide              # sys.argv: ['app.py', '--name', 'Elide']
elide python -c 'import sys; print(sys.version)'
elide python -m json.tool input.json
elide run app.py                              # same program, general runner
```

These work unchanged:

- Scripts, `-c`, `-m`, `-` (standard input), and the REPL (bare `elide python`).
- Interpreter flags such as `-I`, `-E`, `-S`, `-B`, `-u`, `-O` and `-W`; the full list is in
  [Python with Elide](https://elide.help/docs/python#interpreter-options).
- The Python 3.13 standard library, including `json`, `pathlib`, `sqlite3`, `ssl`, `ctypes`, `bz2` and `lzma`.
- Packages from an existing Python 3.13 virtual environment, through `VIRTUAL_ENV`:

```bash
export VIRTUAL_ENV=/path/to/venv   # Elide reads $VIRTUAL_ENV/lib/python3.13/site-packages
elide python app.py
```

## What changes

| With CPython | With Elide |
| --- | --- |
| `python app.py` | `elide python app.py` or `elide run app.py` |
| `python -c CMD`, `python -m MODULE` | `elide python -c CMD`, `elide python -m MODULE` |
| Install CPython | `elide setup python` |
| `pip install PACKAGE` | `elide uv install PACKAGE`; requires the native launcher and pytools installed with the Python component. |
| `python -m venv`, `source .venv/bin/activate` | Packages installed through Elide use its automatic project environment. Compatible Python 3.13 external venvs also work through `VIRTUAL_ENV`. |
| `pytest` | Install pytest, then run `elide python -m pytest`; `elide test` does not discover Python tests. See [Python tests](https://elide.help/docs/python-testing). |
| `timeout 30 python app.py` | `elide --timeout 30s python app.py`; exits `124` when the limit is exceeded. |

Use `elide install --ecosystems=pypi` for declared dependencies. Package installation supports compatible wheels;
source builds and arbitrary CPython native wheels are not supported. Setup and commands:
[Packages and virtual environments](https://elide.help/docs/python-packages).

## Benchmarks

Hello-world startup with `hyperfine -N -w 10` (10 warmup runs, 100 measured) on a 24-core Linux workstation:

| Command | Mean |
| --- | --- |
| `elide run hello.py` | 4.8 ± 0.3 ms |
| `python3 hello.py` | 6.0 ± 0.3 ms |

No other Python benchmark is published for 1.6.0.

## Strengths

- `bz2` and `lzma` work without system `libbz2` or `liblzma`.
- Python calls JavaScript, and JavaScript or TypeScript imports Python modules, in one process with `--interop`.
- The same binary runs JavaScript, TypeScript and JVM code and builds JVM projects.

## Weaknesses

- `pip` is not bundled. Run unittest through `elide python -m unittest`; `elide test` does not discover Python tests.
- Some C extension modules do not load.
- Some edge cases differ from CPython 3.13: 93.8% of CPython core tests pass ([Compatibility Matrix](https://elide.help/docs/compatibility)).
- macOS has no native module isolation.
- With Python installed, WebAssembly SIMD modules are rejected; see [WebAssembly with Elide](https://elide.help/docs/wasm#limits).

## Next steps

- [Python with Elide](https://elide.help/docs/python)
- [Languages and Interop](https://elide.help/docs/languages)
- [Compatibility Matrix](https://elide.help/docs/compatibility)

---

# Elide for Java users

URL: https://elide.help/docs/elide-for-java

> Switching from a JDK with Maven or Gradle to Elide: running Java source directly with JDK 25, what changes in builds and tests, benchmarks and trade-offs.

Elide bundles JDK 25 with a build tool, Maven dependency resolver, JUnit runner and formatter in one binary.

## Run the same code

A source file with a `main` method compiles and runs directly:

```bash
elide run Main.java
```

`elide java`, `elide javac`, `elide jar` and `elide javadoc` run the JDK 25 tools without a JDK install. Their
arguments go after `--`:

```bash
elide javac -- -d out Main.java
elide java -- -cp out Main
elide jar -- --create --file app.jar -C out .
elide java -- -version
```

The distribution's `bin/` holds `java`, `javac`, `jar`, `javadoc` and `javap`, so an existing build can use it as
`JAVA_HOME`; see [JVM Toolchain](https://elide.help/docs/toolchain/jvm#existing-build-systems).

A project is an `elide.pkl` file, which also lists Maven dependencies:

```pkl
amends "elide:project.pkl"

jvm { main = "com.example.Hello" }

dependencies {
  maven {
    packages { "com.google.guava:guava:33.4.8-jre" }
  }
}
```

```bash
elide init --plain --skip-defaults --template java   # new project
elide install                                        # resolve Maven dependencies
elide build                                          # compile and assemble
elide test                                           # run JUnit tests
elide run                                            # run jvm.main
elide format -- src                                  # Google Java Format
```

JUnit is on the test classpath without a declared dependency. See [Java and Kotlin with Elide](https://elide.help/docs/jvm),
[Testing](https://elide.help/docs/toolchain/testing) and the [`elide.pkl` reference](https://elide.help/docs/elide-pkl-reference).

## What changes

| With a JDK, Maven or Gradle | With Elide |
| --- | --- |
| Install a JDK | Nothing; JDK 25 is bundled. |
| `javac -d out Main.java` | `elide javac -- -d out Main.java` |
| `java Main.java` | `elide run Main.java` |
| `pom.xml`, `build.gradle` | `elide.pkl` |
| Resolve dependencies | `elide install`; `elide install -p .` reads a `pom.xml`. |
| `mvn package`, `gradle build` | `elide build` |
| `mvn test`, `gradle test` | `elide test` |
| `gradle run`, `mvn exec:java` | `elide run` |
| Maven goals on an existing `pom.xml` | `elide mvn -- package`; see [Native Maven](https://elide.help/docs/toolchain/jvm/native-maven). |
| Migrate `./gradlew` or `mvn` builds | `elide adopt`; see [Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt). |
| `native-image` | `elide native-image -- -cp app.jar com.example.Main` |
| `google-java-format` | `elide format` |
| IDE project import | `elide project export --format=intellij` or `--format=pom` |

## Benchmarks

No benchmarks are published for JVM programs in 1.6.0. For ahead-of-time builds, see
[Native Image](https://elide.help/docs/toolchain/jvm/native-image).

## Strengths

- One binary replaces the JDK, Maven resolver, JUnit launcher and Google Java Format.
- `elide.pkl` declares dependencies, tests and artifacts without plugins.
- Annotation processors run in `elide build` and `elide javac` from a `processors` bucket.

## Weaknesses

- No Gradle support: `elide build` does not read `build.gradle` or `build.gradle.kts`, and Gradle plugins have no
  equivalent.
- `elide install -p .` does not merge POM parents or imported BOMs; versions inherited from a parent are dropped.
- No `jlink`, `jpackage` or `jshell` command, and JavaFX is not included.
- `elide adopt` is untested on multi-module and Android projects.
- javac jtreg tests: 99.9% pass (1 fail, 2 errors); see the [Compatibility Matrix](https://elide.help/docs/compatibility).
- JDK tool arguments go after `--`: `elide javac -d out Main.java` exits `2`.

## Next steps

- [Java and Kotlin with Elide](https://elide.help/docs/jvm)
- [JVM APIs](https://elide.help/docs/api-jvm)
- [Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt)
- [JVM Toolchain](https://elide.help/docs/toolchain/jvm)

---

# Elide for Kotlin users

URL: https://elide.help/docs/elide-for-kotlin

> Switching from kotlinc and Gradle to Elide: running Kotlin files directly, what changes in builds, dependencies and tests, benchmarks and trade-offs.

Elide bundles Kotlin 2.5.0-Beta2 and JDK 25 with a build tool, Maven dependency resolver, JUnit runner and ktfmt.

## Run the same code

A file with a `main` function compiles and runs directly:

```bash
elide run Main.kt
```

`elide kotlinc`, `elide java` and `elide jar` run the Kotlin and JDK tools. Their arguments go after `--`:

```bash
elide kotlinc -- -version
elide kotlinc -- -d out Main.kt
```

A project is an `elide.pkl` file. Maven dependencies, kotlinx.serialization, kotlinx.coroutines and JUnit need no
plugin blocks:

```bash
elide init --plain --skip-defaults --template ktjvm   # new project
elide install                                         # resolve Maven dependencies
elide build                                           # compile and assemble
elide test                                            # run JUnit tests
elide run                                             # run jvm.main
elide format -- src                                   # ktfmt
```

See [Java and Kotlin with Elide](https://elide.help/docs/jvm), [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc),
[Testing](https://elide.help/docs/toolchain/testing) and the [`elide.pkl` reference](https://elide.help/docs/elide-pkl-reference).

## What changes

| With kotlinc and Gradle | With Elide |
| --- | --- |
| Install a JDK and `kotlinc` | Nothing; both are bundled. |
| `kotlinc Main.kt -d out` | `elide kotlinc -- -d out Main.kt` |
| `build.gradle.kts` | `elide.pkl` |
| `kotlin("jvm") version "2.3.0"` | `kotlin { toolchain = new Kotlin.ManagedKotlinToolchain { version = "2.3.0" } }` |
| `kotlin("plugin.serialization")` | On by default ([`kotlin.features`](https://elide.help/docs/toolchain/jvm/kotlinc#plugins-and-features)). |
| Subprojects in `settings.gradle.kts` | `workspace { members { "core"; "app" } }` in the root `elide.pkl` |
| `./gradlew build`, `test`, `run` | `elide build`, `elide test`, `elide run` |
| Migrate a `./gradlew` build | `elide adopt`; see [Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt). |
| `ktfmt` | `elide format` |
| IDE project import | `elide project export --format=intellij` |
| `kapt` | `elide build` with a [managed or custom toolchain](https://elide.help/docs/toolchain/jvm/kotlinc#choose-a-toolchain); `elide kotlinc --kapt-sources` for CLI/Bazel. |
| `ksp` | `elide kotlinc --ksp-output` (command line and Bazel); not in `elide build`. |

`ManagedKotlinToolchain` needs `import "elide:Kotlin.pkl" as Kotlin` and applies to project builds; `elide kotlinc`
always uses the bundled Kotlin.

## Benchmarks

No benchmarks are published for JVM programs in 1.6.0. For ahead-of-time builds, see
[Native Image](https://elide.help/docs/toolchain/jvm/native-image).

## Strengths

- One binary replaces the JDK, `kotlinc`, the Maven resolver, the JUnit launcher and ktfmt.
- kotlinx.serialization, coroutines, Power Assert and Metro are enabled without configuration. atomicfu is on too, with its runtime library.
- `ManagedKotlinToolchain` builds a project with another Kotlin version, prereleases included.
- Workspace members can read a sibling's `internal` declarations with `project("core").friend()`.

## Weaknesses

- No Gradle support: `elide build` does not read `build.gradle.kts`, and Gradle plugins have no equivalent.
- KSP is not scheduled in project builds; kapt needs a [managed or custom toolchain](https://elide.help/docs/toolchain/jvm/kotlinc#choose-a-toolchain),
  not the embedded compiler. `elide kotlinc --kapt-sources` and `--ksp-output` remain for CLI and Bazel.
- The bundled compiler is Kotlin 2.5.0-Beta2, a beta.
- `elide java` does not add `kotlin-stdlib` (`NoClassDefFoundError`), and `elide kotlinc -- -include-runtime`
  fails. Run with `elide run`, or package with a `Jvm.JvmApplication`
  ([JAR Assembly](https://elide.help/docs/toolchain/jvm/jar#runnable-application-distributions)).
- `elide adopt` is untested on multi-module and Android projects.

## Next steps

- [Java and Kotlin with Elide](https://elide.help/docs/jvm)
- [JVM APIs](https://elide.help/docs/api-jvm)
- [Kotlin Compiler](https://elide.help/docs/toolchain/jvm/kotlinc)
- [Adopt an Existing Project](https://elide.help/docs/toolchain/usage/adopt)

---

# Architecture

URL: https://elide.help/docs/architecture

> Deep dives into how Elide works, each traced through the code and primary sources.

<!-- Generated by `bun run sync:architecture` from architecture/manifest.mts and editorial.mts; never edit it by hand. -->

Each deep dive is an interactive tour: animated diagrams you step through scene by scene, with a written summary
here.

## One managed heap across languages

[![Interactive tour: One managed heap across languages](https://elide.help/assets/architecture/gc-light.jpg)![Interactive tour: One managed heap across languages](https://elide.help/assets/architecture/gc-dark.jpg)](https://deepdive.elide.dev/gc?source=docs&from=/docs/architecture)

One heap across languages. Two collectors for different workloads: Serial keeps memory use low for CLI tools, desktop apps and low-traffic servers; G1 targets high throughput and short pauses for demanding servers.

[Learn more](https://deepdive.elide.dev/gc?source=docs&from=/docs/architecture) · [Read the garbage collection summary](https://elide.help/docs/architecture/gc)

## Memory-safe semantics, optimized

[![Interactive tour: Memory-safe semantics, optimized](https://elide.help/assets/architecture/memory-safety-light.jpg)![Interactive tour: Memory-safe semantics, optimized](https://elide.help/assets/architecture/memory-safety-dark.jpg)](https://deepdive.elide.dev/memory-safety?source=docs&from=/docs/architecture)

Elide carries memory-safety checks from the interpreter into optimized machine code, giving guest languages one foundation for safety and performance.

[Learn more](https://deepdive.elide.dev/memory-safety?source=docs&from=/docs/architecture) · [Read the memory safety summary](https://elide.help/docs/architecture/memory-safety)

## Native libraries, linked at build time

[![Interactive tour: Native libraries, linked at build time](https://elide.help/assets/architecture/native-substrate-light.jpg)![Interactive tour: Native libraries, linked at build time](https://elide.help/assets/architecture/native-substrate-dark.jpg)](https://deepdive.elide.dev/native-substrate?source=docs&from=/docs/architecture)

Elide ships native transport, cryptography and codecs in one executable. Every guest language shares that foundation.

[Learn more](https://deepdive.elide.dev/native-substrate?source=docs&from=/docs/architecture) · [Read the native substrate summary](https://elide.help/docs/architecture/native-substrate)

## Unified diagnostics

[![Interactive tour: Unified diagnostics](https://elide.help/assets/architecture/observability-light.jpg)![Interactive tour: Unified diagnostics](https://elide.help/assets/architecture/observability-dark.jpg)](https://deepdive.elide.dev/observability?source=docs&from=/docs/architecture)

Debug across languages in one session. Profile guest code, inspect the shared heap, and diagnose JIT behavior, regardless of language.

[Learn more](https://deepdive.elide.dev/observability?source=docs&from=/docs/architecture) · [Read the observability summary](https://elide.help/docs/architecture/observability)

## Many contexts, one engine

[![Interactive tour: Many contexts, one engine](https://elide.help/assets/architecture/threading-light.jpg)![Interactive tour: Many contexts, one engine](https://elide.help/assets/architecture/threading-dark.jpg)](https://deepdive.elide.dev/threading?source=docs&from=/docs/architecture)

Run independent tasks in parallel, call across languages on one thread, and reuse compiled code through a shared engine.

[Learn more](https://deepdive.elide.dev/threading?source=docs&from=/docs/architecture) · [Read the threading summary](https://elide.help/docs/architecture/threading)

---

# One managed heap across languages

URL: https://elide.help/docs/architecture/gc

> How Elide shares one managed heap and handles garbage collection across Truffle languages.

<!-- Generated by `bun run sync:architecture` from architecture/gc/public.md; never edit it by hand. -->

[![Interactive tour: One managed heap across languages](https://elide.help/assets/architecture/gc-light.jpg)![Interactive tour: One managed heap across languages](https://elide.help/assets/architecture/gc-dark.jpg)](https://deepdive.elide.dev/gc?source=docs&from=/docs/architecture/gc)

[Learn more](https://deepdive.elide.dev/gc?source=docs&from=/docs/architecture/gc)

Elide's JavaScript, TypeScript and Python objects share one managed heap with the engine's Kotlin and Java objects. One collector follows references across those languages, so objects can cooperate without dividing their managed lifetimes across separate heaps.[1][2]

Choose the collector when you build: Serial GC for low memory overhead in CLI tools, desktop apps and low-traffic servers; G1 GC for high throughput and responsive servers.[3]

## Keep memory use low with Serial

Serial GC uses one collector thread and pauses application execution during collection. Young collections copy live objects into survivor space and promote older survivors. Full collections reclaim unused objects across both generations. This simple design keeps memory overhead low, making Serial a strong fit for smaller applications.[3]

## Sustain server throughput with G1

G1 divides the heap into regions and performs marking concurrently with application execution. Young collections move live objects during pauses; mixed collections reclaim selected old regions alongside young ones. A pause-time goal guides how much work G1 takes on, balancing responsive requests with sustained throughput.[3][4]

## Collect cross-language cycles together

A JavaScript array can reference a Python dictionary holding a JavaScript function. Truffle represents these managed values as host objects, giving the collector one connected object graph to follow.[1][2]

A Python list and a JavaScript closure can also keep each other alive. Once neither remains reachable from the program's roots, one collector can reclaim the cycle. Serial and G1 both work over this shared graph.[1][3]

GraalPy coordinates native extension objects through its reference-counting bridge and cycle detector, connecting native lifetimes to managed references.[5]

## Size and inspect the shared heap

Elide accepts `-Xmx` and `-XX:MaxHeapSize` across its Truffle guest languages. These flags set the isolate's address-space reservation; Substrate VM sizes the managed heap within that reservation using the collector's memory policy.[6]

Elide includes heap dumps, jvmstat and JFR. VisualVM opens heap dumps to show managed objects, their sizes and the references retaining them across the engine and guest runtimes.[7][8]

## Sources

1. [Truffle interoperability](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/interop/InteropLibrary.html) — managed value representations and cross-language access.
2. [Polyglot programming](https://www.graalvm.org/latest/reference-manual/polyglot-programming/) — languages exchanging values in one memory space.
3. [Native Image memory management](https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/MemoryManagement/) — Serial and G1, build-time collector selection, heap sizing and pause-time goals.
4. [G1 collection](https://docs.oracle.com/en/java/javase/21/gctuning/garbage-first-g1-garbage-collector1.html) — regions, concurrent marking and mixed collections.
5. [GraalPy native extension memory management](https://github.com/oracle/graalpython/blob/master/docs/user/Embedding-Native-Extensions.md) — reference counting and cycles across native and managed objects.
6. [Elide isolate creation](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/entry/bin/main.rs) — translating the requested heap size into an isolate address-space reservation.
7. [Elide monitoring configuration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/tools/settings.mts) — included runtime monitors.
8. [Heap inspection with VisualVM](https://www.graalvm.org/latest/reference-manual/native-image/guides/create-heap-dump/) — creating and exploring managed-heap dumps.

---

# Memory-safe semantics, optimized

URL: https://elide.help/docs/architecture/memory-safety

> How Elide reuses checked interpreter semantics through Truffle and Graal, compiles its Engine with Native Image, and validates native integration.

<!-- Generated by `bun run sync:architecture` from architecture/memory-safety/public.md; never edit it by hand. -->

[![Interactive tour: Memory-safe semantics, optimized](https://elide.help/assets/architecture/memory-safety-light.jpg)![Interactive tour: Memory-safe semantics, optimized](https://elide.help/assets/architecture/memory-safety-dark.jpg)](https://deepdive.elide.dev/memory-safety?source=docs&from=/docs/architecture/memory-safety)

[Learn more](https://deepdive.elide.dev/memory-safety?source=docs&from=/docs/architecture/memory-safety)

Elide carries memory-safety checks from the interpreter into optimized machine code. Guest languages share a foundation for safety and performance, and the compiler specializes that foundation for the code you run.[1]

## One set of semantics, from interpreter to compiler

Truffle language implementations use managed objects, bounds checks and garbage collection. Graal specializes their interpreters into machine code, carrying the interpreter's checked semantics through optimization. This reduces the need to maintain separate correctness rules in an interpreter and a guest-language optimizer.[1][2]

JavaScript, Python, JVM bytecode and WebAssembly implementations build on this common model. Language authors supply the semantics; Truffle and Graal provide the machinery that turns them into optimized execution.[1][2]

## Precompile the engine, specialize guest execution

Native Image compiles reachable engine code ahead of time, packaging the runtime into a native executable. At runtime, Graal specializes guest execution using the behavior and values it observes.[3][4]

When an optimization's assumptions change, execution can return to the interpreter and specialize again. The compiler must preserve language semantics throughout that process.[1][5]

This architecture puts the safety model and optimization strategy on the same foundation: the interpreter defines how the program behaves, and the compiler derives optimized execution from it.

## Make native ownership explicit

Rust owns Elide's native entrypoint and calls the managed engine through a C ABI. The interface defines pointer lifetimes, resource ownership and thread ownership at the boundary. Native libraries and extension interfaces use explicit ownership contracts to connect their resources to the runtime.[6]

That gives Elide a deliberate division of responsibility: managed semantics govern guest objects, while the native integration layer governs native resources.

## Test native paths and reinforce their boundaries

Elide's sanitizer builds exercise instrumented native paths to detect memory errors. Compiler and linker hardening reinforce the C integration.[7]

Together, checked guest semantics, compiler specialization and explicit native ownership let Elide pursue performance across its language stack while keeping memory safety central to execution.

## Sources

1. [Writing Truly Memory Safe JIT Compilers](https://medium.com/graalvm/writing-truly-memory-safe-jit-compilers-f79ad44558dd) — deriving optimized guest code from checked Truffle interpreter semantics.
2. [Truffle languages](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/Languages/) — language implementations on the shared framework.
3. [Native Image basics](https://www.graalvm.org/latest/reference-manual/native-image/basics/) — reachability analysis and the native executable.
4. [Host compilation for Truffle interpreters](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/HostOptimization/) — host compilation, guest compilation and partial evaluation.
5. [Optimizing Truffle interpreters](https://www.graalvm.org/jdk21/graalvm-as-a-platform/language-implementation-framework/Optimizing/) — specialization and deoptimization.
6. [Elide's native entrypoint](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/entry/bin/main.rs) — the engine call and native ownership boundary.
7. [Elide sanitizer configuration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/tools/strict.mts) and [native build configuration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/tools/settings.mts) — native validation and hardening.

---

# Native libraries, linked at build time

URL: https://elide.help/docs/architecture/native-substrate

> How Elide uses Static JNI and Native Image substitutions to link native transports, AWS-LC and codecs into one executable shared by its guest languages.

<!-- Generated by `bun run sync:architecture` from architecture/native-substrate/public.md; never edit it by hand. -->

[![Interactive tour: Native libraries, linked at build time](https://elide.help/assets/architecture/native-substrate-light.jpg)![Interactive tour: Native libraries, linked at build time](https://elide.help/assets/architecture/native-substrate-dark.jpg)](https://deepdive.elide.dev/native-substrate?source=docs&from=/docs/architecture/native-substrate)

[Learn more](https://deepdive.elide.dev/native-substrate?source=docs&from=/docs/architecture/native-substrate)

Elide ships native transport, cryptography and codecs in one executable. Guest languages share that foundation, combining their application logic with native libraries for networking and data processing.

## Ship the native stack in one executable

On Linux and Apple Silicon, Elide links Netty's native transports and TLS bindings into Native Image as static archives. The managed engine and Rust services ship together in one deployment artifact.[1][2]

Linux supplies epoll and io_uring; macOS supplies kqueue. AWS-LC provides TLS cryptography, while Elide's Rust services supply zstd, brotli and gzip codecs.[2][3]

Native dependencies become part of the executable's build, bringing their integration into the same validation and packaging process as the rest of the runtime.

## Catch missing bindings before deployment

Elide registers static JNI libraries and their Java-facing methods. Native Image references the corresponding symbols, and the linker checks required definitions while assembling the executable.[1]

This moves native binding resolution into the build. The resulting executable carries the selected native components with it.

## Optimize across compilation units

Elide configures ThinLTO for Native Image's native compiler and Cargo's final link. Compatible LLVM bitcode lets the linker inline and optimize across compilation units, extending optimization beyond individual source files.[2][4]

## Let native libraries serve guest application code

The shared stack creates a direct division of work for servers: native transport and TLS handle connections; host-side HTTP framing turns incoming data into requests; guest code supplies the application handler.

In this design, application code handles a `Request` and returns a `Response`. The runtime retains the handler and invokes it through the realm's event loop. Guest languages focus on application behavior while sharing the transport and cryptography beneath them.[5]

## Embed the engine behind the CLI

Elide exposes a native entrypoint driven by a versioned Cap'n Proto record. CLI and embedded hosts use the same interface, so the engine can serve both command-line tools and larger host applications.[6]

Hosts can manage multiple Native Image isolates. Collector selection also follows the workload: Serial keeps memory overhead low for smaller applications, while G1 targets sustained server throughput.[6][7]

## Sources

1. [Elide static native library integration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/base/main/dev/elide/features/AbstractStaticNativeLibraryFeature.kt) and [Netty archive integration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/tools/jvm/netty-statics.mts) — static JNI registration and linking.
2. [Elide native build configuration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/tools/settings.mts) — native components and compiler configuration.
3. [Netty native transports](https://netty.io/wiki/native-transports.html), [AWS-LC](https://github.com/aws/aws-lc), and [Elide Rust dependencies](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/Cargo.toml) — networking, cryptography and codecs.
4. [LLVM ThinLTO](https://clang.llvm.org/docs/ThinLTO.html) — optimization across compatible bitcode inputs.
5. [Elide HTTP server](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/base/main/dev/elide/lang/javascript/net/transport/HttpServer.java) — request dispatch and retained application handlers.
6. [Elide native entrypoint](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/entry/bin/main.rs) — engine invocation and isolate creation.
7. [Native Image memory management](https://www.graalvm.org/latest/reference-manual/native-image/optimizations-and-performance/MemoryManagement/) — collector selection and workload trade-offs.

---

# Unified diagnostics

URL: https://elide.help/docs/architecture/observability

> How Elide supports Truffle instrumentation across guest languages, and how GraalVM Native Image monitors and native profilers complement runtime diagnosis.

<!-- Generated by `bun run sync:architecture` from architecture/observability/public.md; never edit it by hand. -->

[![Interactive tour: Unified diagnostics](https://elide.help/assets/architecture/observability-light.jpg)![Interactive tour: Unified diagnostics](https://elide.help/assets/architecture/observability-dark.jpg)](https://deepdive.elide.dev/observability?source=docs&from=/docs/architecture/observability)

[Learn more](https://deepdive.elide.dev/observability?source=docs&from=/docs/architecture/observability)

Debug across languages in one session. Profile guest code, inspect the shared heap, and diagnose JIT behavior, regardless of language.

Elide brings Truffle's shared debugger, profiler and coverage tools to guest execution. Each language implements a common instrumentation contract; Elide supplies shared configuration and reporting. Native Image monitors and native profilers extend that view into the managed runtime and machine code.[1][2]

## One suite of consistent tools

Truffle languages expose source locations and standard tags for operations such as calls and statements. Instruments use those tags to observe execution through one API. Graal can inline instrument dispatch with guest code.[1]

Elide exposes debugging, profiling, coverage and Insight through its CLI. MCP exposes Insight through the same engine instrument API, giving agent clients access to execution instrumentation.[3][4]

## Chrome Debugger works across languages

Step through cross-language calls, inspect variables and read guest stacks in one Chrome Debugger session. Elide's CDP debugger connects Chrome to guest execution.[5]

## Insight works across languages

Insight lets a privileged script observe execution across languages. Callbacks can inspect and modify guest locals.[6]

One agent observing two targets, captured on macOS ARM64 with Elide 1.5.0+20260902.bac3ab38; both runs exited successfully.[11]

`observe.js`

```javascript
insight.on("source", (source) => {
  if (source.name === "target.js" || source.name === "target.py") {
    console.log(`Observed source: ${source.name}`);
  }
});
```

`target.js`

```javascript
function twice(value) {
  return value * 2;
}
console.log(`Result: ${twice(21)}`);
```

`target.py`

```python
def twice(value):
    return value * 2

print("Result: " + str(twice(21)))
```

```console
$ elide run --insights=observe.js target.js
Observed source: target.js
Result: 42

$ elide run --insights=observe.js target.py
Observed source: target.py
Result: 42
```

## JVM and Rust diagnostics work together

Elide unifies JVM library and Rust logs under one configuration. Its JFR events describe boot, guest execution and HTTP alongside the runtime's default events. Policy connects these diagnostics to the program's lifecycle.[7]

Native Image supplies execution samples, runtime events and managed-heap dumps. Linux perf samples native execution stacks; debug symbols and jitdump metadata identify ahead-of-time and runtime-compiled methods.[2][8]

## Choose the view that answers your question

| Task | Tool |
| --- | --- |
| Step through guest code | Chrome inspector or DAP |
| Find where CPU time goes | `--profiler=cpusampling` |
| Count executions | `--profiler=cputracing`, also selected by bare `--profiler` |
| Trace guest allocations | `--profiler=memtracing` (experimental) |
| Measure exercised code | `--coverage` |
| Observe execution from a script | Insight through the CLI or MCP |
| Record runtime activity | JFR |
| Find objects retaining memory | Heap dumps and VisualVM |
| Discover the running VM | jvmstat |
| Examine native execution | perf with debug symbols and jitdump |
| Inspect compiler decisions | Compilation tracing and IGV |

Elide supports JFR, jvmstat and heap dumps in the executable, with jcmd on Linux and macOS. Frame pointers support native stack walking.[3][7][8]

VisualVM opens recordings and managed-heap dumps to reveal runtime activity and retained objects. Ideal Graph Visualizer exposes Truffle trees, guest call graphs and compiler phases, connecting source structure to optimization decisions.[9][10]

## Sources

1. [Truffle instrumentation](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/TruffleInstrument.html) — the common instrument API and execution hooks.
2. [Native Image Flight Recorder](https://www.graalvm.org/latest/reference-manual/native-image/debugging-and-diagnostics/JFR/) — execution samples, runtime events and custom events.
3. [Elide CLI instruments](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/crates/cli/src/run.rs) — debugger, profiler, coverage and Insight options.
4. [Elide monitoring and profiling](https://elide.help/docs/instruments) — capture flags, recordings, heap dumps, live capture and perf.
5. [Elide debugging guide](https://elide.help/docs/debugging#attach-a-debugger) and [Chrome Debugger for GraalVM](https://www.graalvm.org/latest/tools/chrome-debugger/) — attaching DAP or CDP; source debugging across Truffle languages.
6. [GraalVM Insight](https://www.graalvm.org/latest/tools/graalvm-insight/manual/) — observing execution and accessing guest locals.
7. [Elide monitoring configuration](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/tools/settings.mts) and [live capture](https://elide.help/docs/instruments#watch-a-running-process) — built-in monitors, logging and lifecycle events.
8. [Elide JIT profiling with perf](https://elide.help/docs/instruments#profile-with-perf-on-linux) — jitdump metadata and perf for native execution profiles.
9. [Elide managed-heap dumps](https://elide.help/docs/instruments#dump-the-heap) — managed-heap inspection in VisualVM.
10. [Ideal Graph Visualizer](https://www.graalvm.org/latest/tools/igv/) — compiler graphs and source relationships.
11. [Insight example](https://github.com/elide-dev/elide/tree/54ce3d1f3e2ca70f4aeeed3c44797d7f4457323b/project/docs/architecture/observability/examples/insight) — agent, targets and recorded output.

---

# Many contexts, one engine

URL: https://elide.help/docs/architecture/threading

> Run independent tasks in parallel, call across languages on one thread, and reuse compiled code through a shared engine.

<!-- Generated by `bun run sync:architecture` from architecture/threading/public.md; never edit it by hand. -->

[![Interactive tour: Many contexts, one engine](https://elide.help/assets/architecture/threading-light.jpg)![Interactive tour: Many contexts, one engine](https://elide.help/assets/architecture/threading-dark.jpg)](https://deepdive.elide.dev/threading?source=docs&from=/docs/architecture/threading)

[Learn more](https://deepdive.elide.dev/threading?source=docs&from=/docs/architecture/threading)

Run independent tasks in parallel, call across languages on one thread, and reuse compiled code through a shared engine.

Each execution context owns its guest language state. Multiple contexts run on a shared Truffle engine.[1][2]

## Contexts support multiple languages

JavaScript and Python can exchange values within one context. Host access and guest thread permissions are configured at the context level.[1][2]

A context running JavaScript admits one executing thread at a time. Python-only contexts support multiple threads, with a per-context GIL serializing Python execution and normally releasing around foreign calls.[2][3]

## A bounded pool of reusable contexts

Elide schedules one active task per pooled context, with a configurable bound that defaults to processor count. Reused contexts retain application state. Tasks that require a particular context return to it.[2][4]

## Callbacks return to their context

I/O and worker completions post work to the context's event loop. Callbacks run on the thread holding that context and can call another language without a thread handoff.[2][5]

For example, a server can distribute requests across pooled contexts. Within a request, a Python handler can call a JavaScript renderer and use its result directly.[1][2][4]

## Dedicated workers for CPU-bound tasks

Each worker owns a dedicated host thread and a fresh context on the shared engine. Workers exchange messages through structured clone.[6]

## Shared engine with JIT caching

The shared engine reuses eligible parsed and compiled code across contexts. GraalVM's Auxiliary Engine Cache can persist this code across program starts.[2][7]

## Sources

1. [Elide runtime](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/base/main/dev/elide/runtime/ElideRuntime.kt) — shared engines, context configuration and guest capabilities.
2. [Polyglot Context](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.html) and [Engine](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Engine.html) — context access, language interoperation and code reuse.
3. [GraalJS multithreading](https://www.graalvm.org/javascript/docs/#multithreading) and [GraalPy multithreading](https://github.com/oracle/graalpython/blob/master/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java) — language-specific threading behavior.
4. [Elide context-aware executor](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/base/main/dev/elide/runtime/execution/ContextAwareExecutorBase.kt) — pooling, task scheduling and context ownership.
5. [Elide event loop](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/base/main/dev/elide/runtime/truffle/EventLoop.kt) — callback execution and external completions.
6. [Elide workers](https://github.com/elide-dev/elide/blob/d8ac9d068726e614e0360c2c23a1ae1dd83f431e/packages/base/main/dev/elide/lang/javascript/node/worker_threads/NodeWorkers.kt) — worker contexts, host threads and parent notifications.
7. [Auxiliary Engine Caching](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/AuxiliaryEngineCachingEnterprise/) — persisting code for reuse across runs of the same native executable.

---

# Benchmarks

URL: https://elide.help/docs/benchmarks

> Published Elide benchmarks: hello-world startup for JavaScript and Python, and HTTP serving throughput and latency, against Node, Bun, Deno and CPython, with machine, date, command and recording.

Benchmarks published for Elide 1.6.0. Each number links to a terminal recording or downloadable raw measurement reports.
JavaScript startup and HTTP serving were re-recorded on October 15 with the release build
`1.6.0`, without the optional Python component. Python results retain their October 2 recording.
No JVM benchmark is published.

1. JavaScript hello-world startup, mean: Elide 1.43 ms, Bun 1.63 ms, Deno 6.31 ms, Node 11.70 ms.
2. Python hello-world startup, mean: Elide 4.8 ms, CPython 6.0 ms.
3. HTTP serving, requests per second: Elide 635,510, Deno 163,511, Bun 156,974, Node 123,519.

## JavaScript startup

Time to run a one-line `hello.js` (`console.log("Hello, World!");`) and exit. Lower is better.

| Runtime | Version | Command | Mean |
| --- | --- | --- | --- |
| Elide | 1.6.0 | `elide run hello.js` | 1.43 ± 0.06 ms |
| Bun | 1.4.2 | `bun hello.js` | 1.63 ± 0.18 ms |
| Deno | 2.9.7 | `deno run hello.js` | 6.31 ± 0.30 ms |
| Node | 24.21.0 | `node hello.js` | 11.70 ± 0.90 ms |

| Detail | Value |
| --- | --- |
| Tool | `hyperfine -N -w 10 -r 100`: no shell, 10 warmup runs, 100 measured |
| Machine | 24-core AMD Ryzen Threadripper PRO 9965WX Linux workstation |
| Date | 2026-10-15 |
| Recording | `bench-startup` (below) |

<img src="https://elide.help/assets/demos/bench-startup.gif" alt="Hello-world startup — Elide, Node, Bun, and Deno" width="1279" height="473" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## Python startup

Time to run a one-line `hello.py` (`print("Hello, World!")`) and exit. Lower is better.

| Runtime | Version | Command | Mean |
| --- | --- | --- | --- |
| Elide | 1.6.0 | `elide run hello.py` | 4.8 ± 0.3 ms |
| CPython | not recorded | `python3 hello.py` | 6.0 ± 0.3 ms |

| Detail | Value |
| --- | --- |
| Tool | `hyperfine -N -w 10`: no shell, 10 warmup runs |
| Machine | 24-core Linux workstation |
| Date | 2026-10-02 |
| Recording | `bench-startup-python` (not published as a clip) |

Python needs the optional component (`elide setup python`); see [Python with Elide](https://elide.help/docs/python).

## HTTP serving

Requests per second and latency for a fetch handler that returns `Hello, World!`. Higher requests per second and lower
latency are better.

```javascript
// server.mjs
export default {
  port: 3000,
  hostname: "127.0.0.1",
  fetch() {
    return new Response("Hello, World!");
  },
};
```

| Runtime | Version | Command | Requests/s | p50 latency | p99 latency |
| --- | --- | --- | --- | --- | --- |
| Elide | 1.6.0 | `elide server.mjs` | 635,510 | 0.38 ms | 0.59 ms |
| Deno | 2.9.7 | `deno serve --port 3000 --host 127.0.0.1 server.mjs` | 163,511 | 1.54 ms | 1.58 ms |
| Bun | 1.4.2 | `bun server.mjs` | 156,974 | 1.60 ms | 1.80 ms |
| Node | 24.22.0 LTS | `node node-default.mjs` | 123,519 | 2.03 ms | 2.24 ms |

| Detail | Value |
| --- | --- |
| Tool | `wrk -t12 -c256 -d10s --latency`, after a discarded 5-second warmup run |
| Machine | 24-core AMD Ryzen Threadripper PRO 9965WX Linux workstation; server on 24 logical CPUs, `wrk` on 24 others |
| Date | 2026-10-15 |
| Recording | `bench-serve` (below) |

The server CPU mask was `0-11,24-35`; the client mask was `12-23,36-47`: twelve physical cores and their SMT
siblings per side, in a private network namespace. The table shows one recorded run on this machine.

Each server used its defaults and one JavaScript application context. Elide also uses transport threads.
This is an apples-to-apples comparison of default settings with the same handler and load, not a comparison of
maximum multi-core capacity. Node uses an equivalent native `http` handler with the same 13-byte body;
HTTP headers remain runtime-specific. Its separate run used the same machine, CPU masks, private network
namespace, warmup, and load settings, with no reported socket or HTTP status errors.
[Node’s raw report](https://elide.help/assets/benchmarks/results/default/node/run-1/measured.txt) and handler are included
in the [reproduction package](https://elide.help/assets/benchmarks/http-serving-1.6.0.zip). The recording below covers the original three runtimes.

<img src="https://elide.help/assets/demos/bench-serve.gif" alt="HTTP serving — Elide, Bun, and Deno answering one request" width="1279" height="619" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## Multi-context peak serving

The same Elide binary reached **10,697,938 requests/s** with 24 application contexts in one process and
HTTP/1.1 pipeline depth 16. Three fresh-server runs measured **10,697,938, 10,376,454, 10,648,229 requests/s**;
the mean was **10,574,207 requests/s**. Every warmup and measured run reported zero request errors.
Ordered-response preflight checked status, framing, and body bytes before each load.

This is a separate tuned throughput experiment. It does not establish a speedup over the default-serving
comparison above, an off-host capacity estimate, or a maximum for other runtimes. Pipeline latency measures
batches; we do not publish it as individual-request latency.

| Configuration | Default-serving comparison | Peak multi-context serving |
| --- | --- | --- |
| Elide throughput | 635,510 requests/s | 10,697,938 requests/s peak |
| JavaScript execution | One context per runtime | 24 contexts in one Elide process |
| HTTP load | No pipelining | Pipeline depth 16; 4096 varied URLs |
| Load generator | 12 threads; 256 connections | 16 threads; 256 connections |
| Warmup / measurement | 5 seconds / 10 seconds | 60 seconds / 60 seconds; three fresh servers |
| Handler | Constant 13-byte Hello, World! response | URL parsing; nine-byte hello-GET response |
| CPU budget | 12 physical server cores + SMT; 12 for client | 12 physical server cores + SMT; 12 for client |
| Scheduling | Default serving settings | Explicit inline serving; io_uring |
| Network | Private namespace, loopback | Host loopback |
| Build | Elide 1.6.0, without Python | Same Elide binary; Serial GC |


### Parallel runtime comparison

We also ran Bun 1.4.3, Deno 2.9.7, and Node.js 24.22.0 LTS against the peak workload above:
same server/client CPU masks, 256 connections, sixteen client threads, pipeline depth 16,
URL parsing, and nine-byte response. Each configuration had three fresh-server runs, each with
60 seconds warmup and 60 seconds measurement. Runtimes ran sequentially, with configurations
interleaved between repeats. These results do not use estimated process scaling or memory penalties.

| Runtime | Configuration | Peak requests/s | Measured-run errors |
| --- | --- | ---: | --- |
| Elide 1.6.0 | 24 contexts; published runs | 10,697,938 | 0 |
| Deno 2.9.7 | 24 worker isolates; `--parallel` | 4,152,202 | 0 |
| Bun 1.4.3 | 24 processes; `reusePort` | 3,573,293 | 0 |
| Node.js 24.22.0 LTS | 24 `node:cluster` workers | 2,801,194 | 0 |
| Node.js 24.22.0 LTS | One process; reference | 217,282 | 139 timeouts across 3 runs |

A fresh Elide control run reached **11,416,311 requests/s** without errors. The comparison retains
the previously published three-run peak instead of replacing it with this single control.

The competitor measurements were:

| Configuration | Run 1 | Run 2 | Run 3 |
| --- | ---: | ---: | ---: |
| Bun, 24 processes | 3,571,718 | 3,573,293 | 3,560,084 |
| Deno, 24 workers | 4,123,713 | 4,039,565 | 4,152,202 |
| Node.js, 24 workers | 2,791,261 | 2,798,668 | 2,801,194 |
| Node.js, one process | 180,500 | 217,282 | 168,524 |

Node’s single-process measured runs reported 48, 42, and 49 timeout events respectively; their
warmups reported 62, 52, and 64. All other measured runs and warmups reported zero connection,
read, write, response-status, and timeout errors. Counts are wrk events, not failed-request rates.

Bun uses Linux port sharing; Deno uses worker isolates within one process; Node uses its built-in
cluster coordinator. No external proxy is involved. Node uses its native `http` API; the other
handlers use fetch-style APIs. All parse the URL and construct the response, but default HTTP
headers differ. This is a comparison of these configurations, not a ceiling for any runtime.
RSS savings were not benchmarked.

[Download sources and raw results](https://elide.help/assets/benchmarks/http-serving-1.6.0.zip) ·
[Comparison summary](https://elide.help/assets/benchmarks/results/comparison/summary.json)

## How contexts share a process

```sh
elide run --contexts=auto server.mjs
```

This enables automatic context sizing; `--contexts=24` requests a fixed count. The entry module runs in each
context. Contexts handle requests concurrently, keep JavaScript globals and module state separate, and share
one managed heap and garbage collector. Eligible parsed and JIT-compiled code can be reused across contexts.
Sharing does not make ordinary JavaScript objects globally accessible. GC pauses and a process failure can
affect all contexts; use external coordination for application data that must be shared.

### Architecture comparison

This compares independent-process scaling with Elide's multi-context model; other runtimes can also offer
worker-thread models. Shared infrastructure can reduce duplication, but application work and context-local
state still scale with the workload.

| Resource | Multiple processes | Elide contexts |
| --- | --- | --- |
| Replicas | One process each | One context each |
| Managed heap | Separate | ✅ Shared |
| GC pauses | ✅ Per process | ⚠ May span contexts |
| Parsed / JIT code | Per process | ✅ Shareable code reused |
| Runtime setup | Per process | ✅ Once per process |
| Telemetry pipeline | Per process | ✅ Shared batching/export |
| Request spans | Per request | Per request |
| Process metrics | One stream per process | ✅ One process stream |
| Listener | Port sharing / routing | ✅ One shared listener |
| I/O resources | Per process | Shared topology; per-owner queues |
| JS globals | ✅ Isolated | ✅ Isolated |
| App client pools | Per replica | Per context unless shared by an API |
| Coordination | IPC / external storage | Explicit APIs / external storage |
| CPU scheduling | Process / worker threads | Context owner threads |
| Crash isolation | ✅ Per process | ⚠ Shared process |
| Lifecycle | Manage each process | ✅ One lifecycle |

Telemetry infrastructure is amortized across contexts; per-request instrumentation still costs work.
Telemetry export was disabled for these measurements. Neither telemetry savings nor memory savings were
measured by the HTTP benchmark.

The peak benchmark also explicitly selects inline scheduling and io_uring, uses unlimited memlock, and
pipelines requests. The simple command above does not enable all those benchmark settings. The download
contains the exact command and environment; [performance tuning](https://elide.help/docs/performance#multi-context-serving)
explains the application-facing context setting. This diagram describes architecture, not measured memory savings.

## Benchmark environment

These details apply to the October 15 JavaScript startup and HTTP measurements. The older Python recording
has only the machine information listed in its own section; do not infer the same kernel or distro for it.

| Detail | Value |
| --- | --- |
| CPU | AMD Ryzen Threadripper PRO 9965WX; 24 physical cores, 48 hardware threads, one socket |
| Memory | 128 GB installed; approximately 122.9 GiB visible to Linux |
| OS | Ubuntu 26.04.1 LTS, x86-64 |
| Kernel | Linux `7.0.0-34-generic` |
| CPU policy | Performance governor; frequency boost enabled |
| Server / client placement | Twelve physical cores plus SMT siblings per side; disjoint CPU masks |
| Client | wrk 4.1.0; exact options in the comparison table and download |
| Elide | `1.6.0`, release, without optional Python; Serial GC |
| Binary SHA-256 | `545a4d99db099cf91a35bad8b33bb7e8d1a37a7361c6ba2b62c6e94691fff5c6` |
| Peak results | [Raw reports and environment](https://elide.help/assets/benchmarks/http-serving-1.6.0.zip) |

Default server CPUs: `0-11,24-35`; client: `12-23,36-47`.
Peak server CPUs: `0-2,6-8,12-14,18-20,24-26,30-32,36-38,42-44`;
client: `3-5,9-11,15-17,21-23,27-29,33-35,39-41,45-47`.
The differing masks preserve the same physical-core budget; they are recorded, not assumed interchangeable.

## Run them yourself

[Download the rerunnable benchmark package](https://elide.help/assets/benchmarks/http-serving-1.6.0.zip)
([SHA-256](https://elide.help/assets/benchmarks/http-serving-1.6.0.zip.sha256)). It includes a Makefile,
a dependency-free Python runner, JavaScript fixtures, the pipelined wrk client, raw results, and instructions.
Bring Linux, Python 3, Make, util-linux, wrk, and your runtime binaries. No runtime binaries are bundled; use
the recorded version and checksum for an exact binary match, or record your own version when comparing.

```sh
make run ARGS="--mode peak --binary /path/to/elide --contexts 24 --server-cpus YOUR_SERVER_CPUS --client-cpus YOUR_CLIENT_CPUS --out results"
```

Choose CPU masks for your machine. The download documents locked-memory limits, namespace differences,
and commands for the default Elide, Bun and Deno comparison. Results vary with hardware and configuration.

The same files and commands work on any machine; expect different absolute numbers. [Performance
Tuning](https://elide.help/docs/performance#measure-startup) covers the setup: real binaries rather than version-manager shims, pinning the
server and `wrk` to separate cores, and a warmup run before measuring.

## See also

- [Performance tuning](https://elide.help/docs/performance) for the settings that change speed and memory
- Comparisons per runtime: [Node](https://elide.help/docs/elide-for-node#benchmarks), [Bun](https://elide.help/docs/elide-for-bun#benchmarks),
  [Deno](https://elide.help/docs/elide-for-deno#benchmarks), [Python](https://elide.help/docs/elide-for-python#benchmarks)

---

# Performance tuning

URL: https://elide.help/docs/performance

> The Elide settings that change speed and memory: serving contexts, network transport, heap size and profiles, plus how to benchmark startup and serving.

This page lists the settings that change Elide's speed and memory use, and how to measure them.

| Setting | Applies to | Default |
| --- | --- | --- |
| `--contexts=N`, `--contexts=auto` | Fetch-handler servers under `run`, `serve`, `dev` (Linux for more than one) | `1` |
| `engine.contexts` in `elide.pkl` | `elide serve`, `elide dev` | `1` |
| `--max-mem=SIZE` | Every command | `4g` for one-shot runs; sized from host memory for `serve`, `dev` |
| `--transport=VALUE`, `ELIDE_TRANSPORT_V2` | `fetch` and dependency downloads | `auto` |
| `--sandbox=PROFILE` | Every program | `trusted` |

## Add serving contexts

A context is one copy of your app with its own module state. Each context runs requests on its own thread, so more
contexts serve more requests at once on more cores.

```bash
elide serve --no-tui --contexts=4 server.mjs
elide run --contexts=auto server.mjs
```

`auto` uses the physical cores minus two. Set it per project for `serve` and `dev`:

```pkl
// elide.pkl
amends "elide:project.pkl"

engine {
  contexts { spawn = "auto"; reserve = 2; min = 1; max = 16 }
}
```

| Rule | Detail |
| --- | --- |
| `elide run` | Reads `--contexts` only; pass the flag. |
| Module state | Not shared between contexts; keep shared state in a database or another service. |
| `node:http` servers | One context; a second copy fails with `EADDRINUSE`. |
| Platforms | More than one context requires Linux. |

Server I/O threads follow the context count; `ELIDE_HTTP_NATIVE_WORKERS` does not change them under `run`, `serve` or
`dev`. Field reference: [Engine contexts](https://elide.help/docs/elide-pkl-reference#engine-contexts); walkthrough:
[Several contexts](https://elide.help/docs/http-service#several-contexts).

## Cap memory

```bash
elide --max-mem=512m run app.js
elide --max-mem=2g serve server.mjs
```

`--max-mem` caps the heap. One-shot runs (`run`, a bare file) default to at most `4g`; `serve` and `dev` size the heap
from host or container memory, so set it on every container or shared host. A full heap exits `1` with
`the heap address space is exhausted`; a cap of `128m` or less fails at startup. See
[Troubleshooting](https://elide.help/docs/troubleshooting).

## Choose a network transport

`--transport` picks how `fetch` and dependency downloads reach the network. It does not change HTTP servers.

| Value | Use |
| --- | --- |
| `auto` | Best transport for the host. On Linux this is `v2` with epoll. |
| `v2` | Elide's own transport, with its own TLS. `ELIDE_TRANSPORT_V2=1` selects it when no flag is given. |
| `epoll`, `io_uring` | `v2` with that Linux event driver. |
| `kqueue` | `v2` on macOS; other platforms exit `2`. |
| `nio` | Portable transport, for comparison or when a native driver fails. |

```bash
elide --transport=io_uring run client.mjs
elide info
```

`elide info` prints the selected transport and driver on its `Transport:` line. An explicit `--transport` wins over
`ELIDE_TRANSPORT_V2`. `ELIDE_TRANSPORT_DIAGNOSTICS=1` prints transport statistics to stderr.

## Pick an execution profile

| Profile | Status |
| --- | --- |
| `--sandbox=trusted` | Default; no confinement cost. |
| `--sandbox=sandboxed` | Exits `2`: `--sandbox=sandboxed is unavailable` |
| `--sandbox=isolated` | Exits `2`: `--sandbox=isolated is not available in this build` |

Permission flags and limits are on [Sandbox and Limits](https://elide.help/docs/sandbox).

## Find the slow part

| Question | Tool |
| --- | --- |
| Where does startup time go? | `ELIDE_DIAG_STARTUP=1 elide run app.js` prints each startup phase with a timestamp to stderr. |
| Which functions run most? | `elide run --profiler=cputracing app.js`; see [Debugging](https://elide.help/docs/debugging#profile-cpu-time). |
| What happened during a run or a request? | `elide --jfr=run.jfr run app.js`; see [Monitoring and Profiling](https://elide.help/docs/instruments). |
| Where does compiled code spend CPU time? | `--jitdump=DIR` with Linux `perf`; see [Monitoring and Profiling](https://elide.help/docs/instruments). |
| Which requests are slow in production? | Server spans and `http.server.request.duration`; see [OpenTelemetry](https://elide.help/docs/opentelemetry/runtime). |

## Measure startup

Run [hyperfine](https://github.com/sharkdp/hyperfine) with `-N` (no shell) so each sample is one process:

```javascript
// hello.js
console.log("Hello, world!");
```

```bash
hyperfine -N --warmup 10 --runs 100 --export-json startup.json \
  'elide run hello.js' 'node hello.js' 'bun hello.js' 'deno run hello.js'
```

Call each runtime's real binary: a version-manager shim or wrapper script adds a process to every sample. Give the full
path if `which elide` is not the installed binary.

## Measure serving

Serve one fixed response and load it with [wrk](https://github.com/wg/wrk):

```javascript
// server.mjs
export default {
  hostname: "127.0.0.1",
  port: 3000,
  fetch() {
    return new Response("Hello, world!");
  },
};
```

```bash
elide run server.mjs &
wrk -t12 -c256 -d5s http://127.0.0.1:3000/ > /dev/null
wrk -t12 -c256 -d10s --latency http://127.0.0.1:3000/ > elide.txt
kill %1
```

| Step | Why |
| --- | --- |
| Discard a 5-second run first | The first requests compile the handler. |
| Pin the server and `wrk` to separate cores, e.g. `taskset -c 0-7 elide run server.mjs` and `taskset -c 8-15 wrk ...` | Keeps the load generator from taking the server's CPU. |
| Repeat with `--contexts=auto` | One context uses one thread for your handler. |
| Compare `Requests/sec` and the `--latency` percentiles | Averages hide tail latency. |

`bun server.mjs` serves the same file; `deno serve --port 3000 --host 127.0.0.1 server.mjs` needs the address on the
command line.

## Multi-context serving

```sh
elide run --contexts=auto server.mjs
# Or choose the count explicitly:
elide run --contexts=24 server.mjs
```

One process evaluates the server entry module in each context and serves requests concurrently.
Each context has its own JavaScript globals and module state. The process shares one managed heap,
garbage collector, and eligible parsed/JIT-compiled code across contexts. Ordinary objects are not shared
application state; use external coordination when replicas must agree. Process failures and GC pauses
can affect all contexts. Start with `auto`, then measure your workload before choosing a fixed count.

The [published HTTP benchmarks](https://elide.help/docs/benchmarks#multi-context-peak-serving) distinguish default single-context
serving from tuned multi-context serving with HTTP pipelining, and include a configuration table,
architecture diagram, hardware/OS details, and a downloadable runner. Their peak configuration also
selects inline scheduling and io_uring; `--contexts` alone does not reproduce it.


## See also

- [Compatibility Matrix](https://elide.help/docs/compatibility) for API coverage per release
- [Changelog](https://elide.help/docs/changelog) for performance changes per release

---

# Compatibility Matrix

URL: https://elide.help/docs/compatibility

> Elide's measured pass rates on test262, CPython, javac jtreg, WinterTC and Node-API test suites for the current release, and how to reproduce them.

This page shows Elide's pass rates on upstream suites: Test262, the CPython core tests, javac jtreg, WinterTC and
Node-API. Each rate is one Elide build against one suite revision, from the
[`elide-dev/testsuite`](https://github.com/elide-dev/testsuite) report
[`reports/index.json`](https://raw.githubusercontent.com/elide-dev/testsuite/main/reports/index.json).

## Pass Rate Snapshot

<div class="not-prose my-8 space-y-4">
  <div>
    <div class="mb-1 flex items-center justify-between gap-4 text-sm font-medium">
      <span>JavaScript - test262</span>
      <span>99.9%</span>
    </div>
    <div class="h-3 overflow-hidden rounded-full bg-muted">
      <div class="h-full rounded-full bg-primary" style="width: 99.9%;"></div>
    </div>
  </div>
  <div>
    <div class="mb-1 flex items-center justify-between gap-4 text-sm font-medium">
      <span>Java - javac-jtreg</span>
      <span>99.9%</span>
    </div>
    <div class="h-3 overflow-hidden rounded-full bg-muted">
      <div class="h-full rounded-full bg-primary" style="width: 99.9%;"></div>
    </div>
  </div>
  <div>
    <div class="mb-1 flex items-center justify-between gap-4 text-sm font-medium">
      <span>WinterTC - wpt-wintertc</span>
      <span>95.9%</span>
    </div>
    <div class="h-3 overflow-hidden rounded-full bg-muted">
      <div class="h-full rounded-full bg-primary" style="width: 95.9%;"></div>
    </div>
  </div>
  <div>
    <div class="mb-1 flex items-center justify-between gap-4 text-sm font-medium">
      <span>Python - cpython-core</span>
      <span>93.8%</span>
    </div>
    <div class="h-3 overflow-hidden rounded-full bg-muted">
      <div class="h-full rounded-full bg-primary" style="width: 93.8%;"></div>
    </div>
  </div>
  <div>
    <div class="mb-1 flex items-center justify-between gap-4 text-sm font-medium">
      <span>Node-API - node-api</span>
      <span>86.8%</span>
    </div>
    <div class="h-3 overflow-hidden rounded-full bg-muted">
      <div class="h-full rounded-full bg-primary" style="width: 86.8%;"></div>
    </div>
  </div>
</div>

## Headline Suites

| Area | Suite | Elide build | Upstream revision | Result | Regressions |
| --- | --- | --- | --- | --- | --- |
| JavaScript | test262 | `1.6.0+6e718933f` | `de8e621c` | 99.9% passed: 96,235 pass, 4 fail, 90 error, 7,032 skipped | 0 |
| Python | cpython-core | `1.6.0+6e718933f` | `fd17997c` | 93.8% passed: 31,404 pass, 1,259 fail, 831 error, 1,453 skipped | 0 |
| Java | javac-jtreg | `1.6.0+6e718933f` | `6c48f4ed` | 99.9% passed: 3,925 pass, 1 fail, 2 error, 6 skipped | 0 |

Pass rate is `pass / (pass + fail + error)`; skipped tests are excluded.

## Tracked Suites

These suites also run on every release.

| Area | Suite | Elide build | Upstream revision | Result | Regressions |
| --- | --- | --- | --- | --- | --- |
| WinterTC | wpt-wintertc | `1.6.0+6e718933f` | `1eb456f6` | 95.9% passed: 24,065 pass, 1,018 fail, 5 error, 75 skipped | 0 |
| Node-API | node-api | `1.6.0+6e718933f` | `ed33ae74` | 86.8% passed: 1,194 pass, 176 fail, 5 error, 83 skipped | 0 |

## What the Rates Leave Out

<!-- compat-reasons:start -->
Excluded tests are out of scope for any runtime except the one a suite was written for; skipped tests are in
scope but not run. Neither counts toward a pass rate.

- **Out of scope**: tests of another runtime's internals, other platforms or browser-only features.
- **Not supported**: features Elide does not implement yet, or tests that hang.
- **Test environment**: needs something the machine running the suite does not provide.

### test262

0 excluded, 7,032 skipped.

| Reason | Tests | Status |
| --- | --: | --- |
| **Temporal with non-ISO calendars**. Date arithmetic in calendars such as Ethiopian and Islamic is incomplete. | 4,058 | Not supported |
| **Staging tests**. Tests for proposals not yet part of the standard. | 2,794 | Out of scope |
| **Unshipped proposals**. Legacy RegExp accessors and text, bytes and source-phase imports. | 72 | Not supported |
| **`document.all` emulation**. Needs a browser host object. | 70 | Out of scope |
| **Proper tail calls**. Among major engines only Safari's implements them. | 34 | Not supported |
| **Non-blocking agents**. Checks a throw that applies only where `Atomics.wait` cannot block; Elide can block, as Node does. | 4 | Out of scope |

### cpython-core

2,970 excluded, 1,453 skipped.

| Reason | Tests | Status |
| --- | --: | --- |
| **CPython C API and C accelerators**. Tests of CPython's C interfaces and of C versions of modules Elide ships in Python. | 1,183 | Out of scope |
| **CPython implementation details**. Bytecode, the peephole optimizer, opcode tables and other details the Python docs leave to each implementation. | 902 | Out of scope |
| **Other platforms**. Windows, macOS, BSD, mobile and 32-bit tests. | 799 | Out of scope |
| **Socket ancillary data**. `socket.sendmsg` and `socket.recvmsg`. | 346 | Not supported |
| **Missing os, signal and user-database functions**. Functions such as `os.sendfile`, `os.mkfifo`, `os.timerfd_create`, `signal.pthread_sigmask` and the `grp` and `pwd` modules. | 228 | Not supported |
| **Test machine setup**. Third-party packages, Tk, large memory, terminals, locales, root access or interpreter flags the harness does not provide. | 176 | Test environment |
| **poll and epoll selectors**. `selectors.PollSelector` and `selectors.EpollSelector`. | 151 | Not supported |
| **Specialised socket families**. Bluetooth, CAN, RDS, VSOCK and other kernel socket families the test machine does not load. | 109 | Test environment |
| **Writing bytecode files**. Elide does not write `.pyc` files. | 97 | Not supported |
| **Process forking**. `os.fork`, the fork and forkserver start methods and `os.spawn*`. | 95 | Not supported |
| **Hangs and time limits**. Tests that hang, or run past the per-test limit, under Elide. | 70 | Not supported |
| **Reference-counting timing**. Asserts that an object is freed the moment its last reference goes; Elide uses a tracing garbage collector. | 39 | Out of scope |
| **CPython build options and internals**. Debug, statistics and DTrace builds, reference counts and interpreter internals. | 35 | Out of scope |
| **Other**. 2 tests skipped themselves without recording why; the rest give 121 other reasons. | 193 | Various |

### javac-jtreg

0 excluded, 6 skipped.

| Reason | Tests | Status |
| --- | --: | --- |
| **Ignored upstream**. Tests the JDK project itself marks as ignored. | 4 | Out of scope |
| **JVM launcher flags**. `-J` flags configure a JVM launcher; Elide's compiler is a native binary. | 1 | Out of scope |
| **Custom platform providers**. A `--release` PlatformProvider loaded through service discovery. | 1 | Not supported |

### wpt-wintertc

3,640 excluded, 75 skipped.

| Reason | Tests | Status |
| --- | --: | --- |
| **Browser-only features**. Needs a DOM: documents, frames, navigation, media, `<a>` elements or `XMLHttpRequest`. | 3,438 | Out of scope |
| **CORS enforcement**. Browser security policy (preflight, CORS and CORP checks); Node, Deno and other server runtimes do not enforce it. | 202 | Out of scope |
| **TLS and HTTP/2 test servers**. The test server runs without TLS or HTTP/2. | 75 | Test environment |

### node-api

105 excluded, 83 skipped.

| Reason | Tests | Status |
| --- | --: | --- |
| **Node internals**. Tests of Node's private modules and C++ bindings (`--expose-internals`, `internal/test/binding`). | 105 | Out of scope |
| **`node:cluster`**. Elide does not implement `node:cluster`. | 2 | Not supported |
| **Hangs**. Tests that rely on interrupting a busy child process. | 2 | Not supported |
| **Other**. 68 tests skipped themselves without recording why; the rest give 10 other reasons. | 79 | Various |
<!-- compat-reasons:end -->

## Reproduce The Results

To run the suites yourself, follow [`elide-dev/testsuite`](https://github.com/elide-dev/testsuite). The report
behind this page:

```bash
curl -fsSL https://raw.githubusercontent.com/elide-dev/testsuite/main/reports/index.json
```

For each suite it records the Elide build, the upstream revision, and pass, fail, error, skipped and regression
counts.

## Related Docs

- [JavaScript and TypeScript with Elide](https://elide.help/docs/web)
- [Python with Elide](https://elide.help/docs/python)
- [Java and Kotlin with Elide](https://elide.help/docs/jvm)

---

# Code samples

URL: https://elide.help/docs/code-samples

> Runnable Elide samples in TypeScript, JavaScript, Java, Kotlin, Python and WebAssembly: HTTP servers, SQLite, files, streams, workers, coroutines, JSON, Maven dependencies, annotations, tests, interop and OpenTelemetry, each with its command and output.

Run each sample in an empty directory.

## TypeScript without a build

Generics, union types and `satisfies` run directly, with no build step or `tsconfig.json`.

```ts
// shapes.ts
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rect":
      return shape.width * shape.height;
  }
}

function largest<T>(items: T[], size: (item: T) => number): T {
  return items.reduce((a, b) => (size(b) > size(a) ? b : a));
}

const shapes = [
  { kind: "circle", radius: 2 },
  { kind: "rect", width: 3, height: 5 },
] satisfies Shape[];

for (const s of shapes) console.log(`${s.kind}: ${area(s).toFixed(2)}`);
console.log(`largest: ${largest(shapes, area).kind}`);
```

```bash
elide run shapes.ts
```

```text
circle: 12.57
rect: 15.00
largest: rect
```

## HTTP handler

```ts
// server.ts
export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    return Response.json({ path: url.pathname });
  },
};
```

```bash
elide serve --no-tui server.ts
curl http://127.0.0.1:8080/hello
```

```text
{"path":"/hello"}
```

## Routes with URLPattern

Matches request paths with `URLPattern` in a handler served by `elide serve`.

```ts
// api.ts
const users = new Map([
  ["1", { id: 1, name: "Ada" }],
  ["2", { id: 2, name: "Grace" }],
]);

const userRoute = new URLPattern({ pathname: "/users/:id" });

export default {
  async fetch(request: Request): Promise<Response> {
    const match = userRoute.exec(request.url);
    if (!match) return new Response("Not found\n", { status: 404 });
    const user = users.get(match.pathname.groups.id!);
    return user ? Response.json(user) : Response.json({ error: "no such user" }, { status: 404 });
  },
};
```

```bash
elide serve --no-tui api.ts
curl -s http://127.0.0.1:8080/users/2; echo
curl -s -w ' %{http_code}\n' http://127.0.0.1:8080/users/9
```

```text
{"id":2,"name":"Grace"}
{"error":"no such user"} 404
```

## Local server and fetch

Starts a `node:http` server on a free port, calls it with `fetch`, and shuts it down.

```ts
// roundtrip.ts
import { createServer } from "node:http";
import type { AddressInfo } from "node:net";

const server = createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    const { items } = JSON.parse(body) as { items: number[] };
    res.setHeader("content-type", "application/json");
    res.end(JSON.stringify({ count: items.length, sum: items.reduce((a, b) => a + b, 0) }));
  });
});

server.listen(0, "127.0.0.1", async () => {
  const { port } = server.address() as AddressInfo;
  const response = await fetch(`http://127.0.0.1:${port}/sum`, {
    method: "POST",
    body: JSON.stringify({ items: [4, 8, 15, 16, 23, 42] }),
  });
  console.log(response.status, response.headers.get("content-type"));
  console.log(JSON.stringify(await response.json()));
  server.close();
});
```

```bash
elide run roundtrip.ts
```

```text
200 application/json
{"count":6,"sum":108}
```

## Embedded SQLite

```ts
// database.ts
import { Database } from "elide:sqlite";

const db = new Database();
db.exec("CREATE TABLE users (name TEXT)");
db.exec("INSERT INTO users VALUES ('Ada')");
console.log(db.query("SELECT name FROM users").get().name);
```

```bash
elide run database.ts
```

```text
Ada
```

## SQLite transactions

Moves money between accounts in a SQLite transaction that rolls back when a balance would go negative.

```ts
// bank.ts
import { Database } from "elide:sqlite";

const db = new Database();
db.exec("CREATE TABLE accounts (name TEXT PRIMARY KEY, balance INTEGER NOT NULL)");
const open = db.prepare("INSERT INTO accounts VALUES ($name, $balance)");
open.run({ $name: "alice", $balance: 100 });
open.run({ $name: "bob", $balance: 20 });

const adjust = db.prepare("UPDATE accounts SET balance = balance + ? WHERE name = ?");
const balance = db.prepare("SELECT balance FROM accounts WHERE name = ?");

const transfer = db.transaction((from: string, to: string, amount: number) => {
  adjust.run(-amount, from);
  adjust.run(amount, to);
  if (balance.get(from).balance < 0) throw new Error(`${from} cannot send ${amount}`);
});

transfer("alice", "bob", 30);
try {
  transfer("bob", "alice", 500);
} catch (e) {
  console.log("rolled back:", (e as Error).message);
}

for (const [name, amount] of db.prepare("SELECT name, balance FROM accounts ORDER BY name").values()) {
  console.log(name, amount);
}
```

```bash
elide run bank.ts
```

```text
rolled back: bob cannot send 500
alice 70
bob 50
```

## Access rules with CEL

Compiles permission rules written in CEL once with `elide:cel`, then checks them against each user and document. CEL expressions have no side effects and always terminate, so rules can come from configuration.

```ts
// rules.ts
import { compile } from "elide:cel";

const rules = {
  "read": "true",
  "edit": "user.id == doc.owner || 'admin' in user.roles",
  "export": "user.plan == 'pro' && !doc.tags.exists(t, t.startsWith('pii'))",
};
const programs = Object.entries(rules).map(([name, rule]) => ({ name, program: compile(rule) }));

const docs = [
  { id: 1, owner: "ada", tags: ["report"] },
  { id: 2, owner: "grace", tags: ["pii-email", "report"] },
];
const users = [
  { id: "ada", plan: "pro", roles: [] },
  { id: "grace", plan: "free", roles: ["admin"] },
];

for (const user of users) {
  for (const doc of docs) {
    const allowed = programs.filter(({ program }) => program.test({ user, doc }));
    console.log(`${user.id} on doc ${doc.id}: ${allowed.map(({ name }) => name).join(", ")}`);
  }
}

console.log("export reads:", programs[2]?.program.variables.join(", "));
```

```bash
elide run rules.ts
```

```text
ada on doc 1: read, edit, export
ada on doc 2: read
grace on doc 1: read, edit
grace on doc 2: read, edit
export reads: doc, user
```

## Files and paths

Writes a small directory tree with `node:fs`, then walks it and totals file sizes by extension.

```ts
// sizes.ts
import { mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
import { extname, join } from "node:path";

mkdirSync("site/css", { recursive: true });
writeFileSync("site/index.html", "<h1>Home</h1>");
writeFileSync("site/about.html", "<h1>About us</h1>");
writeFileSync("site/css/main.css", "body { margin: 0 }");

const totals = new Map<string, number>();
for (const entry of readdirSync("site", { recursive: true, withFileTypes: true })) {
  if (!entry.isFile()) continue;
  const ext = extname(entry.name);
  const size = statSync(join(entry.parentPath, entry.name)).size;
  totals.set(ext, (totals.get(ext) ?? 0) + size);
}

for (const [ext, bytes] of [...totals].sort()) console.log(`${ext}: ${bytes} bytes`);
```

```bash
elide run sizes.ts
```

```text
.css: 18 bytes
.html: 30 bytes
```

## CSV report

Parses a CSV file and prints revenue per region, largest first.

```text
# sales.csv
region,product,units,price
north,widget,12,2.50
south,widget,4,2.50
north,gadget,3,10.00
east,gizmo,7,4.00
south,gadget,6,10.00
```

```ts
// report.ts
import { readFileSync } from "node:fs";

type Row = { region: string; product: string; units: number; price: number };

const [header, ...lines] = readFileSync("sales.csv", "utf8").trim().split("\n");
const keys = header.split(",");
const rows: Row[] = lines.map((line) => {
  const v = line.split(",");
  return { region: v[0], product: v[1], units: Number(v[2]), price: Number(v[3]) };
});

const revenue = new Map<string, number>();
for (const r of rows) revenue.set(r.region, (revenue.get(r.region) ?? 0) + r.units * r.price);

console.log(`${keys.length} columns, ${rows.length} rows`);
for (const [region, total] of [...revenue].sort((a, b) => b[1] - a[1])) {
  console.log(`${region.padEnd(6)} ${total.toFixed(2).padStart(8)}`);
}
```

```bash
elide run report.ts
```

```text
4 columns, 5 rows
south     70.00
north     60.00
east      28.00
```

## Streams and async iteration

Reads a log file line by line with `node:readline` and counts entries per level.

```javascript
// levels.mjs
import { createReadStream, writeFileSync } from "node:fs";
import { createInterface } from "node:readline";

writeFileSync("app.log", [
  "INFO server started",
  "WARN slow query: 812ms",
  "INFO request /users",
  "ERROR connection reset",
  "INFO request /orders",
].join("\n"));

const counts = {};
const lines = createInterface({ input: createReadStream("app.log") });
for await (const line of lines) {
  const level = line.split(" ", 1)[0];
  counts[level] = (counts[level] ?? 0) + 1;
}
console.log(JSON.stringify(counts));
```

```bash
elide run levels.mjs
```

```text
{"INFO":3,"WARN":1,"ERROR":1}
```

## Transform stream pipeline

Chains a generator source, a `Transform` and a writable sink with `pipeline` from `node:stream/promises`.

```javascript
// pipeline.mjs
import { Readable, Transform, Writable } from "node:stream";
import { pipeline } from "node:stream/promises";

async function* records() {
  yield { sku: "A-1", qty: 3, price: 4.5 };
  yield { sku: "B-7", qty: 1, price: 19.99 };
  yield { sku: "C-2", qty: 10, price: 0.25 };
}

const toCsv = new Transform({
  objectMode: true,
  transform(r, _enc, done) {
    done(null, `${r.sku},${r.qty},${(r.qty * r.price).toFixed(2)}\n`);
  },
});

const lines = [];
const sink = new Writable({
  objectMode: true,
  write(chunk, _enc, done) {
    lines.push(chunk.toString().trim());
    done();
  },
});

await pipeline(Readable.from(records()), toCsv, sink);
console.log(["sku,qty,total", ...lines].join("\n"));
```

```bash
elide run pipeline.mjs
```

```text
sku,qty,total
A-1,3,13.50
B-7,1,19.99
C-2,10,2.50
```

## Command-line arguments

Parses flags and positional arguments with `parseArgs` from `node:util`.

```javascript
// greet.mjs
import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  args: process.argv.slice(2),
  options: {
    greeting: { type: "string", short: "g", default: "Hello" },
    shout: { type: "boolean", default: false },
  },
  allowPositionals: true,
});

for (const name of positionals) {
  const line = `${values.greeting}, ${name}!`;
  console.log(values.shout ? line.toUpperCase() : line);
}
```

```bash
elide run greet.mjs -- --greeting Hi Ada Grace
elide run greet.mjs -- --shout Alan
```

```text
Hi, Ada!
Hi, Grace!
HELLO, ALAN!
```

## Worker threads

Counts primes below 200,000 in four `node:worker_threads` workers and adds up their results.

```javascript
// primes.mjs
import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";

function countPrimes(from, to) {
  let count = 0;
  for (let n = Math.max(from, 2); n < to; n++) {
    let prime = true;
    for (let d = 2; d * d <= n; d++) if (n % d === 0) { prime = false; break; }
    if (prime) count++;
  }
  return count;
}

if (isMainThread) {
  const limit = 200_000, parts = 4, step = limit / parts;
  const jobs = Array.from({ length: parts }, (_, i) =>
    new Promise((resolve, reject) => {
      const w = new Worker(new URL(import.meta.url), { workerData: [i * step, (i + 1) * step] });
      w.once("message", resolve);
      w.once("error", reject);
    }));
  const counts = await Promise.all(jobs);
  console.log("per worker:", counts.join(", "));
  console.log("primes below", limit, "=", counts.reduce((a, b) => a + b));
} else {
  parentPort.postMessage(countPrimes(...workerData));
}
```

```bash
elide run primes.mjs
```

```text
per worker: 5133, 4459, 4256, 4136
primes below 200000 = 17984
```

## TypeScript tests

Runs `node:test` tests written in TypeScript with `elide test`, with no configuration. `--reporter=tap` prints TAP instead of the summary.

```ts
// slugify.ts
export function slugify(title: string): string {
  return title
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-|-$/g, "");
}
```

```ts
// slugify.test.ts
import { describe, test } from "node:test";
import assert from "node:assert";
import { slugify } from "./slugify.ts";

describe("slugify", () => {
  test("lowercases and joins words", () => {
    assert.equal(slugify("Hello World"), "hello-world");
  });

  test("drops punctuation at the ends", () => {
    assert.equal(slugify("  Elide: a runtime! "), "elide-a-runtime");
  });
});
```

```bash
elide test --reporter=tap
```

```text
TAP version 13
# start 1: slugify > lowercases and joins words
ok 1 - slugify > lowercases and joins words
# start 2: slugify > drops punctuation at the ends
ok 2 - slugify > drops punctuation at the ends
1..2
```

## Java records and streams

Runs a single Java file with records, switch expressions and streams, with no build file.

```java
// Payroll.java
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Collectors;

public class Payroll {
  enum Role { ENGINEER, DESIGNER, MANAGER }

  record Employee(String name, Role role, int salary) {}

  public static void main(String[] args) {
    var staff = List.of(
        new Employee("Ada", Role.ENGINEER, 120_000),
        new Employee("Linus", Role.ENGINEER, 110_000),
        new Employee("Susan", Role.DESIGNER, 95_000),
        new Employee("Grace", Role.MANAGER, 130_000));

    Map<Role, Double> average = staff.stream().collect(
        Collectors.groupingBy(Employee::role, TreeMap::new, Collectors.averagingInt(Employee::salary)));

    average.forEach((role, avg) -> {
      String label = switch (role) {
        case ENGINEER -> "Engineering";
        case DESIGNER -> "Design";
        case MANAGER -> "Management";
      };
      System.out.printf("%-12s %,8.0f%n", label, avg);
    });
  }
}
```

```bash
elide run Payroll.java
```

```text
Engineering   115,000
Design         95,000
Management    130,000
```

## Kotlin collections

Groups, sums, sorts and partitions a list of orders with the Kotlin standard library.

```kotlin
// Orders.kt
data class Order(val customer: String, val item: String, val amount: Double)

fun main() {
  val orders = listOf(
    Order("ada", "book", 24.0),
    Order("grace", "laptop", 1299.0),
    Order("ada", "pen", 3.5),
    Order("alan", "book", 24.0),
    Order("grace", "mouse", 25.0),
  )

  orders.groupBy { it.customer }
    .mapValues { (_, list) -> list.sumOf { it.amount } }
    .entries
    .sortedByDescending { it.value }
    .forEach { (customer, total) -> println("%-6s %8.2f".format(customer, total)) }

  val (books, other) = orders.partition { it.item == "book" }
  println("books: ${books.size}, other items: ${other.map { it.item }.distinct().sorted()}")
}
```

```bash
elide run Orders.kt
```

```text
grace   1324.00
ada       27.50
alan      24.00
books: 2, other items: [laptop, mouse, pen]
```

## Kotlin tests

Runs `kotlin.test` tests with `elide test` in a project with an `elide.pkl`. `--reporter=tap` prints TAP instead of the summary.

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "pricing"
```

```kotlin
// src/main/kotlin/Pricing.kt
fun priceWithTax(net: Double, ratePercent: Int): Double = Math.round(net * (100 + ratePercent)) / 100.0
```

```kotlin
// src/test/kotlin/PricingTest.kt
import kotlin.test.Test
import kotlin.test.assertEquals

class PricingTest {
  @Test
  fun addsTax() {
    assertEquals(12.0, priceWithTax(10.0, 20))
  }

  @Test
  fun roundsToCents() {
    assertEquals(10.69, priceWithTax(9.99, 7))
  }
}
```

```bash
elide test --reporter=tap
```

```text
TAP version 13
# start 1: PricingTest > addsTax()
ok 1 - PricingTest > addsTax()
# start 2: PricingTest > roundsToCents()
ok 2 - PricingTest > roundsToCents()
1..2
```

## Kotlin coroutines

Starts three loads with `async` and waits for all of them; the shortest delay finishes first. kotlinx.coroutines is
bundled, so a single file needs no build file.

```kotlin
// Fetch.kt
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking

suspend fun load(name: String, ms: Long): Int {
  delay(ms)
  println("loaded $name")
  return name.length
}

fun main() = runBlocking {
  val sizes = listOf("users" to 300L, "orders" to 200L, "prices" to 100L)
    .map { (name, ms) -> async { load(name, ms) } }
    .awaitAll()
  println("sizes in request order: $sizes")
}
```

```bash
elide run Fetch.kt
```

```text
loaded prices
loaded orders
loaded users
sizes in request order: [5, 6, 6]
```

## Kotlin JSON serialization

Decodes JSON into a `@Serializable` data class, filling defaults, and encodes a copy. The serialization plugin and
runtime are bundled.

```kotlin
// Config.kt
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class Server(val host: String, val port: Int = 8080, val tags: List<String> = emptyList())

fun main() {
  val json = Json { prettyPrint = true }
  val server = json.decodeFromString<Server>("""{"host": "localhost", "tags": ["dev"]}""")
  println(server)
  println(json.encodeToString(server.copy(port = 9090)))
}
```

```bash
elide run Config.kt
```

```text
Server(host=localhost, port=8080, tags=[dev])
{
    "host": "localhost",
    "port": 9090,
    "tags": [
        "dev"
    ]
}
```

## Java with a Maven dependency

Declares Gson in `elide.pkl`; `elide run` resolves it, compiles and runs `jvm.main`.

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "inventory"

jvm {
  main = "app.Inventory"
}

dependencies {
  maven {
    packages { "com.google.code.gson:gson:2.13.1" }
  }
}
```

```java
// src/main/java/app/Inventory.java
package app;

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import java.util.List;

public class Inventory {
  record Item(String sku, int quantity, double price) {}

  public static void main(String[] args) {
    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    Item[] items = gson.fromJson("""
        [{"sku": "A-1", "quantity": 3, "price": 2.5},
         {"sku": "B-2", "quantity": 1, "price": 10.0}]
        """, Item[].class);

    double total = List.of(items).stream().mapToDouble(i -> i.quantity() * i.price()).sum();
    System.out.println(items.length + " items, total " + total);
    System.out.println(gson.toJson(items[0]));
  }
}
```

```bash
elide run
```

```text
2 items, total 17.5
{
  "sku": "A-1",
  "quantity": 3,
  "price": 2.5
}
```

## Elide annotations in Kotlin

Marks an interface with `@API` and a method with `@Delicate`, which callers must opt in to. Kotlin projects get
`dev.elide.annotations` on the classpath; see [Elide annotations](https://elide.help/docs/api-jvm-annotations).

```pkl
// elide.pkl
amends "elide:project.pkl"

name = "cache"

jvm {
  main = "MainKt"
}
```

```kotlin
// src/main/kotlin/Main.kt
import dev.elide.annotations.API
import dev.elide.annotations.Delicate

@API
interface Cache {
  fun get(key: String): String?
  fun put(key: String, value: String)
}

class MemoryCache : Cache {
  private val entries = mutableMapOf<String, String>()

  override fun get(key: String) = entries[key]

  override fun put(key: String, value: String) {
    entries[key] = value
  }

  @Delicate
  fun clear() = entries.clear()
}

@OptIn(Delicate::class)
fun main() {
  val cache = MemoryCache()
  cache.put("user:1", "Ada")
  println(cache.get("user:1"))
  cache.clear()
  println(cache.get("user:1"))
  println(Cache::class.java.isAnnotationPresent(API::class.java))
}
```

```bash
elide run
```

```text
Ada
null
true
```

Without `@OptIn(Delicate::class)`, the build fails with `This API is marked delicate; opt in with
@OptIn(Delicate::class) if you understand its caveats.`

## Python calling JavaScript

Needs the Python component and `--interop`.

```python
# interop.py
from elide import js

total = js("[1, 2, 3, 4].reduce((a, b) => a + b, 0)")
print(total)
```

```bash
elide --interop python interop.py
```

```text
10
```

## JavaScript importing Python

Needs the Python component and `--interop`.

```python
# greet.py
def hello():
    return "Hello from Python"
```

```javascript
// main.mjs
import greet from "./greet.py";
console.log(greet.hello());
```

```bash
elide --interop run main.mjs
```

```text
Hello from Python
```

## WebAssembly from JavaScript

Builds a WebAssembly library from C with `zig`, then imports its exports as an ES module. Needs `zig` to build the `.wasm` file.

```c
// checksum.c
unsigned int adler32(const unsigned char *data, unsigned int len) {
  unsigned int a = 1, b = 0;
  for (unsigned int i = 0; i < len; i++) {
    a = (a + data[i]) % 65521;
    b = (b + a) % 65521;
  }
  return (b << 16) | a;
}
```

```javascript
// main.mjs
import { adler32, memory } from "./checksum.wasm";

const input = new TextEncoder().encode("Wikipedia");
new Uint8Array(memory.buffer).set(input, 1024);
console.log(adler32(1024, input.length).toString(16));
```

```bash
zig cc --target=wasm32-freestanding -O2 -nostdlib -Wl,--no-entry -Wl,--export=adler32 -o checksum.wasm checksum.c
elide run main.mjs
```

```text
11e60398
```

## WASI command

Builds a WASI command from C with `zig` and runs it with arguments. Needs `zig` to build the `.wasm` file.

```c
// wc.c
#include <stdio.h>
#include <string.h>

int main(int argc, char **argv) {
  int chars = 0;
  for (int i = 1; i < argc; i++) {
    chars += strlen(argv[i]);
    printf("%d: %s\n", i, argv[i]);
  }
  printf("%d words, %d characters\n", argc - 1, chars);
  return 0;
}
```

```bash
zig cc --target=wasm32-wasi -O2 -o wc.wasm wc.c
elide run wc.wasm -- polyglot runtime toolchain
```

```text
1: polyglot
2: runtime
3: toolchain
3 words, 24 characters
```

## Python script

Python's standard library runs with no virtual environment. Needs the Python component (`elide setup python`).

```python
# words.py
import json
import re
from collections import Counter
from dataclasses import asdict, dataclass

@dataclass
class Report:
    words: int
    unique: int
    top: list[tuple[str, int]]

text = """Elide runs Python, JavaScript and TypeScript.
Python runs without a separate interpreter; JavaScript runs too."""

words = re.findall(r"[a-z]+", text.lower())
report = Report(len(words), len(set(words)), Counter(words).most_common(3))
print(json.dumps(asdict(report)))
```

```bash
elide python words.py
```

```text
{"words": 15, "unique": 11, "top": [["runs", 3], ["python", 2], ["javascript", 2]]}
```

## PostgreSQL queries

A prepared batch insert, a transaction and an aggregate query with `elide:postgres`. Start a server first, for example
`docker run -d -e POSTGRES_USER=app -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=app -p 127.0.0.1:5432:5432 postgres:17`.

```ts
// orders.ts
import { Database } from "elide:postgres";

const db = await Database.connect(process.env.DATABASE_URL!);

await db.exec("DROP TABLE IF EXISTS orders");
await db.exec("CREATE TABLE orders (id SERIAL PRIMARY KEY, customer TEXT NOT NULL, total NUMERIC(10, 2))");

const insert = await db.prepare("INSERT INTO orders (customer, total) VALUES ($1, $2)");
await insert.executeBatch([["ada", 42.5], ["grace", 18], ["ada", 7.25]]);
await insert.close();

await db.transaction(async (tx) => {
  await tx.exec("UPDATE orders SET total = total * 0.9 WHERE customer = $1", "ada");
});

const result = await db.query(
  "SELECT customer, count(*)::int AS orders, sum(total)::float AS spent FROM orders GROUP BY customer ORDER BY customer",
);
for (const row of await result.all()) console.log(row);

await db.close();
```

```bash
DATABASE_URL=postgresql://app:secret@127.0.0.1:5432/app elide run orders.ts
```

```text
{customer: "ada", orders: 2, spent: 44.78}
{customer: "grace", orders: 1, spent: 18}
```

## Server-sent events

A `ReadableStream` body streams events as they are produced; `request.signal` stops the timer when the client leaves.

```ts
// events.ts
const encoder = new TextEncoder();

Elide.serve({
  hostname: "127.0.0.1",
  port: 3000,
  fetch(request) {
    let timer: ReturnType<typeof setInterval>;
    const body = new ReadableStream({
      start(controller) {
        let n = 0;
        timer = setInterval(() => {
          n += 1;
          controller.enqueue(encoder.encode(`event: tick\ndata: ${n}\n\n`));
          if (n === 3) {
            clearInterval(timer);
            controller.close();
          }
        }, 500);
        request.signal.addEventListener("abort", () => clearInterval(timer));
      },
    });
    return new Response(body, {
      headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
    });
  },
});
```

```bash
elide run events.ts
curl -N http://127.0.0.1:3000/
```

```text
event: tick
data: 1

event: tick
data: 2

event: tick
data: 3
```

Each event arrives half a second after the previous one.

## Request limits

`maxBodyBytes` rejects large request bodies before the handler reads them.

```js
// limits.mjs
const server = Elide.serve({
  hostname: "127.0.0.1",
  port: 0,
  maxBodyBytes: 1024,
  async fetch(request) {
    const body = await request.text();
    return new Response(`received ${body.length} bytes\n`);
  },
});
setTimeout(async () => {
  for (const size of [512, 4096]) {
    const res = await fetch(`http://127.0.0.1:${server.port}/`, { method: "POST", body: "x".repeat(size) });
    console.log(size, res.status, (await res.text()).trim());
  }
  server.close();
}, 0);
```

```bash
elide run limits.mjs
```

```text
512 200 received 512 bytes
4096 413 Payload Too Large
```

## node:http server and client

```js
// http.mjs
import http from "node:http";

const server = http.createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ method: req.method, url: req.url, received: body.length }));
  });
});

server.listen(0, "127.0.0.1", () => {
  const { port } = server.address();
  const req = http.request({ port, host: "127.0.0.1", method: "POST", path: "/items" }, (res) => {
    let data = "";
    res.setEncoding("utf8");
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => {
      console.log(res.statusCode, res.headers["content-type"]);
      console.log(data);
      server.close();
    });
  });
  req.end("hello");
});
```

```bash
elide run http.mjs
```

```text
200 application/json
{"method":"POST","url":"/items","received":5}
```

## Sandboxed subprocess

`--allow-run` lists the commands a program may start; any other command fails.

```js
// spawn.mjs
import { execFileSync } from "node:child_process";

console.log(execFileSync("echo", ["allowed"], { encoding: "utf8" }).trim());
try {
  execFileSync("ls", ["/"]);
} catch (e) {
  console.log(e.message);
}
```

```bash
elide --allow-run=echo run spawn.mjs
```

```text
allowed
spawn of 'ls' is not permitted; grant it with --allow-run=ls
```

## Sign data with Web Crypto

```ts
// sign.ts
const { privateKey, publicKey } = await crypto.subtle.generateKey(
  { name: "ECDSA", namedCurve: "P-256" },
  true,
  ["sign", "verify"],
);

const message = new TextEncoder().encode("ship order 1042");
const algorithm = { name: "ECDSA", hash: "SHA-256" };
const signature = await crypto.subtle.sign(algorithm, privateKey, message);

console.log("signature bytes:", signature.byteLength);
console.log("valid:", await crypto.subtle.verify(algorithm, publicKey, signature, message));

const tampered = new TextEncoder().encode("ship order 9999");
console.log("tampered valid:", await crypto.subtle.verify(algorithm, publicKey, signature, tampered));

const jwk = await crypto.subtle.exportKey("jwk", publicKey);
console.log("public key:", jwk.kty, jwk.crv);
```

```bash
elide run sign.ts
```

```text
signature bytes: 64
valid: true
tampered valid: false
public key: EC P-256
```

## Gzip with CompressionStream

```ts
// gzip.ts
const text = "elide ".repeat(1000);

const compressed = await new Response(
  new Blob([text]).stream().pipeThrough(new CompressionStream("gzip")),
).arrayBuffer();

const restored = await new Response(
  new Blob([compressed]).stream().pipeThrough(new DecompressionStream("gzip")),
).text();

console.log(`original: ${text.length} bytes`);
console.log(`gzip: ${compressed.byteLength} bytes`);
console.log(`round trip: ${restored === text}`);
```

```bash
elide run gzip.ts
```

```text
original: 6000 bytes
gzip: 73 bytes
round trip: true
```

## Dates with Temporal

Month arithmetic clamps to the end of the month, and zoned times keep their wall-clock time across a daylight-saving
change.

```ts
// dates.ts
const start = Temporal.PlainDate.from("2026-01-30");
console.log(start.add({ months: 1 }).toString());

const meeting = Temporal.ZonedDateTime.from("2026-03-28T09:00[Europe/London]");
console.log(meeting.add({ days: 1 }).toString());
console.log(meeting.withTimeZone("America/New_York").toPlainTime().toString());

const due = Temporal.PlainDate.from("2026-12-25");
console.log(start.until(due, { largestUnit: "months" }).toString());
```

```bash
elide run dates.ts
```

```text
2026-02-28
2026-03-29T09:00:00+01:00[Europe/London]
05:00:00
P10M25D
```

## Limit workers

`--limit=workers=N` caps live workers; one more throws `ERR_WORKER_LIMIT`.

```js
// workers.mjs
import { Worker } from "node:worker_threads";

const source = "setInterval(() => {}, 1000)"; // stays alive until terminated
const workers = [];
for (let i = 1; i <= 3; i++) {
  try {
    workers.push(new Worker(source, { eval: true }));
    console.log(`worker ${i} started`);
  } catch (e) {
    console.log(`worker ${i}: ${e.code}`);
  }
}
await Promise.all(workers.map((w) => w.terminate()));
```

```bash
elide --limit=workers=2 run workers.mjs
```

```text
worker 1 started
worker 2 started
worker 3: ERR_WORKER_LIMIT
```

## Filter tests with CEL

`--where` selects tests with a [CEL](https://elide.help/docs/api-cel) expression over `name`, `parents` and `file`.

```ts
// cart.test.ts
import { describe, test } from "node:test";
import assert from "node:assert/strict";

describe("cart", () => {
  test("adds items", () => assert.equal([1, 2].length, 2));
  test("applies discount [slow]", () => assert.equal(Math.round(10 * 0.9), 9));
});

describe("checkout", () => {
  test("charges card", () => assert.ok(true));
  test("sends receipt [slow]", () => assert.ok(true));
});
```

```bash
elide test --where 'name.endsWith("[slow]")'
```

```text
cart.test.ts
⇥ cart > adds items
✓ cart > applies discount [slow] [1ms]
⇥ checkout > charges card
✓ checkout > sends receipt [slow] [3ms]

 2 pass
 2 skip
 0 fail
Ran 4 tests across one file. (0.14s)
```

## JUnit XML in CI

`--reporter junit` writes one XML file per test file for CI test-report steps; a failure exits `1`.

```ts
// price.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";

const total = (items: number[]) => items.reduce((a, b) => a + b, 0);

test("sums prices", () => assert.equal(total([2, 3]), 5));
test("empty cart", () => assert.equal(total([]), 1));
```

```bash
elide test --reporter junit --reporter-outfile reports
```

```text
 1 pass
 0 skip
 1 fail
Ran 2 tests across one file. (0.11s)
```

`reports/js/TEST-price.test.ts.xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<testsuite name="price.test.ts" tests="2" failures="1" errors="0" skipped="0" time="0.026">
  <testcase name="sums prices" classname="price.test.ts" time="0.005"/>
  <testcase name="empty cart" classname="price.test.ts" time="0.021">
    <failure message="Expected values to be strictly equal:&#10;&#10;0 !== 1&#10;" type="ERR_ASSERTION">…</failure>
  </testcase>
</testsuite>
```

## Multi-context server

`--contexts=auto` runs one copy of the module per core (Linux). Each copy keeps its own globals, so the counter counts
per context.

```ts
// counter.ts
const id = crypto.randomUUID().slice(0, 8);
let count = 0;

export default {
  fetch(): Response {
    count += 1;
    return Response.json({ context: id, count });
  },
};
```

```bash
elide serve --no-tui --contexts=auto --port 8080 counter.ts
for i in 1 2 3 4; do curl -s http://127.0.0.1:8080/; echo; done
```

```text
{"context":"60cf3464","count":1}
{"context":"60e90376","count":1}
{"context":"90086101","count":1}
{"context":"4adfe8e1","count":1}
```

Each `curl` opens a new connection, which the server may hand to any context.

## Custom span in TypeScript

Spans from `@opentelemetry/api`, exported by Elide with no SDK installed. `using` ends the inner span with its block.
Start a local collector first: `docker run --rm -p 4318:4318 otel/opentelemetry-collector:0.115.1`.

```ts
// checkout.ts
import { trace } from "@opentelemetry/api";
import { currentSpanContext, flush } from "elide:telemetry";

const tracer = trace.getTracer("checkout");

async function chargeCard(amount: number): Promise<void> {
  using span = tracer.startSpan("charge card");
  span.setAttribute("payment.amount", amount);
  await new Promise((resolve) => setTimeout(resolve, 20));
}

await tracer.startActiveSpan("checkout", async (span) => {
  span.setAttribute("order.id", 42);
  await chargeCard(19.99);
  console.log("charged order 42, sampled:", currentSpanContext()?.traceFlags === 1);
  span.end();
});

console.log("exported:", await flush());
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=checkout elide run checkout.ts
```

```text
charged order 42, sampled: true
exported: true
```

The collector receives `checkout` with its child `charge card`, and the `console.log` line as a log record with
their trace id.

## Metrics instruments

A counter, a histogram with explicit buckets, and an observable gauge.

```ts
// metrics.ts
import { metrics } from "@opentelemetry/api";
import { flush } from "elide:telemetry";

const meter = metrics.getMeter("shop");
const orders = meter.createCounter("shop.orders", { unit: "{order}" });
const latency = meter.createHistogram("shop.charge.duration", {
  unit: "s",
  advice: { explicitBucketBoundaries: [0.05, 0.1, 0.25, 0.5] },
});
const queue: string[] = ["a", "b"];
meter
  .createObservableGauge("shop.queue.depth", { unit: "{job}" })
  .addCallback((result) => result.observe(queue.length));

for (const [region, seconds] of [["eu", 0.08], ["us", 0.21], ["eu", 0.04]] as const) {
  orders.add(1, { region });
  latency.record(seconds, { region });
}

console.log("exported:", await flush());
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=shop elide run metrics.ts
```

```text
exported: true
```

The collector's debug output, trimmed:

```text
InstrumentationScope shop
     -> Name: shop.orders
Data point attributes:
     -> region: Str(eu)
Value: 2.000000
     -> Name: shop.charge.duration
Data point attributes:
     -> region: Str(eu)
Count: 2
Sum: 0.120000
     -> Name: shop.queue.depth
Value: 2.000000
```

## Python span and logging

Needs the Python component. `logging` output is exported as log records with the span's ids; no
`opentelemetry` package is needed.

```python
# orders.py
import logging

import elide.telemetry
from opentelemetry import trace

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
log = logging.getLogger("orders")
tracer = trace.get_tracer("orders")

with tracer.start_as_current_span("import orders") as span:
    span.set_attribute("orders.count", 3)
    log.info("imported %d orders", 3)
    print("sampled:", elide.telemetry.current_span_context()["trace_flags"] == 1)

print("exported:", elide.telemetry.flush())
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=orders elide python orders.py
```

```text
INFO orders: imported 3 orders
sampled: True
exported: True
```

## OTLP to a local collector

A served handler continues the caller's trace: the server span takes the `traceparent` parent, and the handler's own
span is its child.

```ts
// server.ts
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("inventory");

export default {
  async fetch(request: Request): Promise<Response> {
    const id = new URL(request.url).pathname.split("/").pop() ?? "";
    return tracer.startActiveSpan("load item", async (span) => {
      span.setAttribute("item.id", id);
      span.end();
      return Response.json({ id, stock: 7 });
    });
  },
};
```

```bash
docker run --rm -d -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:0.115.1
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=inventory elide serve server.ts
curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' http://localhost:8080/items/17
```

```text
{"id":"17","stock":7}
```

The collector's debug output, trimmed:

```text
InstrumentationScope inventory
    Trace ID       : 4bf92f3577b34da6a3ce929d0e0e4736
    Parent ID      : 6a28bf795e58acfb
    Name           : load item
     -> item.id: Str(17)
InstrumentationScope dev.elide.runtime 1.6.0
    Trace ID       : 4bf92f3577b34da6a3ce929d0e0e4736
    Parent ID      : 00f067aa0ba902b7
    ID             : 6a28bf795e58acfb
    Name           : GET
    Kind           : Server
     -> url.path: Str(/items/17)
     -> http.response.status_code: Int(200)
     -> Name: http.server.request.duration
Exemplar #0
     -> Trace ID: 4bf92f3577b34da6a3ce929d0e0e4736
     -> Span ID: 6a28bf795e58acfb
```

## Baggage across services

Elide's server ignores an incoming `baggage` header until inbound baggage is on, and then admits only allowed keys.

```ts
// server.ts
import { context, propagation } from "@opentelemetry/api";

export default {
  async fetch(): Promise<Response> {
    const baggage = propagation.getBaggage(context.active());
    const tenant = baggage?.getEntry("tenant")?.value ?? "none";
    const debug = baggage?.getEntry("debug")?.value ?? "none";
    return new Response(`tenant=${tenant} debug=${debug}\n`);
  },
};
```

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
ELIDE_OTEL_BAGGAGE_INBOUND=true ELIDE_OTEL_BAGGAGE_ALLOW=tenant \
elide serve server.ts
curl -H 'baggage: tenant=acme,debug=true' http://localhost:8080/
```

```text
tenant=acme debug=none
```

Without `ELIDE_OTEL_BAGGAGE_INBOUND=true`, the response is `tenant=none debug=none`.

---

# Changelog

URL: https://elide.help/docs/changelog

> Release notes for every Elide version, newest first: what was added, changed and fixed in each release, with links to its GitHub release.

Releases are listed newest first; select a version to expand it.

<div class="changelog-meta">
  <span>Latest release <code>1.6.2</code></span>
  <span>For install and upgrade commands, see <a href="https://elide.help/docs/releases">Releases</a>.</span>
</div>

## Inside Elide 1.6.3

Elide 1.6.3 expands the project toolchain with Android builds, Micronaut integration, shared test services, and Python package tools. It also adds Maven version overrides, richer build telemetry, and commands for reading Markdown and rendering configuration. This release is in development; 1.6.2 remains the latest release.

### Build and run an Android app

Create a Kotlin Compose app with the Android template, then build a signed development APK. Elide also builds AAR libraries and app bundles, merges workspace resources and manifests, and supports optional code shrinking. The Compose compiler is opt-in through `kotlin.features.compose`; the template enables it and declares the runtime dependencies.

Install an Android SDK before starting. Elide reports missing SDK components and the commands to install them. Run the following in a new directory; the keystore task creates a development signing key once. The run task installs and launches the app on an attached device, or starts the configured emulator.

Use `elide build android-debug-app` to launch suspended and print the forwarded debugger address. Android testing supports configured host tests and instrumented test APKs; an instrumented test APK needs its own project. App bundles with dynamic feature modules cannot yet be minified.

**Create and launch the app**

```shell
mkdir hello-android
cd hello-android
elide init --template android --plain --skip-defaults -- package=com.example.hello
elide build android-keystore-app
elide build app
elide build android-run-app
```

See [Compose compiler](https://elide.help/docs/toolchain/jvm/kotlinc#compose), [Android starter source](https://github.com/elide-dev/elide/tree/main/project/samples/android), [Android build guide](https://github.com/elide-dev/elide/blob/main/docs/android.md).

### Build Micronaut applications

Declare a Micronaut Core version and Elide installs the matching Java annotation and native metadata processors. Put application settings in `jvm.micronaut.config` to generate `application.json` on the classpath. Elide installs the JSON loader and rebuilds affected artifacts when configuration changes; authored resource files remain supported.

Create these two files in a new project directory. The program starts a Micronaut application context and reads the message from Pkl configuration. Run `elide install`, then `elide run`; it prints `Hello from Pkl`.

Use the Micronaut Core version, which can differ from the platform BOM version. This integration processes Java sources; Micronaut processing through Kotlin KSP is not yet provided. The guide extends this example with JUnit tests, coverage, JVM distributions, and native executables.

**elide.pkl**

```pkl
amends "elide:project.pkl"
name = "hello-micronaut"

dependencies {
  micronaut {
    version = "4.10.23"
    modules { "runtime" }
  }
}
jvm {
  main = "example.Application"
  micronaut {
    config {
      sample { message = "Hello from Pkl" }
    }
  }
}
```

**src/main/java/example/Application.java**

```java
package example;

import io.micronaut.context.ApplicationContext;

public final class Application {
  public static void main(String[] args) {
    try (var context = ApplicationContext.run()) {
      System.out.println(context.getRequiredProperty("sample.message", String.class));
    }
  }
}
```

See [Micronaut guide](https://elide.help/docs/toolchain/jvm/micronaut), [Testing and coverage](https://elide.help/docs/toolchain/testing), [Native packaging](https://elide.help/docs/toolchain/jvm/native-image).

### Share a service across test runners

Declare databases and other test services in `testing.testcontainers`. Elide starts them once for the project, waits for readiness, and gives JavaScript, TypeScript, and JUnit tests the same connection settings. Host ports are allocated dynamically, so concurrent runs need no fixed port reservations.

This example starts an HTTP service and tests its response. Save both files in a new project directory and run `elide test`. A Docker-compatible daemon and JDK 17 or newer are required. Java and Kotlin tests can read the same `TEST_URL` with `System.getenv("TEST_URL")`.

Startup failures fail the test run. Containers are cleaned up after success, failure, or cancellation; installation and compilation alone do not start them. Container tooling stays out of application dependencies.

**elide.pkl**

```pkl
amends "elide:project.pkl"
name = "service-tests"

testing {
  testcontainers {
    containers {
      ["web"] {
        image = "busybox:1.37"
        command {
          "sh"; "-c"
          "mkdir -p /www; echo ready > /www/index.html; httpd -f -p 8080 -h /www"
        }
        ports { 8080 }
        wait { strategy = "http"; port = 8080 }
      }
    }
    environment {
      ["TEST_URL"] = "http://${web.host}:${web.port.8080}/"
    }
  }
}
```

**service.test.ts**

```typescript
import test from "node:test";
import assert from "node:assert/strict";

test("service is ready", async () => {
  const url = process.env.TEST_URL;
  assert.ok(url, "TEST_URL must be supplied by the test runner");
  const response = await fetch(url);
  assert.equal(response.status, 200);
  assert.equal((await response.text()).trim(), "ready");
});
```

See [Container configuration](https://elide.help/docs/toolchain/testing#shared-test-containers), [JavaScript and JUnit sample](https://github.com/elide-dev/elide/tree/main/project/samples/testcontainers).

### Install Python packages and run console tools

Python package tooling is available on demand with the optional Python component. `elide uv install` adds packages to the project environment, which Elide loads without activation. `elide uv tool run` uses a separate environment for a console tool, keeping its dependencies out of the project.

Create the manifest below in a new directory, then install a package and run a tool. The HTTPie command prints help; it does not send a request. Tool environments are cached between runs; `elide uv tool list` shows them and `elide uv tool prune` removes expired or excess entries.

Python remains experimental. Package installation supports compatible wheels only; source builds and arbitrary CPython native extensions are not supported. `elide uv` exposes the documented package and tool commands, not the full upstream command set. Python tests still run through `elide python -m unittest` or an installed pytest, rather than `elide test`.

**pyproject.toml**

```toml
[project]
name = "python-demo"
version = "0.1.0"
requires-python = ">=3.13"
```

**Install a package and run an isolated tool**

```shell
elide setup python
elide uv install attrs
elide python -c 'import attrs; print(attrs.__version__)'
elide uv check
elide uv tool run --from 'httpie==3.2.4' http --help
elide uv tool list
```

See [Python packages and tools](https://elide.help/docs/python-packages), [Python toolchain](https://elide.help/docs/python-toolchain).

### Select one Maven version across the dependency graph

Use `dependencies.maven.resolutions` when a direct or transitive dependency needs a specific version. Each key is a `group:artifact` pair, and the override applies before dependency metadata is fetched, including requests for other classifiers or packaging types.

In this example, the resolution selects Commons Lang 3.20.0 even though the direct dependency requests 3.19.0. Run `elide install` after changing the manifest. An override does not add a missing dependency or restore an excluded one.

Values must be exact versions; ranges and wildcards are rejected. Workspace members inherit root overrides and can replace them by key. Changing or removing an override invalidates the resolved dependency graph.

**elide.pkl**

```pkl
amends "elide:project.pkl"
name = "version-overrides"

dependencies {
  maven {
    packages { "org.apache.commons:commons-lang3:3.19.0" }
    resolutions {
      ["org.apache.commons:commons-lang3"] = "3.20.0"
    }
  }
}
```

See [Maven version overrides](https://elide.help/docs/toolchain/dependencies#maven-version-resolutions).

### Follow a build from tasks to test results

With an OTLP destination configured, build and test commands export correlated spans for tasks, execution units, and individual tests. An invocation ID ties each report together, with task outcomes and cache status attached. In your collector, find the `elide.build` or `elide.test` root span and inspect its children.

Run these commands in an existing project with an OTLP/HTTP collector listening on port 4318. Global telemetry flags go before the command. Without a configured destination, no build or test telemetry is exported; there is no separate build-report flag.

Automatic HTTP server telemetry also gains active-request and body-size measurements, and runtime instrumentation logs retain structured fields and trace context in OTLP export. Guest CPU profiles remain experimental and require separate configuration.

**Send build and test traces to a local collector**

```shell
elide --otel-endpoint=http://localhost:4318 --otel-protocol=http/protobuf build
elide --otel-endpoint=http://localhost:4318 --otel-protocol=http/protobuf test

# Disable telemetry for one invocation, even if the project enables it.
elide --no-otel test
```

See [Build and test reports](https://elide.help/docs/opentelemetry/runtime#enable-build-reports), [Telemetry configuration](https://elide.help/docs/opentelemetry/configuration).

### Generate JSON or YAML from configuration

Evaluate `.pkl` or `.pcf` files directly and render the format your application expects. No Elide project is required. Relative imports resolve from the input file, so configuration can share nearby defaults.

Save the configuration below as `config.pkl`. The JSON command writes `service`, `port`, and `healthPath` with the same values and types; the YAML command renders the same configuration in YAML. Without `--format`, the module controls its output, with PCF as the default.

Rendered content goes to stdout; diagnostics go to stderr. Use `--out config.json` to replace a file atomically after successful evaluation, or `--out -` to explicitly select stdout. TOML output is not supported.

**config.pkl**

```pkl
service = "api"
port = 8080
healthPath = "/health"
```

**Render the configuration**

```shell
elide --format=json config.pkl
elide --format=yaml config.pkl

# Replace a generated file only after successful evaluation.
elide --format=json --out config.json config.pkl
```

See [Pkl rendering guide](https://elide.help/docs/pkl-configuration).

### Read READMEs and runbooks in the terminal

Open a `.md` or `.markdown` file to read headings, lists, tables, and highlighted code blocks with terminal-width wrapping. Task lists and strikethrough are supported. No project manifest is required.

Use an existing README or runbook with the commands below. Piped output is plain, links retain their destinations, and raw HTML is shown as text. Code examples are displayed without execution.

**Read an existing document**

```shell
elide README.md
elide docs/runbook.md | less
elide --no-color README.md > readme.txt
```

See [Terminal Markdown guide](https://elide.help/docs/terminal-markdown).

## Releases

<div class="changelog-timeline">

  <details class="cl-release cl-release-current" open>
    <summary><span class="cl-release-version" role="heading" aria-level="3">1.6.3</span> — Next release</summary>
    <div class="cl-release-body">
      <p>Android builds and Compose, Micronaut applications, shared test containers, Python package tools, Maven version overrides, and terminal document rendering.</p>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Build Android APKs, AAR libraries, and app bundles from <code>elide.pkl</code>. The Android template includes a Kotlin Compose app; device tasks install, run, debug, and test it using an installed Android SDK.</li>
            <li>Enable the Compose compiler with <code>kotlin.features.compose = true</code> or <code>elide kotlinc --compose</code>. Declare a compatible Compose runtime dependency; the compiler plugin remains off by default.</li>
            <li>Declare Micronaut Core dependencies and Elide installs matching Java annotation processors. Configure the application in Pkl or resource files, run JUnit tests with coverage, and package JVM applications or native executables.</li>
            <li>Declare shared test services in <code>testing.testcontainers</code>. JavaScript, TypeScript, and JUnit tests receive the same container connection settings, with readiness checks and cleanup after the run.</li>
            <li>Install Python packages into the project environment with <code>elide uv install</code>, or run console tools in isolated environments with <code>elide uv tool run</code>. Requires the optional Python component; only compatible wheels are supported.</li>
            <li>Override direct and transitive Maven versions with <code>dependencies.maven.resolutions</code>. Workspace members inherit root overrides and can replace them by module.</li>
            <li>Export build tasks and test results as correlated OpenTelemetry spans, with invocation IDs, task outcomes, and cache status. Export requires a configured telemetry destination; guest CPU profiles remain experimental.</li>
            <li>Render <code>.pkl</code> and <code>.pcf</code> files as JSON, YAML, or PCF: <code>elide --format=json config.pkl</code>. Without <code>--format</code>, the module controls its output. No Elide project is required.</li>
            <li>Read Markdown with <code>elide README.md</code>: headings, lists, tables, task lists, and highlighted code blocks adapt to the terminal. Piped output is plain; code blocks are displayed without execution.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Automatic HTTP server telemetry records active requests and request and response body sizes alongside request duration. Throughput counts include unsampled requests.</li>
            <li>Runtime instrumentation logs join the configured OpenTelemetry export, retaining structured fields and trace context. Runtime logging controls apply independently of application logging.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Heap sizing respects Linux container memory limits instead of sizing against host RAM, avoiding oversized default heaps in memory-limited containers.</li>
            <li>Program arguments after <code>--</code> reach the program unchanged, including arguments that resemble Elide engine options.</li>
            <li>Builds preserve compiler arguments and generated sources for editor project synchronization.</li>
            <li>Android debugging lets <code>adb</code> allocate an available forwarded port, removing the race between choosing a port and opening it.</li>
            <li>Telemetry sidecar file descriptors are closed on exec on older glibc systems, so child processes no longer inherit them.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

<details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.6.2</span>
      </span>
      <span class="cl-release-summary">Embedded C compiler and linker via LLVM, Java bindings from C headers, dotenv and encrypted configuration, Java ABI jars, and dependency-aware formatting.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.6.2">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.6.2</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/v1.6.2" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>v1.6.2</code>
        </a>
      </div>
      <p>The <a href="https://elide.help/docs/changelog#inside-elide-1-6-2">1.6.2 feature narrative</a> covers the workflows and links to complete guides.</p>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Embedded C compiler and linker via LLVM: <code>elide cc</code> emits native objects or LLVM IR and links JIT code in memory to invoke a zero-argument <code>long long</code> function.</li>
            <li><code>elide jextract</code> generates Java FFM sources from C headers. Named Pkl binding groups and ad hoc <code>javac --jextract</code> headers also compile in memory with application sources; <code>--emit-bindings</code> exports generated sources for IDEs.</li>
            <li>Application commands load <code>.env</code> and <code>.env.local</code> defaults and Java properties from <code>.properties</code> and <code>.properties.local</code>. Explicit file lists and per-domain disable flags control discovery.</li>
            <li>Dotenv and Java properties accept dotenvx-compatible <code>encrypted:</code> values, with private keys from the inherited environment or selected directories&#x27; <code>.env.keys</code> files.</li>
            <li><code>elide javac --abi-only</code> emits Java header jars through Turbine; <code>--emit-abi</code> adds a header jar alongside a full compilation.</li>
            <li>jfmt resolves imports against project dependencies or an explicit classpath, supports source selections, and works with <code>elide format --install</code> to resolve dependencies first.</li>
            <li>Add build tasks written in JavaScript or TypeScript: modules listed under <code>extensions</code> in <code>elide.pkl</code> declare tasks with inputs, outputs, flags, groups, and ordering, cached like built-in tasks. <a href="https://elide.help/docs/toolchain/build-extensions">Build extensions</a></li>
            <li>Package an extension as a <code>.elx</code> archive with an <code>Extensions.ExtensionArchive</code> artifact.</li>
            <li>Fetch extensions with <code>url:</code>, <code>npm:</code>, or <code>maven:</code> declarations; <code>integrity</code> pins the downloaded bytes.</li>
            <li>Extension tasks call the embedded <code>kotlinc</code>, <code>javac</code>, <code>jar</code>, Native Image, ktfmt, and google-java-format in-process through <code>ctx.tools</code>.</li>
            <li><code>elide build &lt;task&gt; --help</code> describes the flags a task accepts.</li>
            <li>A flag an extension task declares decides whether the task is up to date and which cache entry it uses; <code>keyed: false</code> opts a flag out.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Kotlin ABI-only compilation strips non-inline bodies by default while retaining inline bodies, metadata, and constants needed by downstream compilation.</li>
            <li>Generated native seams share invocation-scoped environment and property loading across native and JVM execution.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>jextract PCH serialization preserves the host runtime’s signal handlers, and split JVM tools resolve their run-context functions on Linux and Windows.</li>
            <li>Child JVMs, project tasks, and Node child processes respect filtered inherited environments instead of retaining denied OS variables.</li>
            <li>KSP and its Analysis API match the bundled Kotlin 2.5.0-Beta2 compiler, including native processor execution.</li>
            <li>The embedded Native Image driver initializes its option descriptors safely and preserves the project&#x27;s working directory.</li>
            <li>macOS telemetry delivers final runtime metrics, spans, logs, and profiles on process exit, with corrected sidecar startup and final-response handling.</li>
            <li>OTLP exports use configured CA files and directory lists in both the parent and export sidecar.</li>
            <li>Recursive macOS file watches retain nested filenames through symlink roots, and POSIX <code>os.hostname()</code> reads the host name without a DNS lookup.</li>
            <li><code>elide classpath --json main:compile test:compile</code> returns each query’s paths in a JSON object, restoring project synchronization for editor integrations that request batched classpaths.</li>
            <li>Package-private <code>#imports</code> resolve within the importing package, including conditional and wildcard targets, so packages such as OpenTelemetry SDK 3 load correctly.</li>
            <li>JavaScript and TypeScript test files retain their file origins, so relative ESM imports resolve under <code>elide test</code>.</li>
            <li>Standalone Java source launches preserve selected environment and property files and honor <code>--no-env</code> and <code>--no-properties</code> without rediscovering automatic files.</li>
            <li><code>elide -m MODULE</code> runs the Python module instead of opening the REPL and offers Python setup before engine startup when the component is missing.</li>
            <li>Native Image distributions retain the ONNX runtime, inference models, and adopted JDK profiles required by optimized builds, fixing ML profile-inference initialization failures.</li>
            <li>Invalid inbound <code>traceparent</code> values discard the accompanying <code>tracestate</code>, preventing it from leaking into child and outbound spans.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>Update the managed Elide and GraalVM toolchains, regenerate native seam bindings and dependency locks, and remove unused runtime and build helpers.</li>
          </ul>
        </section>
      </div>
      <p><a href="https://elide.help/docs/toolchain/native/cc">Embedded C compiler and linker via LLVM</a> · <a href="https://elide.help/docs/toolchain/native/jextract">jextract</a> · <a href="https://elide.help/docs/environment">Environment and properties</a> · <a href="https://elide.help/docs/toolchain/jvm/javac#abi-jars">Java ABI jars</a> · <a href="https://elide.help/docs/toolchain/jvm/formatting">Formatting</a></p>
    </div>
  </details>


  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.6.1</span>
      </span>
      <span class="cl-release-summary">Runs on glibc 2.17 and later, adds a static build for Alpine and other musl systems, moves to Kotlin 2.5.0-Beta2, and updates TLS, compression, and archive dependencies for security advisories.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.6.1">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.6.1</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/v1.6.1" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>v1.6.1</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>A static <code>linux-amd64-musl</code> build runs on Alpine and other musl distributions. The install script picks it on musl and on glibc older than 2.17; <code>--libc=glibc</code> or <code>--libc=musl</code> overrides the choice.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Linux builds for amd64 and arm64 need glibc 2.17 or later, down from 2.34: RHEL and CentOS 7, Amazon Linux 2, Ubuntu 20.04, Debian 11, and later.</li>
            <li>The musl build has no Python and ships no JDK or <code>native-image</code>: <code>elide java</code> uses an installed JDK, and <code>elide native-image</code> uses an installed GraalVM.</li>
            <li>Elide is no longer published to npm, and the <code>@elide-dev/elide</code> package is no longer updated; install with the install script or a package manager.</li>
            <li>Kotlin language and API levels below <code>2.2</code> fail with an error that names the flag and the bundled compiler's minimum, in <code>elide kotlinc</code> and in <code>elide.pkl</code> compiler options.</li>
            <li>HTTP serving removes dot segments from the request path, including encoded <code>%2e%2e</code>, before the handler sees it: <code>/../index.html</code> serves the site root's <code>index.html</code> instead of <code>404</code>. Paths still cannot leave the root.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li><code>--timeout</code> always exits with <code>124</code>; a timed-out program could exit with <code>137</code>.</li>
            <li>The bundled <code>elide-api</code>, <code>elide-insight</code>, and <code>elide-rewrite</code> jars keep the same bytes from build to build, so a lockfile that pins them stays valid when they have not changed.</li>
            <li>The docs MCP server files reports sent as top-level fields or as a JSON string, and accepts a report without an Elide binary, such as a failed install, marked as needing evidence.</li>
            <li>Docs links without the <code>/docs</code> prefix, such as <code>/changelog</code>, redirect to the page they name.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>GraalVM 25.5.5-elide.20, with the blocked-certificate list updated for CVE-2026-91403.</li>
            <li>AWS-LC 5.11.0 for TLS and cryptography, in both the Rust crates and the Java security provider.</li>
            <li>Kotlin 2.5.0-Beta2 with kotlinx-serialization 1.12.0, Metro 1.5.0, and Pkl 0.32.2.</li>
            <li>SQLite 3.53.4 on Linux.</li>
            <li>Security updates: rustls 0.23.46 (RUSTSEC-2026-0346 to 0349), rustls-webpki 0.103.16 (RUSTSEC-2026-0382), webpki-root-certs 1.0.11 (RUSTSEC-2026-0383), ctutils 0.4.6 (RUSTSEC-2026-0385), tokio 1.54.1 (RUSTSEC-2026-0386), zstd 0.14.3 (RUSTSEC-2026-0391, 0395 to 0406, and 0410), and zip 9 (RUSTSEC-2026-0367 to 0369).</li>
            <li>Library updates: Jackson 2.22.4, Gson 2.15.0, CEL 0.15.0, protobuf-java 4.37.0-RC1, commons-codec 1.23.0, commonmark 0.31.0, Caffeine 3.3.1, JaCoCo 0.8.16, ASM 9.11.1, MySQL Connector/J 26.10.0, ThreeTen-Extra 1.11.0, ntex 4.4.1, and oxc 0.156.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.6.0</span>
      </span>
      <span class="cl-release-summary">Built-in OpenTelemetry, Python as an optional component, workspaces, a shared build cache, experimental WebAssembly, and faster startup and HTTP serving.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.6.0">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.6.0</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/v1.6.0" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>v1.6.0</code>
        </a>
      </div>
      <p>Python is an optional component that <code>elide setup python</code> adds. Projects gain workspaces, a shared build cache, Maven publishing, and export to Maven and IntelliJ. WebAssembly runs as an experimental language.</p>
      <p><strong>Faster startup and serving.</strong> JavaScript hello-world starts in 1.43 ms, versus Bun’s 1.63 ms, Deno’s 6.31 ms, and Node.js’s 11.70 ms. Peak single-context serving reached 635,510 requests/sec with default settings. With 24 contexts and HTTP pipelining, the same binary peaked at 10,697,938 requests/sec and averaged 10,574,207 across three error-free runs. These are separate workloads. <a href="https://elide.help/docs/benchmarks">Results and environment</a> · <a href="https://elide.help/assets/benchmarks/http-serving-1.6.0.zip">Download the benchmark package</a></p>
      <p><strong>Shared resources, separate state.</strong> Serving contexts share a managed heap, garbage collector, eligible JIT code, and telemetry infrastructure. JavaScript globals remain separate. <a href="https://elide.help/docs/benchmarks#architecture-comparison">Architecture comparison</a></p>
      <p><strong>OpenTelemetry, built in.</strong> Use the standard JavaScript, TypeScript, or Python API; Elide supplies the SDK and export for traces, metrics, logs, and errors. Profiles are experimental. <a href="https://elide.help/docs/opentelemetry">Configure telemetry</a></p>
      <p><strong>Publish to Maven.</strong> Build and publish JARs with <code>elide publish</code>. Target your local repository, a remote repository, or Maven Central; <code>--dry-run</code> previews the upload. <a href="https://elide.help/docs/toolchain/jvm/publishing">Maven publishing</a></p>
      <p><strong>VS Code and IntelliJ IDEA.</strong> Open an <code>elide.pkl</code> project to sync dependencies and source sets. Build, run, test, debug, and view coverage through the Elide integration. <a href="https://elide.help/docs/vscode">VS Code</a> · <a href="https://elide.help/docs/intellij">IntelliJ IDEA</a></p>
      <p><strong>Report, request, file, directly from your agent or editor.</strong> Connect to <code>https://elide.help/mcp</code> to search docs, find examples, report bugs, and request features. Review and confirm each report before it becomes a public issue. <a href="https://elide.help/docs/agentic-reporting">Reporting workflow</a></p>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>OpenRewrite (experimental): <code>elide rewrite</code> lists, previews, and applies OpenRewrite recipes, with dependency type attribution and supported preconditions selecting files before parsing.</li>
            <li>Python is now an optional component: <code>elide setup python</code> adds it, and the install script takes <code>--with-python</code>.</li>
            <li>Workspaces: <code>workspace { members { ... } }</code> in the root <code>elide.pkl</code> builds several projects as one.</li>
            <li><code>project(&quot;core&quot;).friend()</code> lets a workspace member use a sibling's Kotlin <code>internal</code> declarations; a source set sees those of the sets it depends on.</li>
            <li><code>ELIDE_REMOTE_CACHE=&lt;url&gt;</code> shares a build cache between machines; <code>ELIDE_REMOTE_CACHE_POLICY=smart</code> transfers an entry only when that is faster than rebuilding it.</li>
            <li><code>elide build --workers=N</code> limits build concurrency.</li>
            <li>Unknown, missing, or misspelled build options fail before any task runs and name the closest match.</li>
            <li><code>ELIDE_BUILD_TELEMETRY</code> writes a Chrome trace of the build to disk.</li>
            <li>Select JVM tests with <code>--select=class:...</code>, <code>method:...</code>, or <code>package:...</code>, or by tag with <code>--include-tag</code>.</li>
            <li><code>elide test --where &quot;'api' in parents&quot;</code> filters JavaScript tests with a CEL expression over <code>name</code>, <code>parents</code>, and <code>file</code>.</li>
            <li><code>elide:cel</code> evaluates <a href="https://elide.help/docs/api-cel">CEL</a> expressions from JavaScript: compile once, evaluate many times, no side effects.</li>
            <li><code>jvm.flags</code> apply to JVM tests; <code>jvm.defs</code> apply to runs, tests, start scripts, and container images.</li>
            <li><code>kotlin.features</code> and <code>kotlin.plugins</code> configure Kotlin compiler plugins.</li>
            <li><code>elide kotlinc --abi-only</code> (experimental) emits only an ABI jar.</li>
            <li><code>dependencies.maven.substitutions</code> replaces a Maven artifact with a local jar.</li>
            <li>Jar packaging applies <code>excludes</code>, keeps requested classifiers, and merges <code>META-INF/services</code>.</li>
            <li>A <code>Jvm.JvmApplication</code> artifact packages a runnable JVM application with start scripts and archives.</li>
            <li>Maven publishing: <code>elide publish</code> installs a library into the local Maven repository, or publishes it to a named repository or Maven Central (<code>--to</code>) with checksums and <code>gpg</code> signatures; <code>--dry-run</code> lists what it would send.</li>
            <li>Java annotation processors declared under <code>processors</code> run during compilation.</li>
            <li><code>elide run --coverage</code> collects coverage from a run: JaCoCo for Java and Kotlin, LCOV for JavaScript and TypeScript.</li>
            <li><code>elide run</code> and <code>elide test</code> exit with the program's own exit code.</li>
            <li><code>--allow-env[=NAMES]</code> lets a manifest read environment variables outside the default allowlist.</li>
            <li><code>--max-mem=512m</code> limits the heap; one-shot runs default to 4 GB.</li>
            <li><code>--contexts=N</code> or <code>--contexts=auto</code> serves from several application contexts.</li>
            <li><code>elide project export</code> prints the manifest as JSON, a Maven POM, or an IntelliJ project; it replaces <code>elide manifest</code>.</li>
            <li>WebAssembly (experimental): <code>elide run app.wasm</code> runs a WASI command, JavaScript and TypeScript load WASM libraries with the <code>WebAssembly</code> API or <code>import</code>, and <code>elide native-image</code> compiles a JVM application to WebAssembly.</li>
            <li>The docs MCP server at <code>https://elide.help/mcp</code> searches the docs, compares runtimes, and files bug, performance, expectation, and feature reports once you confirm.</li>
            <li><code>elide agent perf</code> times a command against another runtime or an installed Elide version, offline.</li>
          </ul>
          <p><a href="https://elide.help/docs/elide-pkl-reference#workspaces">Workspaces</a> · <a href="https://elide.help/docs/wasm">WebAssembly and WASI</a> · <a href="https://elide.help/docs/toolchain/source-sets">Source sets</a></p>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Serving and <code>fetch</code> use the native transport by default on Linux and macOS; <code>--transport=nio</code> selects the portable one.</li>
            <li>A program starts only the languages it uses; <code>--interop</code> lets JavaScript, TypeScript, and Python call each other.</li>
            <li>Source sets follow convention: <code>src/&lt;set&gt;/&lt;language&gt;</code>, <code>src/&lt;set&gt;</code>, then a flat <code>src</code> or <code>test</code>.</li>
            <li><code>elide test</code> stops discovery at a nested project; name its path to run it.</li>
            <li>A <code>--release</code> build no longer counts as up to date after a debug build.</li>
            <li>Plain <code>http://</code> Maven repositories are refused except on loopback; <code>--allow-http-repositories</code> allows them.</li>
            <li><code>--timeout</code> kills the whole process tree, then exits <code>124</code>; <code>--timeout 0</code> disables it.</li>
            <li><code>NODE_TLS_REJECT_UNAUTHORIZED=0</code> prints Node's warning once.</li>
            <li>jvmstat is off by default; <code>--vmstat</code> makes the process visible to <code>jps</code>, <code>jstat</code>, and <code>jcmd</code>.</li>
            <li>Development, MCP, and CDP servers accept only local <code>Host</code> and <code>Origin</code> values; <code>elide mcp</code> reads <code>ELIDE_MCP_TOKEN</code>.</li>
            <li>A pinned version that is not installed prompts before downloading; <code>ELIDE_AUTO_INSTALL=1</code> answers yes.</li>
            <li>Java compiles with <code>--release</code>, targeting <code>jvm.target</code> (default Java 21).</li>
            <li>A <code>JavadocJar</code> whose sources include Kotlin is generated by Dokka; <code>generator = "javadoc"</code> keeps <code>javadoc</code>.</li>
            <li>Release channels are <code>release</code> and <code>nightly</code>, and the install scripts default to <code>release</code>; <code>preview</code> is gone.</li>
            <li>Linux builds link glibc dynamically and need glibc 2.34 or later; 1.3 builds were static, and musl distributions such as Alpine are no longer supported.</li>
            <li>Within a <code>MAJOR.MINOR</code> line, patch releases only add manifest schema properties; a manifest that uses a removed property fails and names the version to pin.</li>
            <li>JVM coverage reports go under <code>.dev/reports/coverage/jvm/</code>.</li>
            <li>A top-level <code>coverage</code> block in <code>elide.pkl</code> replaces <code>testing.coverage</code>.</li>
            <li><code>elide agent bug --json</code> prints an <code>elide.report/1</code> skeleton; <code>--kind</code> selects <code>bug</code>, <code>perf</code>, <code>expectation</code>, or <code>feature</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Memory and CPU limits apply in containers with a private cgroup namespace (the Docker and Podman default) and on cgroup v1 and hybrid hosts.</li>
            <li>Startup no longer crashes on linux-arm64; Windows startup and the directory watcher work again.</li>
            <li>Python: <code>bz2</code>, <code>lzma</code>, and <code>multiprocessing</code> spawn pools work.</li>
            <li>Python: thread switching, <code>gc.collect()</code>, warnings, and <code>ProcessPoolExecutor</code> shutdown match CPython.</li>
            <li>Python: <code>assert</code> runs (<code>__debug__</code> is <code>True</code> unless <code>-O</code>), <code>sys.flags</code> matches CPython, and <code>-E</code> and <code>-I</code> ignore <code>VIRTUAL_ENV</code>.</li>
            <li>Python: tracebacks from a <code>.py</code> file start at that file; starting a thread without <code>--allow-threads</code> raises <code>RuntimeError</code> naming the flag.</li>
            <li><code>fetch</code> retries an idempotent request on a closed keep-alive connection; <code>https</code> applies <code>ca</code>.</li>
            <li><code>fetch</code> over HTTP/2 runs at full speed on high-latency links, and a response dropped unread releases its connection.</li>
            <li>Node: <code>MessagePort</code>, <code>BroadcastChannel</code>, <code>dgram</code>, <code>net</code>, <code>dns</code>, <code>fs</code>, streams, <code>vm</code>, <code>AsyncLocalStorage</code>, signals, and child-process IPC match Node.</li>
            <li><code>console.log</code> prints objects, arrays, and maps as Node does.</li>
            <li><code>AsyncContext</code> values reach timer, <code>setImmediate</code>, <code>process.nextTick</code>, and <code>queueMicrotask</code> callbacks; <code>Intl.Segmenter</code> splits Chinese and Japanese words.</li>
            <li>TypeScript keeps its source line numbers in stack traces, test failures, coverage, and debugger breakpoints.</li>
            <li>The DAP debugger no longer pauses on entry and prints <code>Debugger listening on …</code>.</li>
            <li>HTTP serving answers <code>413</code> for oversized uploads, <code>400</code> for malformed or conflicting headers, and <code>408</code> for a stalled request body; <code>elide dev</code> answers <code>405</code> to methods other than <code>GET</code> and <code>HEAD</code>.</li>
            <li>Static files with percent-encoded paths resolve.</li>
            <li>The development server reloads only when files change.</li>
            <li>REPL: Ctrl+C no longer resets an idle session, and Ctrl+D exits a runaway evaluation.</li>
            <li><code>elide init</code> and archive extraction refuse entries and links that escape the target directory, and extraction drops setuid bits.</li>
            <li>Crash reports refuse a planted crash directory and honor <code>ELIDE_SYS_TMP</code>.</li>
            <li><code>--allow-run=name</code> no longer allows a path-qualified command of that name.</li>
            <li><code>elide install</code> no longer hangs on a TLS server that requires a client certificate.</li>
            <li>javac applies <code>-encoding</code>.</li>
            <li>Kotlin: <code>elide run file.kt</code> works with compiler plugins; changing <code>kotlin.features</code> recompiles.</li>
            <li>Kotlin: single files can use the <code>elide-api</code> annotations, a snippet without <code>main</code> fails with one message, and <code>.kts</code> files in a source set are skipped with a warning.</li>
            <li><code>elide kotlinc -Xplugin=</code> runs the all-open, no-arg, sam-with-receiver, assignment, and Lombok plugins, from Maven and Bazel too; other plugin JARs fail with a compiler error instead of a crash.</li>
            <li><code>elide kotlinc --plugins serialization</code>, <code>atomicfu</code>, or <code>metro</code> adds the plugin's runtime; Kotlin projects get the atomicfu runtime, and incremental compiles see Java sources.</li>
            <li><code>elide-api</code> with version <code>latest</code> resolves, <code>jvm.features.testing = false</code> drops the bundled JUnit, and <code>elide classpath</code> reports a failed resolution instead of crashing.</li>
            <li><code>--insights</code> applies to single-file Java and Kotlin runs, and a broad filter no longer stops the JVM.</li>
            <li>The archives ship <code>lib/jspawnhelper</code> executable, so Elide as <code>JAVA_HOME</code> runs forked JVMs such as Surefire's.</li>
            <li><code>elide mvn</code> verifies the native Maven download before running it.</li>
            <li><code>elide build --workers 2</code> is refused, and the error names the <code>--workers=2</code> spelling.</li>
            <li>A task record that cannot be saved no longer makes every task rebuild.</li>
            <li>Tests: a suite that skips itself reports as skipped; every <code>--exec</code> file is included in the JaCoCo report.</li>
            <li>MCP <code>build/cancel</code> reports <code>cancelled=true</code> only when it stopped a build.</li>
            <li><code>--heap-dump-on-oom</code> exits after writing the dump.</li>
            <li><code>elide serve</code> keeps the newest request visible.</li>
            <li>Subcommand help shows its footer.</li>
            <li><code>elide run</code> and <code>elide init</code> print each error once, <code>elide test</code> no longer prints <code>Build failed</code> when tests fail, and <code>elide -p DIR adopt</code> adopts <code>DIR</code>.</li>
            <li><code>LANG=fr</code> and other bare language tags select that language, and <code>--locale</code> applies to <code>--help</code>; <code>elide lsp</code> reports its version to the editor.</li>
            <li>Nightly versions pinned by date no longer re-download.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>Kotlin 2.5.0-Beta1; manifests accept Kotlin language and API level <code>2.5</code>.</li>
            <li>JDK 25.0.4.</li>
            <li>Python 3.13.</li>
          </ul>
        </section>
      </div>
      <h4 id="story-openrewrite">OpenRewrite (experimental)</h4>
      <p><code>elide rewrite</code> lists, previews, and applies OpenRewrite recipes. Add recipe modules to <code>dependencies.maven.devPackages</code>; Elide supplies dependency type information without a build plugin.</p>
      <p>Supported preconditions use the reference index to select candidate files before parsing. Other recipes scan the full source set. <code>--no-prefilter</code> skips compilation and parses every Java source.</p>
      <p>Use the index directly to resolve classes, inspect members, follow references, and find Java or Kotlin usages with <code>elide index used-by</code>.</p>
      <p>Experimental in 1.6.0, with compatibility hardening planned for 1.6.1. Dependency annotation values are not yet supported. Review the dry-run diff before applying changes.</p>
      <pre><code class="language-bash">elide rewrite --list
elide rewrite org.openrewrite.java.RemoveUnusedImports --dry-run
elide rewrite org.openrewrite.java.RemoveUnusedImports</code></pre>
      <p><a href="https://elide.help/docs/toolchain/jvm/rewrite">OpenRewrite workflow</a> · <a href="https://elide.help/docs/toolchain/jvm/code-index">Dependency code index</a></p>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.5.4</span>
      </span>
      <span class="cl-release-summary">Experimental native transport v2, faster HTTP serving, and clearer profiling and tooling diagnostics.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.5.4">
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.5.4%2B20260921" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.5.4+20260921</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Opt into the experimental v2 transport with <code>--transport=v2</code> or <code>ELIDE_TRANSPORT_V2=1</code>. An explicit <code>--transport</code> flag takes precedence; <code>auto</code> keeps the existing default.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Serve static files faster, with cached-file revalidation.</li>
            <li>Reduce HTTP request overhead with native HTTP/1 parsing and response encoding for transport v2, cached URL parsing and header names, and fewer per-response allocations.</li>
            <li>Reduce JavaScript allocation and execution overhead in URL, header, buffer, and filesystem operations.</li>
            <li>Start faster and download a smaller distribution.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Collect CLI profiler results after asynchronous work and exit handlers finish, including Python project entry points.</li>
            <li>Print profiler results when a long-running program is stopped with Ctrl+C, with bounded shutdown reporting.</li>
            <li>Show expected build-tool failures as user-friendly errors instead of stack traces or crash reports, and render Java and Kotlin compiler diagnostics consistently in direct tool calls and project builds.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.5.3</span>
      </span>
      <span class="cl-release-summary">Faster startup and HTTP serving, test debugging, resource limits, and fixes for bundled JVM tools.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.5.3">
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.5.3%2B20260917" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.5.3+20260917</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Start JavaScript programs faster: a Linux release benchmark cut <code>elide run hello.js</code> from 31 ms to 7.7 ms.</li>
            <li>Serve more HTTP requests: the Linux echo benchmark improved 4.5×, from 25K to 114K requests/sec at 256 connections. Static and development servers also reuse HTTP/1.1 connections for faster repeat requests.</li>
            <li>Download smaller distributions while keeping Java and Kotlin compilers, formatters, and other JVM tools included by default.</li>
            <li>Run JavaScript tests with less overhead and lower memory use after tests finish. Programs using buffers, URLs, events, timers, and console output also allocate less memory.</li>
            <li>Keep native HTTP and WebSocket services within a bounded number of background threads under load.</li>
          </ul>
          <p><a href="https://elide.help/docs/dev-server">Development Server</a></p>
        </section>
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Attach a debugger to tests with <code>elide test --debugger</code>: use Chrome DevTools for JavaScript/TypeScript tests or a JVM debugger for Java/Kotlin tests. Select a JVM port with <code>--debugger=5005</code>.</li>
            <li>TAP test reports include test-start events and associate output with the test that produced it, helping editors show progress and diagnostics.</li>
            <li>Limit JavaScript/TypeScript workers and open <code>node:fs</code> handles with <code>--limit=workers=COUNT</code> and <code>--limit=fds=COUNT</code> on scripts and <code>elide run</code>. Limits include descendant workers; <code>--timeout</code> requests cleanup of the script and its workers.</li>
            <li>Select trusted execution with <code>--sandbox=trusted</code> and explicitly control native access with <code>--allow-native</code> or <code>--no-native</code>. Bare <code>--sandbox</code> keeps its filesystem-only behavior.</li>
            <li>Pin a nightly manifest schema at <code>pkl.elide.dev/&lt;version&gt;-&lt;stamp&gt;/project.pkl</code>; Elide rejects stamps that do not match its embedded build.</li>
          </ul>
          <p><a href="https://elide.help/docs/debugging">Debugging tests</a> · <a href="https://elide.help/docs/sandbox">Permissions and resource limits</a> · <a href="https://elide.help/docs/elide-pkl-reference">Manifest reference</a></p>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Bundled JVM tools work through the standard macOS installation: <code>elide javac -- -help</code>, Java compilation, and other JVM tool commands no longer incorrectly report that <code>jvmtools</code> is missing when <code>elide</code> is launched through an installation symlink. No separate toolchain installation is needed.</li>
            <li>Keep filesystem, network, and subprocess permissions scoped to each workload, including its workers and background file operations, so one workload’s settings do not change another’s access.</li>
            <li>Cancel an HTTP request without a late cancellation interrupting an unrelated request.</li>
            <li>JVM debugging now listens on <code>127.0.0.1</code> by default. For remote attachment, set an explicit address such as <code>--debugger=0.0.0.0:5005</code>. Invalid debugger options are rejected instead of silently running without a debugger.</li>
            <li>Keep update notices out of redirected stderr and CI logs, and report timeout errors in the selected language.</li>
            <li>Fix <code>elide classpath -q</code>. Tool wrappers reject misplaced <code>--version</code>; pass tool flags after <code>--</code>, as in <code>elide jar -- --version</code>. Formatter help explains how to check without rewriting files.</li>
            <li>Copy code snippets throughout the docs with a dedicated copy button.</li>
          </ul>
          <p><a href="https://elide.help/docs/cli-references">CLI reference</a></p>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.5.2</span>
      </span>
      <span class="cl-release-summary">Native HTTP transport, flight recordings and heap dumps, typed build flags, <code>elide adopt</code>, a TAP reporter, and broad CLI and Node fixes.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.5.2">
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.5.2%2B20260908" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.5.2+20260908</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>New <code>elide adopt</code> command adopts Elide in an existing project through Claude or Codex; every prompt can be answered up front for non-interactive use.</li>
            <li>Typed build flags: <code>--flag=NAME[=VALUE]</code> or <code>-fNAME</code> on every project-aware command, read from <code>build.flags</code> in the manifest. See <a href="https://elide.help/docs/toolchain/build-flags">Build Flags</a>.</li>
            <li>An ES module that exports a <code>fetch</code> handler runs as a server under <code>elide run</code>, <code>elide serve</code>, and <code>elide dev</code>; interactive <code>serve</code> and <code>dev</code> show the serving TUI for scripts.</li>
            <li>Native builds route <code>fetch</code> and <code>Elide.serve</code> through a native HTTP transport: HTTP/1.1 and HTTP/2, streaming bodies, cancellation, graceful shutdown, and HTTP proxy support. <code>elide info</code> reports the active backend.</li>
            <li><code>elide test --reporter tap</code> emits one TAP 13 stream for JavaScript and JVM tests; <code>--reporter-outfile</code> writes <code>.tap</code> files.</li>
            <li>Capture JFR recordings and heap dumps with <code>--jfr</code>, <code>--jfr-settings</code>, <code>--heap-dump</code>, and <code>--heap-dump-on-oom</code>, or familiar <code>-XX:</code> options; see <code>elide help instruments</code>.</li>
            <li>Inspect running native processes with jvmstat and the JDK's <code>jcmd</code> on Linux and macOS: start and dump recordings, capture heaps, and print thread stacks.</li>
            <li>Profile JIT-compiled guest code with <code>--jitdump</code> and Linux <code>perf</code>.</li>
            <li>Elide-specific JFR events record runtime boot, guest program start and exit, and HTTP request lifecycle.</li>
            <li>Debugger listeners bind to configurable hosts and ports.</li>
            <li>The project manifest Pkl schema is published per Elide release at <code>pkl.elide.dev/&lt;version&gt;/</code>, for editor tooling and <code>amends</code> clauses; a manifest may pin one of those versions, and a pin newer than the Elide evaluating it is read with that Elide's schema.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li><code>elide run</code> sent a JVM program's stdout to stderr. Guest output is now written to Elide's own streams byte for byte, redirected output is free of ANSI, and <code>--no-color</code> and <code>--quiet</code> apply to build output.</li>
            <li><code>elide run --debugger</code> no longer starts an unrequested MCP endpoint; the inspector identifies itself as Elide, suspension messages are clearer, and an errant flag warning is gone.</li>
            <li><code>--version</code> and <code>--help-all</code> work on commands with required arguments, and <code>--help-all</code> describes the selected command rather than the root.</li>
            <li><code>--debugger</code> and <code>--profiler</code> are global like the rest of the diagnostics flags; <code>--quiet</code> no longer suppresses <code>manifest</code>, <code>project info</code>, or <code>project advice</code> output; stale flags were removed from help.</li>
            <li><code>elide test</code> rejects unknown <code>--reporter</code> values, parses <code>-t=pattern</code>, skips <code>vendor/</code>, resolves the project from a named test path, and skips JVM tests when paths match only JavaScript tests.</li>
            <li><code>elide init</code> prints a diagnostic on every non-interactive failure path.</li>
            <li><code>elide javaformat --list-diffs</code> no longer rewrites files in place, and <code>elide mvn</code> locates Maven home.</li>
            <li>Node: <code>node:test</code> files run outside <code>elide test</code> fail with an error instead of being skipped silently; <code>scrypt</code> accepts derived-key lengths below 16; <code>performance.measure</code> uses a named start mark; queuing strategy <code>size</code> is read correctly; <code>spawnSync</code> applies <code>inherit</code> and <code>ignore</code> stdio; <code>dns.lookup</code> with <code>all</code>; unknown <code>node:</code> imports throw; <code>performance.nodeTiming</code> and timeout messages match Node.</li>
            <li>Ticks and microtasks now run after each timer callback, matching Node's ordering; stream destroy callbacks run at the correct time.</li>
            <li>Context scheduling handles creation failures, shutdown races, and full callback queues.</li>
            <li><code>--profiler=memtracing</code> no longer aborts at startup.</li>
            <li>Maven module dependencies are added to the <code>elide native-image</code> classpath; a build fails when it references a missing artifact.</li>
            <li>The apt repository's signing key verifies on current Ubuntu releases.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Native builds on Linux and macOS arm64 allocate through one mimalloc core across Rust, C, and runtime unmanaged memory.</li>
            <li>The JVM toolchain is in a shared library beside the binary, loaded on demand; the main executable is smaller.</li>
            <li>Terminal rendering moved to a single Rust renderer, replacing the vendored JVM terminal libraries.</li>
            <li>The <code>elide help</code> corpus is a separate file at <code>doc/elide-docs.bin</code> beside the binary; <code>ELIDE_DOCS</code> overrides its location.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>Upgraded the Rust toolchain to <code>1.100.x</code> and LLVM to <code>23.x</code>.</li>
            <li>New guides: <a href="https://elide.help/docs/instruments">Monitoring and Profiling</a>, <a href="https://elide.help/docs/toolchain/build-flags">Build Flags</a>, VS Code and IntelliJ plugins, native Maven, architecture tours, and a generated embedded-versions page.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.5.1</span>
      </span>
      <span class="cl-release-summary">Small bugfix release following 1.5.0: REPL multiline fixes and Node TLS environment variables for <code>fetch</code>.</span>
    </summary>
    <div class="cl-release-body">
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>fetch</code> reads Node's TLS environment variables: <code>NODE_TLS_REJECT_UNAUTHORIZED</code>, <code>NODE_USE_SYSTEM_CA</code>, and <code>NODE_EXTRA_CA_CERTS</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>The REPL handles newlines correctly and no longer renders multiline prompts incorrectly.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.5.0</span>
      </span>
      <span class="cl-release-summary">Updates the Python and JVM toolchains and expands Node compatibility across core runtime APIs.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.5.0">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.5.0</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.5.0%2B20260902" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.5.0+20260902</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>The embedded Python runtime and bundled standard library target Python <code>3.13</code>.</li>
            <li>The bundled Kotlin compiler is updated to <code>2.4.10</code>; the Java toolchain targets JDK 25.</li>
            <li><code>elide:crypto</code>, <code>elide:fs</code>, <code>elide:net</code>, and <code>elide:process</code> now match their <code>node:*</code> modules. Compression remains available through <code>node:zlib</code> and the Compression Streams API; there is no <code>elide:compression</code> module.</li>
            <li>Buffer, timer handles, process and OS data, performance APIs, async context and abort behavior, TLS, and other Node compatibility were expanded or corrected.</li>
            <li><code>process.env</code> can be replaced, and <code>process.loadEnvFile([path])</code> explicitly loads dotenv files.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>node:zlib</code> adds Zstandard support, stream constructors, <code>crc32</code>, and <code>codes</code>.</li>
            <li><code>node:util</code> adds formatting, <code>callbackify</code>, <code>inherits</code>, deep equality, deprecation and debug helpers, system-error helpers, ANSI stripping and styling, and dotenv parsing.</li>
            <li><code>PerformanceObserver.supportedEntryTypes</code> includes <code>function</code>, and the module loader exposes <code>node:http</code> and <code>node:tls</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>The CLI, project, installation, and language guides were consolidated and verified against the 1.5 binary.</li>
            <li>Server guidance now reflects the static and development servers' observed <code>3000</code> default.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.7</span>
      </span>
      <span class="cl-release-summary">Installs native Maven images on demand, adds Spring-specialized builds, and fixes the nightly upgrade prompt.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.7">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.7</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.7%2B20260901" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.7+20260901</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>elide mvn --flavor spring@&lt;version&gt;</code> selects a native Maven image specialized for a Spring Boot line. Without the flag, the project's POM is read for its Boot version and the matching image is chosen, or the generic one if none matches.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li><code>elide upgrade --channel=nightly</code> no longer offers a build to itself as <code>v1.4.6 -&gt; v1.4.6</code>. Both sides of the message include the datestamp and commit that identify a nightly, so the running build and the candidate are distinguishable.</li>
            <li><code>elide javaformat</code> and <code>elide ktfmt</code> walk directory arguments.</li>
            <li><code>elide init</code> no longer requires a TTY for the documented non-interactive run.</li>
            <li><code>elide serve --host</code> is applied.</li>
            <li><code>elide install --with</code> rejects unknown classifiers.</li>
            <li><code>elide test</code> runs sequentially by default on both engines.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>The distribution no longer bundles native Maven images. <code>elide mvn</code> installs the image it needs on first use.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.6</span>
      </span>
      <span class="cl-release-summary">Parallelizes <code>elide test</code>, narrows <code>elide install</code> to Maven by default, and reorganizes the CLI help.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.6">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.6</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.6%2B20260830" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.6+20260830</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>elide --help</code> now groups commands under four headings and hides ten rarely used commands; <code>--help-all</code> prints everything.</li>
            <li>A <code>--profiler=memtracing</code> mode that uses the runtime memory tracer.</li>
            <li>Build tools record their argument vectors as <code>&lt;tool&gt;.args</code> beside primary outputs &mdash; <code>javac</code> and <code>kotlinc</code> as well as <code>native-image</code> &mdash; and the recorded argfiles are inputs to the build cache.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>All manifest evaluations now share one execution layer, fixing "invalid sharing of AST nodes" errors on a second manifest evaluation.</li>
            <li>Precompiler diagnostics are scoped per operation, so concurrent precompiles no longer report each other's errors.</li>
            <li>Maven POM profiles activated by <code>&lt;activation&gt;&lt;condition&gt;</code> expressions now evaluate correctly.</li>
            <li>Mutable multipath container operations are implemented rather than stubbed.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li><code>elide test</code> runs in parallel on both engines: <code>--concurrency</code> defaults to one worker per CPU (test files for JavaScript, test classes for the JVM), <code>--concurrency=1</code> forces a sequential run, and <code>--concurrency=0</code> is rejected at parse time. Discovery overhead is reduced, and JVM tests are no longer recompiled on every invocation.</li>
            <li>Coverage is now opt-in on both test engines: collection happens only when <code>--coverage</code> is passed or the manifest enables it, and the manifest default is now off.</li>
            <li><code>elide install</code> installs Maven dependencies and nothing else by default; a neighboring <code>package.json</code>, <code>pyproject.toml</code>, or <code>requirements.txt</code> produces a one-line note on stderr, and <code>--ecosystems=&lt;names&gt;</code> installs other ecosystems. <code>uv</code> is no longer bundled.</li>
            <li>The default <code>elide test --coverage</code> report is a rollup summary; per-file rows appear with <code>--verbose</code>.</li>
            <li>The download is roughly 30 MiB smaller.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.5</span>
      </span>
      <span class="cl-release-summary">Retires the closed-source subsystems for the Apache-2.0 open-source release, adds CLI commands for AI coding agents, and fixes incorrect results across test, format, run, install, and classpath.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.5">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.5</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.5%2B20260827" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.5+20260827</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>elide agent</code>, commands for AI coding agents: <code>agent help</code> prints documentation as Markdown on stdout, <code>agent diagnostics</code> reports status (with <code>--json</code>), and <code>agent bug</code> assembles a bug report. <code>elide help &lt;topic&gt; --format=markdown</code> works everywhere, and <code>elide help</code> no longer panics for non-interactive callers.</li>
            <li>Elide detects when an AI coding agent is running it and switches to plain output &mdash; no ANSI sequences, no frames &mdash; in both the parsing and rendering layers.</li>
            <li><code>elide install</code> writes resolved classpath files to <code>.dev/dependencies/m2/{compile,runtime,test,processors}.classpath</code>, in the same format <code>elide classpath &lt;usage&gt;</code> prints, so external tools can read a classpath without invoking Elide.</li>
            <li>Distributions include the Apache-2.0 <code>LICENSE</code> and <code>NOTICE</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li><code>elide format</code> on Java silently did nothing in write mode &mdash; formatted output was discarded instead of written back &mdash; and check/dry-run modes mis-reported results for both Java and Kotlin.</li>
            <li><code>elide test &lt;path&gt;</code> treats paths as a real filter: zero matches now fails and names the paths, and the JVM engine no longer runs the whole suite unfiltered while reporting success. A package-like bare token maps to a JUnit package selector, and an existing path always takes precedence, resolved against the project root.</li>
            <li><code>-t</code>/<code>--test-name-pattern</code> performs the documented unanchored search on the JVM engine, and an empty filtered run exits non-zero.</li>
            <li><code>elide run &lt;name&gt;</code> follows a total, documented resolution order &mdash; source file, then <code>elide.pkl</code> scripts, then <code>package.json</code>/<code>pyproject.toml</code> scripts, then <code>node_modules/.bin/&lt;name&gt;</code> &mdash; and produces a real diagnostic when nothing matches.</li>
            <li><code>elide build &lt;target&gt;</code> accepts the documented target groups, and <code>elide install --with</code> is applied.</li>
            <li><code>elide classpath</code> errors on an unparseable usage spec instead of silently returning the main compile classpath, and Maven exclusions are applied.</li>
            <li><code>--timeout</code> starts before fast-path dispatch, so it now applies to <code>repl</code>, <code>serve</code>, <code>dev</code>, <code>help</code>, <code>agent</code>, and <code>init</code>.</li>
            <li><code>elide serve</code> defaults to the documented port 8080, <code>kotlinc</code> accepts <code>--max-errors</code>, and a mistyped subcommand produces a clear error.</li>
            <li><code>--no-color</code>, <code>NO_COLOR</code>, and <code>TERM=dumb</code> apply to the help masthead and progress output; a shared terminal check lets <code>elide init &lt; /dev/null</code> exit cleanly; and the REPL reads piped stdin.</li>
            <li>Usage errors have their own exit code, distinct from guest failures, and error color is used only on a real terminal.</li>
            <li><code>process.exit</code> codes are preserved on the inline-snippet path, and top-level <code>-c</code> snippets match CPython <code>argv</code> semantics.</li>
            <li>Retired subcommand names fail gracefully.</li>
            <li>Test discovery never descends into hidden directories, and a failing JavaScript test file prints its failure message.</li>
            <li>Python <code>zoneinfo</code> resolves timezones; constructing any <code>ZoneInfo</code> previously raised.</li>
            <li>A producer failure mid-body on a streamed HTTP response aborts the response instead of hanging the client.</li>
            <li>macOS/arm64: unwind information is preserved for native frames, so an exception thrown through a native frame no longer aborts; the mach exception port no longer leaks into child processes; and the crash handler is async-signal safe.</li>
            <li>Image compression entrypoints return cleanly instead of failing to link at runtime.</li>
            <li><code>elide install</code> no longer recurses into its own post-install step and deadlocks an npm install.</li>
            <li>Diagnostics carry source identity across the native bridge, logging configuration is safe for concurrent readers, and log levels resolve by longest matching prefix.</li>
            <li>IPC socket writes are flushed to the peer, socket files are unlinked on drop, and a listener only unlinks the socket it bound.</li>
            <li>Builds without Python fail on an empty compile classpath instead of producing many "package does not exist" errors.</li>
            <li>The default container base image is pinned.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>The <code>jib</code>, <code>aube</code>, <code>uv</code>, <code>pro</code>, and <code>s3</code> subcommands are permanently retired, along with the telemetry, cloud, sidecar, and licensing subsystems; their documentation is removed across locales. <code>python</code>, <code>javap</code>, <code>jdeps</code>, <code>javadoc</code>, <code>native-image</code>, and <code>manifest</code> are unaffected.</li>
            <li>Distributions no longer include duplicate or unreachable files.</li>
            <li>Kotlin language and API level are now 2.4.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>The Homebrew tap now receives an automatic version bump for each nightly release.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.4</span>
      </span>
      <span class="cl-release-summary">Turns <code>elide test</code> into a single cross-language test runner, adds Java language-server support and <code>pom.xml</code> manifests, and moves dependency installation onto the managed toolchain.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.4">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.4</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.4%2B20260824" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.4+20260824</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>elide test</code> is now one test runner for every language: JavaScript and TypeScript tests are discovered with no configuration (no <code>elide.pkl</code> required) and run alongside JVM tests as one reported run &mdash; one tally, one exit code, one XML report format, one coverage table.</li>
            <li>JUnit console output uses the build display's format.</li>
            <li><code>elide lsp</code> supports Java, with <code>google-java-format</code> integrated.</li>
            <li><code>pom.xml</code> is accepted as a foreign project manifest.</li>
            <li>Elide's own CI now checks Java and Kotlin formatting with <code>elide format</code>.</li>
            <li>The <code>native-image</code> argument vector is recorded beside image outputs.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>TypeScript entry metadata.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Dependency resolution &mdash; including classifier JARs from Maven Central &mdash; moves off the Elide Classic bootstrap and onto the managed toolchain via <code>elide install</code>.</li>
            <li>JVM code can execute inside the parent <code>elide</code> process; opt in with <code>SPAWN_PROCESS=false</code> in native mode.</li>
            <li><code>TextDecoder</code> uses <code>encoding_rs</code>; URL setters work, <code>XMLHttpRequest</code> accepts <code>data:</code> URLs, and <code>fetch()</code> resolves relative URLs.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>Dependency updates across ecosystems include upstream security fixes.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.3</span>
      </span>
      <span class="cl-release-summary">Fixes native-image build cache invalidation and makes native Windows builds work.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.3">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.3</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.3%2B20260818" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.3+20260818</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Native-image task cache keys now fingerprint the contents of configuration inputs, so editing reachability metadata under <code>-H:ConfigurationFileDirectories</code> or regenerating a profile correctly invalidates the cached image; previously only the flag text was tracked.</li>
            <li>Native-image output and configuration paths are relative to the resolved project root, configuration and linker inputs are fingerprinted through symlinks and external paths, and the complete JVM <code>conf</code> tree &mdash; including <code>java.security</code> &mdash; is packaged.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Windows builds work natively: the builder no longer forces container mode on Windows and prefers a resolved native binary, postinstall resolves <code>elide</code> from the <code>PATH</code>, and the docs build script runs on an explicit 32 MiB stack.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.2</span>
      </span>
      <span class="cl-release-summary">Runs Java and Kotlin sources directly, adds the WHATWG legacy text encodings, and repairs JVM build task-graph behavior.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.2">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.2</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.2%2B20260816" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.2+20260816</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Java and Kotlin source files run directly with <code>elide run</code>.</li>
            <li><code>elide run</code> executes scripts declared in <code>elide.pkl</code>, <code>package.json</code>, and <code>pyproject.toml</code>.</li>
            <li>Every legacy encoding in the WHATWG Encoding Standard for <code>TextDecoder</code> &mdash; the single-byte families (<code>windows-125x</code>, <code>iso-8859-*</code>, <code>koi8-r/u</code>, <code>macintosh</code>, and others) and the multi-byte CJK encodings (<code>gbk</code>/<code>gb18030</code>, <code>big5</code>, <code>euc-jp</code>, <code>iso-2022-jp</code>, <code>shift_jis</code>, <code>euc-kr</code>) with spec-correct streaming and error semantics.</li>
            <li>A Spring shorthand for JVM dependency declarations.</li>
            <li>Generic XML test reports.</li>
            <li>Elide itself can be built without Python support via <code>--no-python</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Maven dependency resolution now records the full dependency graph instead of a spanning tree, so shared transitive dependencies resolve correctly in multi-scope projects (for example Spring apps).</li>
            <li>JVM build task-graph fixes: <code>javac</code> targeting prefers <code>--release</code> and falls back to the default release when unset, <code>-parameters</code> is always passed, Kotlin tasks only run when Kotlin sources exist, and run-task resources resolve correctly.</li>
            <li>Worker threads now report their real script path via <code>__filename</code>, <code>__dirname</code>, and <code>process.argv</code>, and an entry module that imports itself resolves to a single module instance by canonical path.</li>
            <li>Ctrl+C now interrupts <code>elide init</code>.</li>
            <li>Arguments after <code>--</code> are forwarded to JVM programs resolved from the project manifest.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Build targets may be named without a prefix.</li>
            <li><code>--no-cache</code> also skips local build state.</li>
            <li>macOS distributions carry all eight executables, and bundled dylibs are ad-hoc signed.</li>
            <li>The documentation site is completely rebuilt.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.1</span>
      </span>
      <span class="cl-release-summary">Implements node:net, node:dgram, and node:child_process, adds Python insights, and improves MCP tooling and CLI error output.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.1">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.1</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.1%2B20260719" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.1+20260719</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>node:net</code>: TCP and Unix-domain sockets and servers with DNS resolution and Happy-Eyeballs dialing, plus <code>BlockList</code> and <code>SocketAddress</code>.</li>
            <li><code>node:dgram</code>: UDP sockets covering unicast, connected, broadcast, and multicast transports with full socket-option support.</li>
            <li><code>node:child_process</code>: the whole spawn family (<code>spawn</code>, <code>exec</code>, <code>execFile</code>, their sync forms) and <code>fork</code> with a working IPC channel, controlled by new <code>--allow-run</code> / <code>--deny-run</code> sandbox flags.</li>
            <li>Python support in watch insight scripts and targets, plus insight throw hooks, error capture, and argument destructuring.</li>
            <li>The error-stack accessor proposal is now enabled for JavaScript.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li><code>node:vm</code> contexts now bind <code>this</code> and <code>globalThis</code> to the sandbox and hide the internal contextify marker; <code>node:buffer</code> populates <code>buffer.constants</code> and validates allocation sizes with coded errors; <code>process.argv[1]</code> and <code>__filename</code> resolve to the real script path.</li>
            <li>Python: crash loading the <code>time</code> module, <code>-m</code> module parameter passing, and buffered stdout/stderr now flushing on exit across all eval paths.</li>
            <li>CLI: plain, parseable error output on non-interactive terminals, and the REPL accepts experimental options on language-probe engines.</li>
            <li>Dependency installation: npm overrides no longer corrupt install data, and <code>package.json</code> parsing handles previously failing edge cases.</li>
            <li>MCP and insights: attach failures are reported, in-flight requests are processed when stdio closes, source-path errors are clearer, and deeply nested values render completely.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>The <code>linux-amd64</code> binary runs on older Linux distributions again.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.4.0</span>
      </span>
      <span class="cl-release-summary">Updates the runtime and adds a large set of JavaScript and Python compatibility fixes.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.4.0">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.4.0</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.4.0" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.4.0</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Broader Node.js compatibility, including <code>node:path</code>, process behavior, <code>node:assert</code>, <code>node:util</code>, <code>node:test</code>, module shims, stream behavior, and worker-thread support.</li>
            <li>An <code>elide python</code> subcommand with CPython-style flag compatibility.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>JavaScript module loading, CommonJS resolution, worker-thread runtime ownership, structured clone and message ports, stream lifecycle behavior, fetch URL resolution, and catchable guest errors for out-of-CWD module failures.</li>
            <li>Embedded native-image operation, embedded JVM staging, Pkl engine isolation, and Python builtins imports.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>NPM platform packages now download the Elide binary during install instead of bundling very large tarballs.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>Updated the runtime and toolchain base, the managed toolchains, and the profile-guided optimization configuration.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.6</span>
      </span>
      <span class="cl-release-summary">Focuses on installers, dependency installation, JVM tool fixes, MCP improvements, Python layout fixes, and JavaScript conformance hooks.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.6">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.6</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.6%2B20260705" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.6+20260705</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Packaged installer support around embedded <code>aube</code> for NPM and <code>uv</code> for PyPI, with unified install smoke coverage.</li>
            <li>Local JAR dependencies for JVM projects.</li>
            <li>MCP insight and debugging tools, including project/build inspection and guest-code execution support.</li>
            <li>JavaScript conformance hooks: global <code>print</code>, plain scriptable error output, and <code>$262</code> host API support for Test262 tooling.</li>
            <li>Web templates for <code>elide init</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>The docs Examples button, by adding the backing code samples page.</li>
            <li><code>elide run</code> for spawned JVM processes that read from stdin.</li>
            <li>MCP HTTP mode and high-level insight scripting behavior.</li>
            <li><code>javaformat</code> and <code>ktfmt</code> helper handling for <code>@argfile</code> arguments.</li>
            <li>Several installer and snippet-runner issues.</li>
            <li>Embedded <code>javac</code> compatibility with ambient <code>CLASSPATH</code> defaults and DocLint reflection behavior.</li>
            <li>Runtime error reporting for module-resolution failures.</li>
            <li>Python home selection.</li>
            <li>Temporary writes, moved into a dedicated process directory that is freed on exit.</li>
            <li>NPM publishing reliability, by freeing disk space and reporting publish errors.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.5</span>
      </span>
      <span class="cl-release-summary">Improves Kotlin and Bazel workflows, adds a fuller Node filesystem implementation, and fixes update and docs behavior.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.5">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.5</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.5%2B20260628" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.5+20260628</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Java ABI output for mixed Kotlin and Java source sets in <code>elide kotlinc --abi-only</code>.</li>
            <li>Bazel-aware Kotlin compiler diagnostics and project-relative source paths.</li>
            <li><code>node:fs</code> and <code>node:fs/promises</code> support with a filesystem capability sandbox.</li>
            <li>A docs "File an issue" action, with fixed mobile layout for page actions.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Explicit <code>elide kotlinc --plugins=&lt;suite&gt;</code> selections now take precedence.</li>
            <li><code>elide upgrade</code> now downloads the full archive, not only the binary, when resources are needed.</li>
            <li>Docs crawler and discovery files, and robots behavior.</li>
            <li>NPM publishing, by moving <code>@elide-dev/elide</code> publishing into a dedicated, testable workflow.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="changed">
          <span class="cl-change-tag">Changed</span>
          <ul class="cl-change-list">
            <li>Disabled <code>telemetry</code>, <code>cloud</code>, and <code>sidecar</code> by default behind optional Cargo features.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.4</span>
      </span>
      <span class="cl-release-summary">Centered on JVM build performance and Kotlin compiler correctness under persistent-worker use.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.4">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.4</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.4%2B20260623" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.4+20260623</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Kotlin Build Tools API work for Elide JVM builds.</li>
            <li>Pro i18n support.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Kotlin incremental compilation behavior, with digest-driven invalidation, heap sizing, and classpath-default handling.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="chore">
          <span class="cl-change-tag">Maintenance</span>
          <ul class="cl-change-list">
            <li>Cached warm <code>javac</code> classpath state in persistent workers to reduce repeated classpath indexing.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.3</span>
      </span>
      <span class="cl-release-summary">Adds Python 3.12 and native compression work, expands NPM distribution infrastructure, and fixes several JVM build and transport issues.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.3">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.3</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.3%2B20260621" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.3+20260621</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>Python interop, Python 3.12 alignment, and <code>sys.argv</code> fixes.</li>
            <li>Native compression for gzip, Brotli, and Zstandard, replacing <code>zstd-jni</code> and <code>brotli4j</code> in the transport path.</li>
            <li>NPM distribution infrastructure for Elide binary packages.</li>
            <li>Publishing infrastructure for <code>@elide-dev/types</code>.</li>
            <li>Roll-up behavior for excessive Kotlin compiler diagnostics.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Python cold start.</li>
            <li>Updated dependencies to address open security alerts.</li>
            <li>zstd JNI class registration on the dynamic dylib path.</li>
            <li>Native-image task output path semantics.</li>
            <li>Kotlin stdlib inclusion when Kotlin sources are present.</li>
            <li>Kotlin compiler API and language-version argument capture.</li>
            <li>Build-cache fingerprint corruption after cache restore.</li>
            <li>External native-image driver selection.</li>
            <li>JVM codegen, so build and version config stay in sync.</li>
            <li>Build-cache file attribute preservation.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.2</span>
      </span>
      <span class="cl-release-summary">Improves CLI version reporting and upgrade behavior, fixes Windows installer packaging, and closes Python and native-image resource gaps.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.2">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.2</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.2%2B20260616" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.2+20260616</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li>The Elide masthead in <code>elide info</code>.</li>
            <li>Channel and precise-version awareness to <code>elide --version</code> and <code>elide info</code>.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Made <code>elide upgrade</code> channel-aware and cleaned up user-facing upgrade output.</li>
            <li>musl and LTO builds, by restoring Rust memory intrinsics via <code>compiler-builtins-mem</code>.</li>
            <li>License registration pages to use <code>elide pro activate</code>.</li>
            <li>The Windows installer, now syncing the staged Elide home instead of relying on stale hand-enumerated file paths.</li>
            <li>Python stdlib version resolution from the on-disk Python home layout.</li>
            <li>Native-image <code>jdeps</code> resource bundle inclusion for used-dependency reports.</li>
            <li>Docs for multiplex persistent-worker support.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.1</span>
      </span>
      <span class="cl-release-summary">Adds <code>jdeps</code>, improves JS crypto support, and fixes Kotlin, Bazel, and formatter regressions.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.1">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.1</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.1%2B20260614" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.1+20260614</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>elide jdeps</code>.</li>
            <li><code>node:crypto</code>, Web Crypto digest behavior, and transparent tool passthrough.</li>
            <li>Reference and guide docs for remaining runtime and tooling topics.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Automatic recovery from corrupt Kotlin incremental-compile caches.</li>
            <li>Bazel flags.</li>
            <li>Formatter check-mode output and Kotlin source counting.</li>
            <li>Generated Java projects, so they no longer include Kotlin dependencies.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading">
        <span class="cl-release-version" role="heading" aria-level="3">1.3.0</span>
      </span>
      <span class="cl-release-summary">Early installer, project-template, and native-image fixes from the reviewed PR range.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide 1.3.0">
        <a class="changelog-release-link" href="https://elide.help/docs/releases">
          <span class="changelog-release-link-label">Release notes</span>
          <code>1.3.0</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.3.0%2B20260613" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.3.0+20260613</code>
        </a>
      </div>
      <div class="cl-changes">
        <section class="cl-change" data-kind="added">
          <span class="cl-change-tag">Added</span>
          <ul class="cl-change-list">
            <li><code>elide init</code> template and metadata improvements, including inverted blocks, binary files, and conditional <code>build</code>/<code>test</code>/<code>run</code> invocation support.</li>
          </ul>
        </section>
        <section class="cl-change" data-kind="fixed">
          <span class="cl-change-tag">Fixed</span>
          <ul class="cl-change-list">
            <li>Installer script argument parsing and Unix executable permissions.</li>
            <li>Native-image localization configuration for ICU.</li>
            <li>Missing annotations for Java test compilations.</li>
            <li>A build-time <code>nanoTime</code> value that caused instant timeout behavior.</li>
          </ul>
        </section>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading cl-release-heading-label">
        <span class="cl-release-version" role="heading" aria-level="3">1.0.x &ndash; 1.2.x</span>
      </span>
      <span class="cl-release-summary">Early prerelease lines, archived for reference. They should not be used for new projects.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links changelog-release-links-wide" aria-label="Release links for Elide prereleases">
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.2.0%2B20260612" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.2.0+20260612</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.1.0%2B20260430" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.1.0+20260430</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.0.0-beta10" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.0.0-beta10</code>
        </a>
      </div>
    </div>
  </details>

  <details class="cl-release">
    <summary class="cl-release-header">
      <span class="cl-release-heading cl-release-heading-label">
        <span class="cl-release-version" role="heading" aria-level="3">Elide Classic</span>
      </span>
      <span class="cl-release-summary">The pre-1.0 code line preserved on the <code>v5</code> branch, useful mainly for understanding older projects pinned to it.</span>
    </summary>
    <div class="cl-release-body">
      <div class="changelog-release-links" aria-label="Release links for Elide Classic">
        <a class="changelog-release-link" href="https://github.com/elide-dev/elide/tree/v5" target="_blank" rel="noopener noreferrer">
          <span class="changelog-release-link-label">Classic branch</span>
          <code>v5</code>
        </a>
        <a class="changelog-release-link changelog-release-link-github" href="https://github.com/elide-dev/elide/releases/tag/1.0.0-beta10" target="_blank" rel="noopener noreferrer">
          <span class="changelog-github-icon"></span>
          <span class="changelog-release-link-label">GitHub</span>
          <code>1.0.0-beta10</code>
        </a>
      </div>
      <p class="cl-classic-note">Classic used beta and release-candidate versions such as <code>1.0.0-beta11-rc6</code>. Treat it as historical unless you are maintaining an existing project on that branch.</p>
    </div>
  </details>

</div>

<div class="border-t border-border/40 my-12"></div>

## About This Page

This page is curated from recent merged changes, plus public release tags on
[`elide-dev/elide`](https://github.com/elide-dev/elide/releases).
Dependency-only, CI-only, and test-only changes are omitted unless they affect
installation, security, packaging, or runtime behavior. Version grouping uses
release milestones where they are set and the public nightly release line
otherwise.

---

# Releases

URL: https://elide.help/docs/releases

> Update Elide with `elide upgrade`, install a specific release or nightly build, and pin a project to an Elide version with `elide use` and `.elideversion`.

Changes are in the [Changelog](https://elide.help/docs/changelog); artifacts, checksums, and dated tags are on
[GitHub Releases](https://github.com/elide-dev/elide/releases).

OpenRewrite integration is experimental in 1.6.0. See [the changelog overview](https://elide.help/docs/changelog#story-openrewrite)
and [the OpenRewrite guide](https://elide.help/docs/toolchain/jvm/rewrite);
recipe compatibility hardening is planned for a later release. The experimental
[dependency code index](https://elide.help/docs/toolchain/jvm/code-index) is also available for type and reference queries.

## Next release: 1.6.3

The [1.6.3 feature overview](https://elide.help/docs/changelog#inside-elide-1-6-3) covers the release in development:

- Android APKs, AAR libraries, and app bundles, with an Android template and opt-in [Compose compiler](https://elide.help/docs/toolchain/jvm/kotlinc#compose).
- [Micronaut applications](https://elide.help/docs/toolchain/jvm/micronaut): Java annotation processing, Pkl application configuration, JUnit tests, and JVM or native packaging.
- [Shared test containers](https://elide.help/docs/toolchain/testing#shared-test-containers): disposable services shared by JavaScript, TypeScript, and JUnit tests.
- [Python packages and isolated console tools](https://elide.help/docs/python-packages): project environments and `elide uv tool run`.
- [Maven version overrides](https://elide.help/docs/toolchain/dependencies#maven-version-resolutions): select exact versions throughout a dependency graph.
- [Build and test telemetry](https://elide.help/docs/opentelemetry/runtime#enable-build-reports): correlate tasks, cache results, and test outcomes in an OTLP collector.
- [Pkl rendering](https://elide.help/docs/pkl-configuration) and [terminal Markdown](https://elide.help/docs/terminal-markdown): generate configuration or read documentation without a project.

These features require a 1.6.3 development build. The latest released version remains 1.6.2.

## Latest release: 1.6.2

The [1.6.2 feature overview](https://elide.help/docs/changelog#inside-elide-1-6-2) describes the latest release:

- [JavaScript and TypeScript build extensions](https://elide.help/docs/toolchain/build-extensions): cached tasks, packaged extensions,
  and in-process JVM tools.
- [Embedded C compiler and linker via LLVM](https://elide.help/docs/toolchain/native/cc): host object and LLVM IR output, plus in-memory
  compilation, linking, and invocation through ORC LLJIT.
- [jextract](https://elide.help/docs/toolchain/native/jextract) and [C header bindings in Java compilation](https://elide.help/docs/toolchain/jvm/javac#c-header-bindings):
  standalone Java FFM generation, in-memory javac integration, named Pkl groups, and generated-source export.
- [Environment and properties](https://elide.help/docs/environment): automatic base/local files, explicit file lists, precedence,
  dotenvx-compatible encrypted values, and invocation-scoped configuration.
- [Java ABI jars](https://elide.help/docs/toolchain/jvm/javac#abi-jars), [Kotlin ABI compilation](https://elide.help/docs/toolchain/jvm/kotlinc#abi-jars),
  and [dependency-aware jfmt formatting](https://elide.help/docs/toolchain/jvm/formatting#resolve-and-rewrite-imports).

Native tools are included on macOS arm64 and dynamically linked Linux amd64/arm64. Windows and fully static
distributions retain their existing JVM tools; see the native-tools guides for the exact capabilities.

Download [Elide 1.6.2](https://github.com/elide-dev/elide/releases/tag/v1.6.2), or use a full dated tag from
GitHub Releases when pinning a nightly build. The [1.6.0 feature narrative](https://elide.help/docs/changelog#release-story)
and benchmark evidence remain available below the 1.6.2 overview.

## Update Elide

```bash
elide upgrade                    # update to the latest build on your channel
elide upgrade --check            # check without updating
elide upgrade --channel release  # channels: release, nightly
```

Update a package-manager install through that package manager.

## Install a specific build

```bash
curl -sSL --tlsv1.2 elide.sh | bash -s -- --install-rev=VERSION
```

For a reproducible nightly, pass a full dated tag from GitHub Releases.

## Pin a project to a version

```bash
elide use 1.6.2
```

This writes `.elideversion` and installs that version; every `elide` run in the project then uses it.

| Flag | Effect |
| --- | --- |
| `elide use --no-install` | Write `.elideversion` only. |
| `elide use --channel <channel>` | Download from `release` or `nightly`. |
| `--use-version <version>` | Run an installed version for one invocation. |
| `--ignore-version` | Run the current binary, ignoring `.elideversion`. |