CLI Reference

The Elara compiler provides a command-line interface for building and running Elara programs.

Installation

Build the compiler from source:

cd elara
cabal build
cabal install

Verify installation:

elara --version

Commands

`elara build`

Compile an Elara program to JVM bytecode without running it.

elara build <MAIN_FILE> [OPTIONS]

MAIN_FILE

string

required

Path to the main Elara source file to compile. Must contain a Main module with a main : IO () function.

Options

--dump

string

default:""

Comma-separated list of intermediate compilation stages to dump to files.Valid values:

lexed - Lexer output (tokens)
parsed - Frontend AST
desugared - Desugared AST
renamed - Renamed AST
shunted - Shunted AST (after operator precedence)
typed - Typed AST
core - Core IR (and ANF, closure-lifted variants)
ir - JVM IR
jvm - JVM bytecode disassembly

Example: --dump=core,jvmEnvironment variable: ELARA_DUMP

--source-dirs

string

default:"[]"

Comma-separated list of directories to search for source files.Example: --source-dirs=lib,srcEnvironment variable: ELARA_SOURCE_DIRS

Examples

elara build Main.elara

Output

Compiled class files are written to the build/ directory:

$ elara build Main.elara
[INFO] Compiled Main to ["build/Main.class"]!
[INFO] Successfully compiled 1 source files in 45.23ms!

build/
└── Main.class

`elara run`

Compile and execute an Elara program.

elara run <MAIN_FILE> [OPTIONS] [-- PROGRAM_ARGS...]

MAIN_FILE

string

required

Path to the main Elara source file to run.

PROGRAM_ARGS

string[]

Arguments to pass to the program being run (after --).

Options

--target

string

default:"interp"

Execution target. Determines how the program runs.Valid values:

interp - Run using the Core interpreter (fast compilation, slower execution)
jvm - Compile to JVM bytecode and run (slower compilation, faster execution)

Example: --target=jvm

--dump

string

default:""

Same as elara build --dump.

--source-dirs

string

default:"[]"

Same as elara build --source-dirs.

Examples

elara run Main.elara

Output

Interpreter
JVM

$ elara run examples/Hello.elara
[INFO] Successfully ran 1 source files in 32.15ms!
Hello, World!

The interpreter executes Core IR directly without generating JVM bytecode.

$ elara run examples/Hello.elara --target=jvm
[INFO] Compiled Main to ["build/Main.class"]!
[INFO] Successfully ran 1 source files in 78.42ms!
Hello, World!

JVM target compiles to bytecode first, then executes via java.

Global Options

These options work with all commands:

--help

flag

Display help information and exit.

elara --help
elara build --help
elara run --help

--version

flag

Display compiler version and exit.

elara --version

Environment Variables

ELARA_DUMP

string

default:""

Same as --dump flag. Command-line flags override environment variables.

export ELARA_DUMP=core,jvm
elara build Main.elara

ELARA_SOURCE_DIRS

string

default:""

Same as --source-dirs flag. Command-line flags override environment variables.

export ELARA_SOURCE_DIRS=lib,stdlib
elara build Main.elara

ELARA_DEBUG

boolean

default:"false"

Enable debug logging. Set to 1 or true to enable.

export ELARA_DEBUG=1
elara build Main.elara

ELARA_LOG_LEVEL

string

default:"info"

Set minimum log level.Valid values: debug, info, warning, error

export ELARA_LOG_LEVEL=debug
elara build Main.elara

Configuration Files

Elara supports YAML configuration files for project settings.

Location

The compiler searches for configuration in this order:

./elara.yaml (current directory)
./elara.yml
~/.config/elara/config.yaml

Format

elara.yaml

# Compilation options
dump:
  - core
  - jvm

sourceDirs:
  - lib
  - stdlib
  - src

# Runtime options
target: jvm

Command-line flags override configuration file settings, which override environment variables.

Dump Targets Reference

Each dump target writes intermediate compilation artifacts to the build/ directory.

lexed

File: build/<module>.lexed.elrContent: Token stream with layout rules applied

DEF IDENTIFIER("main") COLON IDENTIFIER("IO") ...

parsed

File: build/<module>.parsed.elrContent: Frontend AST (directly mirrors source syntax)

Module
  { name = Main
  , declarations =
      [ ValueDeclaration { name = "main", ... }
      ]
  }

desugared

File: build/<module>.desugared.elrContent: Desugared AST (multi-arg lambdas curried, let params removed)

ValueDeclaration
  { name = "main"
  , value = Lambda "x" (Lambda "y" ...)
  }

renamed

File: build/<module>.renamed.elrContent: Renamed AST (all names fully qualified and unique)

ValueDeclaration
  { name = Main.main
  , value = App (Elara.Prelude.print) ...
  }

shunted

File: build/<module>.shunted.elrContent: Shunted AST (operators in prefix form, precedence applied)

