Lumos — CLI Framework for Lua

A modern CLI framework for Lua.
Let there be light in your terminal.

$ luarocks install lumos

Why Lumos?

Built for developers who ship.

Ship in minutes

Run lumos new and get a complete project structure with tests, Makefile, README, and working sample commands. You write the logic, Lumos handles the scaffolding.

Look professional

From ANSI colors and progress bars to interactive prompts and data tables, every UI primitive is included. Your CLI looks polished from the first commit without adding a single dependency.

Distribute anywhere

Distribute a Lua script for developers, a zero-dependency executable for end users, or a statically linked native binary for performance-critical deployments — all from the same codebase.

Showcase

See what you can build with Lumos in a few lines of Lua.

Type-safe flags

Validate emails, URLs, ports, and paths automatically at runtime.

  
flags.lua

local deploy = app:command("deploy", "Deploy app")
deploy:flag_int("-p --port", "Port", 1, 65535)
deploy:flag_email("--notify", "Email")
deploy:flag_url("--endpoint", "API URL")

Beautiful tables

Render boxed lists, data tables, or key-value pairs with auto-calculated widths.

  
tables.lua

local tbl = require('lumos.table')
print(tbl.create({
    {name="Lua", year=1993},
    {name="Moon", year=2020}
}, {headers={"name","year"}}))

Interactive prompts

Build interactive CLIs with arrow-key selection and password inputs.

  
prompts.lua

local p = require('lumos.prompt')
local name = p.input("Name", "Anon")
local ok = p.confirm("Deploy?", true)
local i, env = p.select("Env", {"dev","prod"})

Features

Everything you need to build production-ready CLI tools.

Everything in One API

Commands, subcommands, typed flags, hooks, plugins, and middleware through one chainable API inspired by Cobra. No external routers or parsers needed.

Beautiful Terminal UI

Colors, spinners, progress bars, tables, and interactive prompts — all with zero extra Lua dependencies.

Ship Anywhere

Ship as a Lua script, a standalone binary without a C compiler, or a static native build — choose what fits your users.

Shell Integration

Auto-generate bash, zsh, fish, and powershell completions with enum value and subcommand support. Plus man pages and Markdown docs straight from your code.

Built-in Safety

Input sanitization, path traversal prevention, shell escaping, audit logging, and rate limiting — all built-in, zero extra dependencies.

Project Scaffolding

Bootstrap a full CLI project with tests, Makefile, and sample commands in seconds with lumos new.

Cross-Platform

Runs on Linux, macOS, and Windows with automatic TTY detection and portable builds.

What else?

Got an idea or feature request? Open an issue — we read everything.

Everything in One API

Commands, subcommands, typed flags, hooks, plugins, and middleware through one chainable API inspired by Cobra. No external routers or parsers needed.

Beautiful Terminal UI

Colors, spinners, progress bars, tables, and interactive prompts — all with zero extra Lua dependencies.

Ship Anywhere

Ship as a Lua script, a standalone binary without a C compiler, or a static native build — choose what fits your users.

Shell Integration

Auto-generate bash, zsh, fish, and powershell completions with enum value and subcommand support. Plus man pages and Markdown docs straight from your code.

Built-in Safety

Input sanitization, path traversal prevention, shell escaping, audit logging, and rate limiting — all built-in, zero extra dependencies.

Project Scaffolding

Bootstrap a full CLI project with tests, Makefile, and sample commands in seconds with lumos new.

Cross-Platform

Runs on Linux, macOS, and Windows with automatic TTY detection and portable builds.

What else?

Got an idea or feature request? Open an issue — we read everything.

Quick Start

From zero to CLI in under a minute.

main.lua

local lumos = require('lumos')
local app = lumos.new_app({
   name = 'mycli',
   version = '0.3.8',
   description = 'My CLI app'
})

app:command('hello', 'Say hello')
   :action(function(ctx)
      print('Hello, world!')
      return true
   end)

os.exit(app:run(arg))

CLI Tool

Scaffold, bundle, package and build with built-in commands.

scaffold

$ lumos new

Generate a new CLI project with a single command. Includes tests, Makefile, README, and sample commands.

Tests & Makefile included
Sample commands scaffold
README template

bundle

$ lumos bundle

Bundle your application into a single Lua script with all dependencies inlined. Best for environments where Lua is already installed and you want full transparency.

Single portable script
Cross-platform support
Requires Lua runtime

package

$ lumos package

Create a zero-dependency executable using a precompiled launcher. No C compiler required on your build machine, and your users do not need Lua installed.

Zero-dependency executable
Cross-platform from any host
Precompiled launcher + Lua payload

native

$ lumos build

Compile a true native binary with an embedded Lua VM. Statically link C modules like lfs or lpeg for maximum performance and completely standalone distribution.

Native binary with embedded Lua VM
Static linking of C modules
Cross-compile targets (Windows, Linux ARM64)

diagnose

$ lumos doctor

Check your environment for common issues. Verifies Lua, LuaRocks, C compiler, launchers and build toolchain.

Environment health check
Detects missing dependencies
Build toolchain validation

update

$ lumos update

Update Lumos to the latest version via LuaRocks in one command. Shows current and new version after install.

One-command update
Version before / after
Falls back to manual hint on error

scaffold

$ lumos new

Generate a new CLI project with a single command. Includes tests, Makefile, README, and sample commands.

Tests & Makefile included
Sample commands scaffold
README template

bundle

$ lumos bundle

Bundle your application into a single Lua script with all dependencies inlined. Best for environments where Lua is already installed and you want full transparency.

Single portable script
Cross-platform support
Requires Lua runtime

package

$ lumos package

Create a zero-dependency executable using a precompiled launcher. No C compiler required on your build machine, and your users do not need Lua installed.

Zero-dependency executable
Cross-platform from any host
Precompiled launcher + Lua payload

native

$ lumos build

Compile a true native binary with an embedded Lua VM. Statically link C modules like lfs or lpeg for maximum performance and completely standalone distribution.

Native binary with embedded Lua VM
Static linking of C modules
Cross-compile targets (Windows, Linux ARM64)

diagnose

$ lumos doctor

Check your environment for common issues. Verifies Lua, LuaRocks, C compiler, launchers and build toolchain.

Environment health check
Detects missing dependencies
Build toolchain validation

update

$ lumos update

Update Lumos to the latest version via LuaRocks in one command. Shows current and new version after install.

One-command update
Version before / after
Falls back to manual hint on error

Built for Production

What separates a parser from a framework.

Middleware & Hooks

Intercept every command with an Express-like middleware chain. Add authentication, dry-run previews, timeouts, circuit breakers, rate limiting, and automatic retries without touching your business logic.

Configuration & Secrets

Load JSON, YAML, TOML, or key=value files automatically. Merge environment variables by prefix and validate everything against a schema before your code runs.

Typed Error Handling

Return structured errors with context, exit codes, and user-friendly messages. Lumos suggests the correct command when users mistype, reducing support friction.

Testable by Design

Every command accepts a table of simulated arguments. Test your entire CLI with Busted in-memory — no subprocess spawning, no fixture files needed.

Middleware & Hooks

Configuration & Secrets

Load JSON, YAML, TOML, or key=value files automatically. Merge environment variables by prefix and validate everything against a schema before your code runs.

Typed Error Handling

Return structured errors with context, exit codes, and user-friendly messages. Lumos suggests the correct command when users mistype, reducing support friction.

Testable by Design

Every command accepts a table of simulated arguments. Test your entire CLI with Busted in-memory — no subprocess spawning, no fixture files needed.