Documentation — Lumos CLI Framework for Lua

# Install from LuaRocks
luarocks install --local lumos

# Add to PATH
echo 'export PATH="$HOME/.luarocks/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

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

local greet = app:command("greet", "Greet someone")
greet:arg("name", "Name to greet")
greet:flag("-u --uppercase", "Use uppercase")

greet:action(function(ctx)
    local msg = "Hello, " .. (ctx.args[1] or "World") .. "!"
    if ctx.flags.uppercase then
        msg = msg:upper()
    end
    print(msg)
    return true
end)

os.exit(app:run(arg))

app:command("greet", "Greet someone")
    :arg("name", "Name to greet")
    :flag("-u --uppercase", "Use uppercase")
    :alias("hi")
    :examples({"mycli greet Alice", "mycli greet Bob -u"})
    :action(function(ctx)
        print(ctx.args[1] or "World")
    end)

local cmd = app:command("deploy", "Deploy app")
cmd:flag_int("-p --port", "Server port", 1, 65535)
cmd:flag_string("-e --env", "Environment")
cmd:flag_email("--notify", "Notify email")
cmd:flag_url("--endpoint", "API endpoint")
cmd:flag_path("-c --config", "Config file")
cmd:persistent_flag("-v --verbose", "Verbose output")

local core = require('lumos.core')

-- app:run() returns EXIT_OK, EXIT_ERROR or EXIT_USAGE
local code = app:run(arg)
os.exit(code)

-- Typing a command that doesn't exist shows a suggestion:
-- Error: Unknown command 'gree'
-- Did you mean: greet?

local greet = app:command("greet", "Greet someone")
greet:pre_run(function(ctx)
    print("Starting greeting...")
end)
greet:post_run(function(ctx)
    print("Greeting done.")
end)

-- App-level hooks run for every command
app:persistent_pre_run(function(ctx)
    print("Global setup")
end)

local lumos = require('lumos')
local mw = lumos.middleware

-- Global middleware runs for every command
app:use(mw.builtin.logger(), 10)
app:use(mw.builtin.auth({env_var = "API_KEY"}), 50)
app:use(mw.builtin.rate_limit({max_requests = 10, window_seconds = 60}), 30)

-- Command-level middleware
local deploy = app:command("deploy", "Deploy app")
deploy:use(mw.builtin.confirm({
    message = "Are you sure you want to deploy to production?",
    default = false
}), 20)
deploy:use(mw.builtin.retry({max_attempts = 3, backoff = "exponential"}), 40)

cmd:flag("-v --verbose", "Increase verbosity"):countable()

local deploy = app:command("deploy", "Deploy app")
deploy:flag_string("-e --env", "Environment")
    :default("dev")
    :env("DEPLOY_ENV")
    :required(true)
    :validate(function(v)
        return v == "dev" or v == "prod"
    end)

deploy:flag_int("-p --port", "Server port", 1, 65535)
    :default(8080)

local greet = app:command("greet", "Greet someone")
greet:arg("name", "Name to greet", {
    required = true,
    type = "string",
    validate = function(v)
        return #v >= 2
    end
})
greet:arg("count", "How many times", {
    type = "number",
    min = 1,
    max = 10,
    default = 1
})

local lumos = require('lumos')
local plugin = require('lumos.plugin')

-- Define a reusable plugin that adds a --debug flag
local my_plugin = function(target, opts)
    target:persistent_flag("--debug", "Enable debug mode")
end

-- Register globally on the app
plugin.use(app, my_plugin, {verbose = true})

-- Or attach directly to a specific command
local deploy = app:command("deploy", "Deploy app")
deploy:plugin(my_plugin)

local deploy = app:command("deploy", "Deploy app")

-- Mutually exclusive flags: only one input source allowed
deploy:flag_string("-f --file", "Config file")
deploy:flag_string("-u --url", "Config URL")
deploy:mutex_group("input", {"file", "url"}, {required = true})

-- Hidden flag: internal use, not shown in --help
deploy:flag("--internal-token", "Service token")
    :hidden_flag(true)

-- Deprecated flag: warns user to migrate
deploy:flag("--legacy-deploy", "Old deploy path")
    :deprecated("Use --strategy=bluegreen instead")

local color = require('lumos.color')
print(color.green("Success!"))
print(color.red("Error!"))
print(color.bold(color.yellow("Warning")))

-- Template-based
local out = color.format("{green}OK {reset}Done")
print(out)

-- Status and log helpers
print(color.status.success("Done"))
print(color.log.info("Ready"))

local format = require('lumos.format')

print(format.bold("Bold"))
print(format.truncate("very long text", 10))
print(format.title_case("hello world"))
print(format.pad_center("hi", 10))
print(format.uppercase("hello"))

local tbl = require('lumos.table')

-- Boxed list
print(tbl.boxed({"A", "B", "C"}, {
    header = "Items", align = "center"
}))

-- Data table
print(tbl.create({
    {name="Lua", year=1993},
    {name="Moon", year=2020}
}, {headers={"name","year"}}))

local tbl = require('lumos.table')

-- Split into pages
local pages = tbl.paginate(rows, 10)

-- Get a single page with metadata
local result = tbl.page(rows, 1, 10)
print(result.page, "/", result.total_pages)

local progress = require('lumos.progress')

-- Simple one-liner
for i = 1, 100 do
    progress.simple(i, 100)
end

-- Advanced bar
local bar = progress.new({
    total = 100,
    width = 40,
    style = "unicode"
})

