CLI Reference

Run elide --help for the everyday command list and elide --help-all for advanced commands and flags. Every subcommand also supports --help, and elide help <command> prints that command’s section of this page.

Run and develop

run

Run a source file, a named script, or the project entrypoint. JavaScript, TypeScript, JSX, TSX, and Python run as guest code; .java and .kt files compile and run on the JVM.

elide run app.ts
elide run app.js -- --port 3000
elide run -s 'console.log("hi")'

Script arguments follow --. A name that is not a file on disk resolves as a named script, and a bare elide run uses the project entrypoint; see Elide for AI Agents for the resolution order in full.

python

Run Python with a CPython-shaped command line: every token after the script is a program argument, so no -- separator is needed.

elide python script.py --flag-for-the-script
elide python -c 'print(1)'

-c CMD runs a program passed as a string, and -s leaves the user site directory off sys.path.

serve

Serve static files over HTTP. Defaults to 127.0.0.1:8080, with or without a terminal attached; --host and --port override that, and --no-tui replaces the dashboard with plain logs.

elide serve ./public
elide serve --no-tui --port 3000 ./dist

dev

Serve a directory or script with file watching and live reload. Defaults to 127.0.0.1:3000. --no-tui selects plain logs, --no-watch disables watching.

elide dev ./public
elide dev --no-tui ./public

adopt

Launch an AI coding harness to migrate the project in the current directory to Elide. With no flags, the command interactively asks for a build strategy, harness, and approval mode. See Adopt Elide in an existing project for the workflow and safety guidance.

The selected harness receives the absolute current directory and tailored migration advice. In automatic modes, Elide displays progress and writes harness output to the temporary log path printed at startup. It exits unsuccessfully if the harness does; Ctrl+C aborts adoption with status 130 and keeps the log for review.

$ elide adopt
$ elide adopt --build elide --harness codex --approval auto-approve
$ elide adopt --log
$ elide adopt --build elide --harness codex --approval auto-approve --non-interactive

Supplying a choice flag without --non-interactive preselects that answer and leaves any omitted choices interactive. In non-interactive mode, pass all of --build, --harness, and --approval; use auto-approve or yolo because manual-approve requires a live harness session.

install

Install project dependencies. Maven is the only ecosystem installed by default; npm is opt-in.

elide install
elide install --ecosystems=npm
elide install --workspace
elide install --with=sources

An ecosystem the project declares but the run skips is named on stderr under --verbose, and asking for an ecosystem this build cannot serve is a usage error.

repl

Start the interactive REPL. Also entered by a bare elide with no script and a terminal attached.

Build and test

build

Assemble the artifacts declared by an elide.pkl manifest. Bare tokens name targets, and a leading : is optional; deps, compile and test select a whole task group.

elide build
elide build --inspect
elide build deps compile

--inspect lists the project’s real task names, --no-cache disables the build cache for one run, and --offline avoids fetching remote resources. Anything after -- reaches the underlying subprocess unchanged.

test

Discover and run tests. JavaScript and TypeScript tests are found without configuration; JVM tests need a test source set declared in elide.pkl. Bare tokens narrow the run to the paths they name.

elide test
elide test src/api
elide test -t 'parses .+ headers'
elide test --coverage --bail=3

--timeout is the global flag bounding the whole invocation; --test-timeout is the per-test one. A bare --debugger attaches to guest and JVM tests both; a named mode selects the guest engine alone, and a JDWP address the JVM engine alone — so an address debugs nothing in a project without JVM tests. See the Debugging guide.

format (alias fmt)

Format Java and Kotlin sources. Files and directories, and every formatter-specific flag, follow --; directory arguments are expanded and both languages are formatted in one pass.

elide format -- src
elide format --list-files -- --dry-run src

Write mode is the default. A check-mode run (--dry-run) exits 1 on its own when a file would change — --set-exit-if-changed is accepted for drop-in parity but not required, and there is no --check. --list-files names the offending files and belongs before --; --list-diffs[=N] prints a unified diff for each.

project

Interrogate an Elide project.

Setup and integration

elide agent rounds this group out with agent-oriented guidance, diagnostics, and a bug-report body; see Elide for AI Agents.

init

Create a project from a bundled template. With no flags it opens a TUI editor.

elide init --templates
elide init --templates --json
elide init --plain --skip-defaults --skip-run --template java

info

Show binary, platform, and language information. --cargo-lockfile prints the embedded lockfile instead.

upgrade

Check for and apply updates. --check reports without applying, --force updates even when current, and --channel selects release, preview, or nightly.

use

Write a project .elideversion pin and download that version.

elide use 1.5.0
elide use --no-install 1.5.0

--no-install writes the pin without downloading. Pass --ignore-version on a later invocation to run the installed binary anyway.

help

Read the documentation embedded in the binary. A command name prints that command’s section of this page; a slug or page title prints the whole page.

elide help
elide help run --format=markdown
elide help sandbox --lang=fr