App (App (Var "+") (Var "x")) (Var "y")

typed

File: build/<module>.typed.elrContent: Typed AST (every expression annotated with its type)

ValueDeclaration
  { name = Main.main
  , type' = IO ()
  , value = App @(String -> IO ()) @String ...
  }

core

Files:

build/<module>.core.elr - Initial Core IR
build/<module>.core.anf.elr - A-Normal Form
build/<module>.core.closure_lifted.elr - After closure lifting
build/<module>.core.final.elr - Final optimized Core

Content: Simplified lambda calculus with 8 constructors

Let main (Lam () (App (Var print) (Lit "Hello")))

File: build/<module>.jvm.ir.elrContent: JVM intermediate representation (before bytecode)

public class Main {
  public static Object main() {
    return Prelude.print("Hello");
  }
}

jvm

File: build/<module>.classfile.txtContent: JVM bytecode disassembly

public class Main {
  public static java.lang.Object main();
    Code:
       0: ldc           #2
       2: invokestatic  #3
       5: areturn
}

Exit Codes

success

Compilation/execution succeeded

error

Compilation or runtime error occurred

error

Invalid command-line arguments

Logging

The compiler writes logs to:

Standard output - Colored, formatted output
elara.log - Plain text log file in current directory

Log Format

[INFO] Successfully compiled 3 source files in 125.45ms!
[WARNING] Unused variable 'x' at Main.elara:15:9
[ERROR] Type mismatch at Main.elara:20:5

Controlling Log Output

Set Log Level

export ELARA_LOG_LEVEL=debug
elara build Main.elara

Disable Colors

NO_COLOR=1 elara build Main.elara

Redirect to File

elara build Main.elara 2>&1 | tee output.log

Examples

Basic Workflow

Create a Program

Main.elara

def main : IO ()
let main = print "Hello, Elara!"

Build It

elara build Main.elara

Run It

java -cp build:jvm-stdlib Main

Or use elara run:

elara run Main.elara --target=jvm

Debug Compilation Issues

Enable Debug Logging

export ELARA_DEBUG=1

Dump Intermediate Stages

elara build Main.elara --dump=parsed,renamed,typed,core

Inspect Output

ls build/
# Main.parsed.elr  Main.renamed.elr  Main.typed.elr  Main.core.elr

cat build/Main.typed.elr

Multi-Module Project

project/
├── Main.elara
├── lib/
│   ├── Utils.elara
│   └── Types.elara
└── elara.yaml

elara.yaml

sourceDirs:
  - lib

elara build Main.elara
# Automatically finds modules in lib/

Troubleshooting

Module not found

Error:

[ERROR] Module 'Foo' not found

Solution:

Check that the module file exists

Add the directory to --source-dirs:

elara build Main.elara --source-dirs=lib

Verify the module name matches the file name

Java heap space error

Error:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

Solution: Increase JVM heap size:

export JAVA_OPTS="-Xmx2G"
java -cp build:jvm-stdlib Main

Class not found at runtime

Error:

Error: Could not find or load main class Main

Solution: Ensure both build/ and jvm-stdlib/ are in classpath:

java -cp build:jvm-stdlib Main

Permission denied

Error:

elara: build/Main.class: permission denied

Solution:

chmod +w build/
elara build Main.elara

Compiler Architecture

Learn about the compiler’s internal design

Compilation Pipeline

Understand the 9 compilation stages

Get Started

Language Guide

Standard Library

Compiler

Examples

CLI Reference

Installation

Commands

`elara build`

Options

Examples

Output

`elara run`

Options

Examples

Output

Global Options

Environment Variables

Configuration Files

Location

Format

Dump Targets Reference

Exit Codes

Logging

Log Format

Controlling Log Output

Examples

Basic Workflow

Debug Compilation Issues

Multi-Module Project

Troubleshooting

Compiler Architecture

Compilation Pipeline

Build docs developers (and LLMs) love

Get Started

Language Guide

Standard Library

Compiler

Examples

​Installation

​Commands

​elara build

​Options

​Examples

​Output

​elara run

​Options

​Examples

​Output

​Global Options

​Environment Variables

​Configuration Files

​Location

​Format

​Dump Targets Reference

​Exit Codes

​Logging

​Log Format

​Controlling Log Output

​Examples

​Basic Workflow

​Debug Compilation Issues

​Multi-Module Project

​Troubleshooting

​Related Pages

Compiler Architecture

Compilation Pipeline

Build docs developers (and LLMs) love

Installation

Commands

`elara build`

Options

Examples

Output

`elara run`

Options

Examples

Output

Global Options

Environment Variables

Configuration Files

Location

Format

Dump Targets Reference

Exit Codes

Logging

Log Format

Controlling Log Output

Examples

Basic Workflow

Debug Compilation Issues

Multi-Module Project

Troubleshooting

Related Pages