for i = 1, 100 do
    bar:increment(1)
    os.execute("sleep 0.02")
end
bar:finish()

local loader = require('lumos.loader')

loader.start("Processing...")
for i = 1, 50 do
    loader.next()
    -- do work
end
loader.success()

local prompt = require('lumos.prompt')

local name = prompt.input("Your name", "Anon")
local secret = prompt.password("Password")
local ok = prompt.confirm("Continue?", true)
local ix, choice = prompt.select("Pick one",
    {"dev", "staging", "prod"})
local selections = prompt.multiselect("Features",
    {"logs", "metrics", "alerts"})

local prompt = require('lumos.prompt')

-- Constrained number input
local port = prompt.number("Port", 1024, 65535, 8080)

-- Required input with validator
local email = prompt.required_input(
    "Email",
    prompt.validators.email,
    "Enter a valid email")

-- Autocomplete from options
local lang = prompt.autocomplete(
    "Language",
    {"Lua", "Python", "Rust"},
    "Lua")

-- Searchable selection
local _, tool = prompt.search("Tool",
    {"Docker", "Kubernetes", "Terraform"})

-- Multi-step wizard
local settings = prompt.wizard("Setup", {
    {
        title = "Project",
        fields = {
            {name="project", label="Name", type="input", required=true},
            {name="license", label="License", type="select",
             options={"MIT", "Apache-2.0"}, default=1}
        }
    },
    {
        title = "Config",
        fields = {
            {name="port", label="Port", type="number",
             min=1024, max=65535, default=8080},
            {name="ssl", label="Enable SSL?", type="confirm", default=true}
        }
    }
})

local config = require('lumos.config')

local file = config.load_file("config.json")
local env = config.load_env("MYAPP")

local settings = config.merge_configs(
    {timeout = 30},
    file,
    env,
    ctx.flags
)

local config = require('lumos.config')

local schema = {
    host = {required = true, type = "string"},
    port = {type = "number", validate = function(v) return v > 0 end}
}

local ok, errors = config.validate_schema(settings, schema)
local data, err = config.load_validated("config.json", schema)

local yaml = require('lumos.yaml')

local data = yaml.decode("name: Alice
age: 30")
print(data.name) -- Alice

local out = yaml.encode({name = "Bob", age = 25})

local logger = require('lumos.logger')

logger.set_level("DEBUG")
logger.info("Server started", {port = 8080})
logger.error("Connection failed", {host = "db"})

local child = logger.child({component = "http"})
child.debug("Request received", {path = "/api"})

logger.set_format("json")
logger.info("Server started", {port = 8080})

$ myapp deploy --quiet

local security = require('lumos.security')

local safe, err = security.sanitize_path(user_path)
local escaped = security.shell_escape(user_input)
local ok = security.validate_email(email)
local clean = security.sanitize_output(raw_text)

-- Rate limiting
local allowed, msg = security.rate_limit("api", 10, 60)

local http = require('lumos.http')

-- GET with query params
local resp, err = http.get("https://api.example.com/users", {
    query = {page = "1", limit = "10"}
})

-- POST with JSON body (auto-encoded)
local resp, err = http.post("https://api.example.com/users", {
    body = {name = "Alice"},
    auth = {bearer = "token"}
})

-- Response helpers
if resp and resp.ok then
    local data = resp.json()
end

-- tests/app_spec.lua (Busted)
local lumos = require('lumos')

describe("greet command", function()
    it("greets by name", function()
        local app = lumos.new_app({name = "test"})
        local greet = app:command("greet", "Greet")
        greet:arg("name", "Name")
        greet:action(function(ctx)
            print("Hello, " .. (ctx.args[1] or "World"))
            return true
        end)

        -- Run with simulated args
        local code = app:run({"greet", "Alice"})
        assert.are_equal(lumos.core.EXIT_OK, code)
    end)
end)

-- Built-in completion command
app:add_completion_command()

-- Generate a specific shell
app:generate_completion("bash")
app:generate_completion("zsh")
app:generate_completion("fish")
app:generate_completion("powershell")

-- Generate all shells to a directory
app:generate_completion("all", "./completions")

-- Custom completion values for flags
cmd:flag_enum("--env", "Environment", {"dev", "staging", "prod"})
    :complete({"dev", "staging", "prod"})

-- Man pages
app:generate_manpage(nil, "./man")

-- Markdown docs
app:generate_docs("markdown", "./docs")

# Bundle into a portable Lua script
lumos bundle src/main.lua -o dist/myapp

# Package into a standalone binary (Linux, macOS, Windows — no C compiler)
lumos package src/main.lua -o dist/myapp

# Build a native binary (requires C toolchain)
lumos build src/main.lua -o dist/myapp --static

# Analyze dependencies
lumos bundle src/main.lua --analyze

-- When to choose which distribution method

-- 1. BUNDLE: target has Lua installed, you want transparency
$ lumos bundle src/main.lua -o dist/myapp

-- 2. PACKAGE: zero-dependency executable, no C compiler needed
$ lumos package src/main.lua -o dist/myapp

-- 3. BUILD: maximum performance, static linking, native binary
$ lumos build src/main.lua -o dist/myapp --static

-- Cross-compile from Linux to Windows
$ lumos package src/main.lua -o dist/myapp -t windows-x86_64
$ lumos build src/main.lua -o dist/myapp -t windows-x86_64

-- Check your environment before building
$ lumos doctor