# CLI Reference

> Every Elide command, global option, exit code, and output-stream rule.

`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: [Elide for AI Agents](https://elide.help/docs/agents).

```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`, or `python`. |
| `--contexts=<N\|auto>` | Application contexts to prespawn; `auto` sizes from physical cores. Default `1`. |
| `--debugger[=MODE\|ADDRESS]` | Attach a debugger: `auto`, `cdp`, `dap`, or a JDWP address (`5005`, `host:5005`). |
| `--debugger-host HOST` | Debugger bind host. Default `127.0.0.1`. |
| `--debugger-port PORT` | Debugger port. Default `4711` (DAP) or `1337` (CDP). |
| `--profiler[=PROFILER]` | Profile: `cputracing`, `cpusampling`, or `memtracing`. |
| `--coverage[=auto]` | Collect coverage. |
| `--insights INSIGHTS` | Inject [Insight](https://elide.help/docs/api-insight) scripts. |

### `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 file watching and live reload.

| Flag | Effect |
| --- | --- |
| `--host HOST` | Bind host. Default `127.0.0.1`. |
| `--port PORT` | Bind port. Default `3000`. |
| `--contexts=<N\|auto>` | Application contexts to prespawn, as for `run`. |
| `--no-tui` | Plain log output instead of the dashboard. |
| `--no-watch` | Disable file watching. |
| `-- SCRIPT_ARGS` | Arguments for the script. |

### `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` | Re-download everything, refreshing 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 first with [`setup`](#setup).

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

## Build and test

### `build`

Build what `elide.pkl` declares. Bare tokens name tasks (`deps`, `compile`, `test`, `clean`; leading `:` optional).
Arguments after `--` are passed 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, limited to any paths given. JVM tests need a test source set in `elide.pkl`.

| Flag | Effect |
| --- | --- |
| `-t, --test-name-pattern REGEX` | Run tests whose name matches. |
| `--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. |

`--dry-run` (after `--`) checks without writing and 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. |

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

`<artifactId>` is the project name. `<groupId>` is the workspace root's name, or the project name
outside a workspace. `<version>` is the manifest's, or `0.0.0`. A workspace root lists members as
`<modules>`; members name it as `<parent>`.

| Manifest | Maven scope |
| --- | --- |
| `packages`, `modules` | `compile` |
| `compileOnly`, `devPackages`, `processors` | `provided` |
| `runtimeOnly` | `runtime` |
| `testPackages` | `test` |

Sibling projects become coordinate dependencies; local JARs become `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`); run `elide install` first. The
[IntelliJ IDEA plugin](https://elide.help/docs/intellij) imports this model.

## JVM toolchain

Elide bundles JDK 25 and Kotlin. Tool arguments follow `--`; Elide's flags go before 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 output uses (Bazel strict-deps). |
| `--persistent_worker` | Run as a Bazel persistent worker. |
| `--classpath-cache` | Reuse classpath state across worker compilations. Worker only. |
| `--capabilities` | Print compiler capabilities as JSON. |

### `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`. |
| `--metro` / `--no-metro` | Force the Metro DI plugin on or off. |
| `--tests` | Enable test plugins (power-assert). |
| `--abi-only` | Emit only an ABI (header) JAR to `-d`. |
| `--max-errors N` | Show at most N distinct errors; `0` shows all. |
| `--report-used-deps PATH` | Write the classpath entries the output uses (Bazel strict-deps). |
| `--persistent_worker` | Run as a Bazel persistent worker. |

### `jar`

Build JARs, like `jar`. See [JAR Packaging](https://elide.help/docs/toolchain/jvm/jar).

## Setup and tooling

`elide agent` prints guidance for coding agents; see [Elide for AI Agents](https://elide.help/docs/agents).

### `init`

Create a project from a template. With no flags, opens an editor.

Templates: `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 to Elide with an AI coding harness ([Adopt Elide](https://elide.help/docs/toolchain/usage/adopt)). With no flags, it
asks for each choice. Ctrl+C exits `130` and keeps the log.

| 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;
`options` lists every flag.

<img src="https://elide.help/assets/demos/help.gif" alt="elide help — the complete manual, available offline" width="1310" height="910" 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.

### `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` upgrades Elide first if it is behind the channel; `elide upgrade` keeps installed components.
Package manager installs (Homebrew, apt, RPM, MSI, nix, snap) are refused; 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.

### `mcp`

Start a Model Context Protocol server. See [MCP](https://elide.help/docs/mcp).

| Flag | Effect |
| --- | --- |
| `--mode MODE` | `stdio` (default) or `http`. |
| `--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. |

### `javadoc`

Generate Javadoc, like `javadoc`. Arguments follow `--`.

| Flag | Effect |
| --- | --- |
| `--theme THEME` | `default` or `elide`. |

### `javaformat`

Format Java with google-java-format. Arguments follow `--`. See [Formatting](https://elide.help/docs/toolchain/jvm/formatting).

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

### `javap`

Disassemble JVM bytecode, like `javap`. Arguments follow `--`.

### `jdeps`

Analyze JVM class dependencies, like `jdeps`. Arguments follow `--`.

### `ktfmt`

Format Kotlin with ktfmt. Arguments follow `--`.

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

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

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

### Sandbox flags

Guest code runs unconfined until a sandbox flag is given. 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]` | Attach a debugger ([`run`](#run), [Debugging](https://elide.help/docs/debugging)). |
| `--debugger-host HOST` / `--debugger-port PORT` | Debugger bind address. |
| `--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`. |
| `-X, --vm KEY=VALUE` | Set a VM property. |
| `--safe-close` | Shut down fully even for one-shot runs. |
| `--pkgst` / `--no-pkgst` | Use, or skip, the Pkgst package proxies for `elide install`. |
| `--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` | Skip the first line of the script. |
| `-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. |

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