--format selects auto, interactive, or markdown; a non-interactive caller gets Markdown without asking. -w, --width bounds the rendered width and --languages lists the languages the binary carries.

lsp

Start a Language Server Protocol instance over stdio. Only the Java server is registered today, so a bare elide lsp selects it.

mcp

Start a Model Context Protocol instance. --mode selects stdio (the default) or http, which binds localhost:8125 unless --host and --port say otherwise.

JVM tools

Elide embeds java, javac, kotlinc, jar, javadoc, javap, jdeps, javaformat, ktfmt, mvn, and native-image. Tool arguments follow --, and compiler diagnostics pass through verbatim:

elide javac -- -d target Main.java

Setup and integration

classpath

Print a resolved classpath. A usage is [<sourceSet>:]<usage>, lowercase, with usage one of toolchain, processor, compile, modules, runtime, or provided; the default is main:compile.

elide classpath
elide classpath test:runtime

An unrecognized spec, or one naming a usage that does not exist, is a usage error rather than empty output.

manifest

Print the resolved project manifest as JSON on stdout, with no ANSI. Do not pass --quiet: it silences the output entirely.

Global options

Common global flags include:

See Filesystem Sandbox for capability examples.

Transport v2 uses Rustls/AWS-LC TLS and native payload storage. It requires a build with the v2 native library. Datagram channels, CONNECT TLS proxies, and disabling certificate verification are not supported on this experimental path. It is not yet a performance recommendation; existing Netty native transports remain the default. ELIDE_TRANSPORT_V2=1 (true/yes/on, case-insensitive) selects v2 without the flag; it is an explicit selection, so an unavailable v2 library fails the same way --transport=v2 does, with no fallback to v1. See Runtime Environment Variables.

Instruments

Native monitoring flags are hidden from everyday help. Use elide help instruments, elide --help-instruments, or elide --help-all to list them. Captures are opt-in; the flags configure the native VM and are not passed to guest programs.

Each value accepts either --flag=value or --flag value. Paths must be nonempty. --jfr-settings defaults to profile; JFR filenames and settings cannot contain commas or double quotes because the VM uses a comma-delimited option grammar. Mixing an alias with conflicting JVM capture options is rejected.

JVM option equivalents

The boolean heap-dump VM options also accept the -XX:- disabling form. --heap-dump is Elide’s exit-time capture facility; it has no equivalent DumpHeapAndExit spelling. Other -XX: options are forwarded to Native Image, which rejects unknown or unsupported options for the current build and platform. This does not imply support for every HotSpot option. Arguments after -- (or after -m MODULE) belong to the guest program and are not forwarded to the VM. The launcher still handles -XX:MaxHeapSize and -Xmx specially as heap address-space reservation settings, rather than forwarding them to Native Image.

elide --jfr=run.jfr --heap-dump=heap.hprof run app.js
elide -XX:StartFlightRecording=filename=run.jfr,settings=profile,dumponexit=true run app.js
jfr summary run.jfr
visualvm --openfile heap.hprof

Elide lifecycle events

Recordings include these Elide events, with stack traces disabled by default:

Events are grouped under Elide / Runtime, Elide / Guest, Elide / HTTP, and Elide / Transport. Guest pairs share an executionId; HTTP pairs share a requestId. HTTP and TLS/copy events carry a physical channelId; TLS/copy and batch events also identify the driver. IDs are local to one managed runtime, not distributed trace IDs. Terminal events retain their own metadata so they can be enabled independently. A recording started mid-operation does not reconstruct its missing start. URLs, headers, and payloads are not captured. HTTP status is a snapshot at termination; an aborted exchange does not wait for a pending header write to settle or revise its event if that write later succeeds.

jfr print --events 'dev.elide.*' run.jfr

Scope, platforms, and capture lifecycle

Options apply to native run invocations and explicit scripts, snippets, or modules. Place them before guest arguments introduced by -- or -m module. In JVM mode, pass JVM-supported monitoring options to the hosting Java process before startup; the native launcher’s instrument flags cannot configure an already-running JVM. Normal exit finalizes JFR and the requested exit-time heap dump before engine teardown. Finalization failures produce a nonzero exit status without replacing an existing workload failure. SIGKILL and hard timeouts cannot finalize captures.

On Linux and macOS, use jcmd <pid> help for live controls such as JFR.start, JFR.dump, GC.heap_dump, and Thread.print. JMX server and native memory tracking remain disabled. Heap dumps describe the managed VM heap, not all native allocations.

Jitdump support ships only in Linux PGO release builds; other builds omit the capability. GraalVM can warn and continue if jitdump initialization or writing fails, so a zero workload exit status is not proof of a valid capture. Keep the dump directory until perf inject -j completes and check the symbolized report. Jitdump is Linux perf metadata, not a JFR recording.

See Monitoring and Profiling for capture recipes, file inspection, live diagnostics, tool setup, and verification commands. Get the readers from GraalVM JDK downloads (jfr and jcmd) and VisualVM downloads (heap dumps).

Exit codes

For machine-oriented usage, see Elide for AI Agents.