Luma documentation
Introduction
Getting Started (installing the CLI / running code)

Getting Started (installing the CLI / running code)

Luma is designed to be lightweight, fast, and accessible - for beginners and professionals alike. As we move toward a stable release, we aim to support two flexible installation options to suit different users.

Two Installation Modes

1. System Go (Lightweight Mode)

Recommended for developers who already have Go installed on their system.

  • Install Luma CLI via curl, package manager, or binary
  • Relies on system-installed Go (≥ 1.21)
  • Smaller download (~5–10 MB)
  • Ideal for developers familiar with the Go toolchain
go install luma-lang.dev/cmd/luma@latest
luma build hello.luma

2. Bundled Go (Full Mode)

Ideal for beginners or users without Go installed.

  • Ships with Go compiler in a subfolder (/go)
  • Zero setup: no need to install Go manually
  • Auto-detected by the Luma CLI
  • Slightly larger (~100–200 MB)
  • Same CLI experience
luma/
├── luma             # Luma CLI binary
├── go/              # Embedded Go compiler
│   └── bin/go

The CLI detects Go like this:

  • If go is found in $PATH → use system Go
  • Else if ./go/bin/go exists → use bundled Go
  • Else → show helpful error

CLI Behavior Preview 

$ luma build main.luma
> Using system Go (v1.22.1)

# Or if no system Go:
> Using bundled Go (v1.22.1)

Future Enhancements (Planned)

  • --use-system-go or --use-bundled-go flags for control
  • Environment variable: LUMA_GO_PATH
  • Pre-built installers for:
    • Windows (.exe / .msi)
    • macOS (.pkg)
    • Linux (.deb, .tar.gz, AppImage)

Why This Approach?

We want to support:

  • Zero friction onboarding for newcomers
  • Powerful control for advanced users
  • Consistency across environments (CI, scripts, education)

This dual-mode installation ensures Luma remains accessible, portable, and developer-friendly.

Available Modules

Luma ships with ready-to-use modules written entirely in Luma. Import them with a single line — no package manager, no external dependencies.

csv   = import "csv"
table = import "table"
Module Import Description
CSV import "csv" Parse, query, filter, and write CSV files. Handles quoted fields, custom delimiters, and TSV
Table import "table" Format [[str]] data as terminal tables. Four styles: box-drawing, ASCII, compact, and markdown
JWT import "jwt" Sign and verify JSON Web Tokens (HS256)
MySQL import "mysql" Connect to MySQL databases, execute queries, and read results. Pure Luma driver

Quick examples

CSV to terminal table:

csv   = import "csv"
table = import "table"

data: [[str]] = csv.read("users.csv")
table.print_table(data)

Pretty-print any data:

table = import "table"

data: [[str]] = [
    ["Name", "Role", "City"],
    ["Alice", "Engineer", "Tallinn"],
    ["Bob", "Designer", "Riga"]
]
table.print_styled(data, "simple")

Output:

+-------+----------+---------+
| Name  | Role     | City    |
+-------+----------+---------+
| Alice | Engineer | Tallinn |
| Bob   | Designer | Riga    |
+-------+----------+---------+

Modules are .luma files that live alongside your project. See Modules & Imports for how the module system works.

Last updated on
Why Luma? (vs Go, Python, Rust, etc.)