CLI Reference

The Klar compiler provides several commands for running, building, and analyzing programs.

Usage

klar <command> [options]

Commands

init

Create a new Klar project with the standard directory structure.

klar init [name] [options]

Options:

Option	Description
`--lib`	Create a library project (with `src/lib.kl`)

Examples:

# Create project in current directory
klar init

# Create project with specific name
klar init my-project

# Create a library project
klar init my-lib --lib

This creates:

klar.json — Project manifest
src/main.kl — Entry point (or src/lib.kl for libraries)

run

Run a Klar program. By default, compiles to native code and executes.

klar run <file.kl> [options] [-- program_args...]

Options:

Option	Description
`--vm`	Use bytecode VM instead of native compilation
`--interpret`	Use tree-walking interpreter
`--debug`	Enable instruction tracing (VM only)

Examples:

# Run with native compilation (default, fastest)
klar run hello.kl

# Run with bytecode VM
klar run hello.kl --vm

# Run with interpreter (slowest, for debugging)
klar run hello.kl --interpret

# Pass arguments to the program
klar run hello.kl arg1 arg2

# Use -- to pass flags to the program
klar run hello.kl -- --verbose --count=5

build

Compile a Klar program or project to a native executable.

klar build [file.kl] [options]

If no file is specified, builds the project defined in klar.json.

Options:

Option	Description
`-o <name>`	Output file name (default: `build/<basename>`)
`-O0`	No optimizations (default)
`-O1`	Basic optimizations (constant folding, DCE)
`-O2`	Standard optimizations
`-O3`	Aggressive optimizations
`-g`	Generate debug information (DWARF)
`-l <lib>`	Link with library (e.g., `-lm`, `-lcurl`)
`-L <path>`	Add library search path
`--emit-llvm`	Output LLVM IR (.ll file)
`--emit-asm`	Output assembly (.s file)
`--emit-ir`	Output Klar IR (.ir file)
`--target <triple>`	Cross-compile for target
`--verbose-opt`	Show optimization statistics

Examples:

# Basic build
klar build hello.kl              # Creates build/hello

# Custom output path
klar build hello.kl -o myapp     # Creates myapp

# Optimized build
klar build hello.kl -O2          # Standard optimizations

# Debug build
klar build hello.kl -g           # With debug symbols

# Link with external library
klar build math.kl -lm           # Link with libm

# Multiple libraries with search path
klar build app.kl -L/opt/lib -lmylib -lcurl

# Inspect generated code
klar build hello.kl --emit-llvm  # Creates hello.ll
klar build hello.kl --emit-asm   # Creates hello.s

# Cross-compilation
klar build hello.kl --target x86_64-linux-gnu

# WebAssembly
klar build hello.kl --target wasm          # Freestanding wasm32
klar build hello.kl --target wasi          # WASI target
klar build hello.kl --target wasm -c       # Object file only

Target Triples:

Triple	Description
`x86_64-linux-gnu`	Linux on x86_64
`aarch64-linux-gnu`	Linux on ARM64
`x86_64-apple-macosx`	macOS on Intel
`arm64-apple-macosx`	macOS on Apple Silicon
`x86_64-windows-msvc`	Windows on x86_64
`aarch64-none-elf`	Bare-metal ARM64 (ELF)
`aarch64-none-eabi`	Bare-metal ARM64 (EABI)
`wasm32-unknown-unknown`	WebAssembly (freestanding)
`wasm32-unknown-wasi`	WebAssembly (WASI)

Shorthand targets: --target wasm expands to wasm32-unknown-unknown, --target wasi expands to wasm32-unknown-wasi.

Bare-Metal Options:

For embedded and OS development, Klar supports freestanding compilation:

Option	Description
`--freestanding`	Compile without standard library (no libc)
`--entry <symbol>`	Set entry point symbol (default: main)
`-T <path>`	Use custom linker script

# Build a freestanding kernel
klar build kernel.kl --freestanding --target aarch64-none-elf -T linker.ld

check

Type-check a file without compiling or running.

klar check <file.kl> [options]

Options:

Option	Description
`--dump-ownership`	Show ownership analysis output

Examples:

# Type check a file
klar check myprogram.kl

# Check with ownership analysis output
klar check myprogram.kl --dump-ownership

repl

Start an interactive REPL (Read-Eval-Print Loop).

klar repl

See REPL Guide for detailed usage.

update

Regenerate the lock file from the project manifest.

klar update

This reads klar.json and regenerates klar.lock with resolved dependency information.

Other Commands

Command	Description
`tokenize <file>`	Show lexer output (tokens)
`parse <file>`	Show parser output (AST)
`disasm <file>`	Disassemble bytecode
`help`	Show help message
`version`	Show version
`test`	Run tests (not yet implemented)
`fmt`	Format source files (not yet implemented)

Exit Codes

The klar run command returns the exit code from your program's main function:

fn main() -> i32 {
    return 0  // Exit code 0 = success
}

If compilation fails, klar returns a non-zero exit code.

Environment

Klar does not currently use any environment variables for configuration.

Next Steps

REPL Guide - Interactive development
Hello World - Your first program