Environment and properties

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.

Load configuration

Create .env in the directory where you invoke Elide:

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

Create app.ts:

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

elide run app.ts

Hello from greeter
8080

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

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, 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:

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.

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.

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.

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.

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.

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

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:

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

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:

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

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

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:

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. For flag details, see CLI reference.