CLI Reference — Elide Docs

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.

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

`serve` (alias `start`)

Serve a directory as static files, or a script that exports a fetch handler (Development Server).

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.

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.

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.

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

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

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

elide java -- -jar app.jar

`javac`

Compile Java, like javac. See Java Compiler.

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.

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.

Setup and tooling

elide agent prints guidance for coding agents; see Elide for AI 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). 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.

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:

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.

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.

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.

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.

`web`

Web tooling: elide web build app.ts page.md --out dist builds files without a manifest. See Web Toolchain.

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).
`-V, --version`	Print the version.

Sandbox flags

Guest code runs unconfined until a sandbox flag is given. See 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`, Debugging).
`--debugger-host HOST` / `--debugger-port PORT`	Debugger bind address.
`--profiler[=PROFILER]`	`cputracing`, `cpusampling`, or `memtracing`.
`--coverage[=auto]`	Collect coverage.
`--insights INSIGHTS`	Inject 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).
`--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 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.

Run and develop

run

serve (alias start)

dev

install

repl

python