# CLI reference

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