Leia

Getting Started

Leia can be used as a standalone script runner or embedded in a Go process. From a checkout, run the CLI with go run:

go run ./cmd/leia help
go run ./cmd/leia eval 'print("hello from leia")'
go run ./cmd/leia run tests/smoke/01_basic.leia

Install the latest published CLI and language server from their explicit command paths:

go install github.com/never-labs/leia/cmd/leia@latest
go install github.com/never-labs/leia/cmd/leia-lsp@latest
leia version
leia-lsp --help

From a checkout, install the current source into an isolated or configured GOBIN without depending on a published tag:

GOBIN=/tmp/leia-bin go install ./cmd/leia ./cmd/leia-lsp
/tmp/leia-bin/leia version
/tmp/leia-bin/leia-lsp --help

The published v0.1.0 binary release can be installed with scripts/install.sh; the checksummed archive contains both leia and leia-lsp:

bash scripts/install.sh --version v0.1.0 --bin-dir "$HOME/bin"

Use --base-url when installing from a release mirror or local artifact fixture that contains the archive and SHA256SUMS:

bash scripts/install.sh --version v0.1.0 --base-url file:///tmp/leia-release --bin-dir "$HOME/bin"

Run Examples

Start with the repository example entrypoints:

go run ./cmd/leia examples list
go run ./cmd/leia examples check examples/hello/fib.leia examples/hello/types_demo.leia
go run ./cmd/leia examples run repo-hello-fib

Then try examples for concurrency and data-oriented code:

go run ./cmd/leia examples run examples/concurrency/goroutines_channels.leia
go run ./cmd/leia examples run examples/data_processing/data_oriented/soa_kernels.leia
go run ./cmd/leia examples run examples/data_processing/data_oriented/dense_matrix_vec_kernels.leia

Leia’s larger examples include DSLs: shell/data/web dialects, spreadsheets, data-oriented runtime paths, and optional AI workflows. AI examples require a host provider or replay fixture; keep API keys in environment variables, not source files.

Check Code

Use the local quality gate while editing:

go run ./cmd/leia check --quick .
go test ./...

Useful focused commands:

go run ./cmd/leia fmt --check tests/smoke/01_basic.leia
go run ./cmd/leia lint tests/smoke/01_basic.leia
go run ./cmd/leia test tests/smoke/01_basic.leia
go run ./cmd/leia bench --quick

Embed In Go

package main

import leia "github.com/never-labs/leia"

func main() {
	vm := leia.New(leia.WithLibs(leia.LibSafe))
	if err := vm.Exec(`print("hello from embedded leia")`); err != nil {
		panic(err)
	}
}

For untrusted scripts, start from the security preset:

vm := leia.New(
	leia.SecuritySandbox(),
	leia.WithMaxSteps(100_000),
	leia.WithMaxNativeCalls(1_000),
)

Hot Reload

Hosts can reload script code without restarting the Go process:

loader := leia.NewHotLoader(leia.WithHotLoaderVMOptions(leia.WithVM()))
inst, err := loader.LoadInstance("logic.leia")
if err != nil {
	return err
}
_, err = inst.Call("tick")
_, _ = inst.ReloadIfChanged()

HotInstance preserves ordinary script state where compatible and rolls back failed reloads.

Project Modules

Create module metadata when a project has dependencies, vendored packages, or capability summaries:

go run ./cmd/leia mod init --module github.com/example/tool
go run ./cmd/leia mod list --json
go run ./cmd/leia mod verify --json

Next steps: