ShLua
Write shell scripts with the elegance and power of Lua.
"You know Lua? You already know bash/powershell then!" — Nobody

---

ShLua lets you write your script logic once in clean Lua and transpile it to native, zero-dependency Bash and PowerShell scripts. No new syntax or DSL to learn, no forcing other script-interpreted runtimes onto your users—just fast, cross-platform scripts that run out-of-the-box in any terminal or CI pipeline.

---

✨ Features

• 🔄 Lua to Shell Transpilation: Write maintainable Lua scripts and transpile them to native shell scripts (Bash / PowerShell).
• ⚡ Portable CLI: Run the bundled Lua CLI file or a standalone Windows or Linux executable.
• 📦 No extra setup required: Easy installation and execution across platforms, no additional/external dependencies. Just download and use.

---

📦 Installing

Go to releases, then you can download the following formats.

• shlua.lua — dependency-free Lua 5.1 compatible library and usable as CLI.
• shlua.exe — standalone Windows x64 CLI executable.
• shlua — standalone Linux x64 CLI executable.

---

🚀 Usage

As a standalone CLI

First check [Installing instructions](## 📦 Installing), then run --help with the Lua distribution, Windows executable, or Linux executable:

# Used as a CLI. You need lua >= 5.1 installed in your PATH env variable.
lua shlua.lua --help

# Windows
./luash_win_x64.exe --help

# Linux-Based OS
./luash --help

ShLua v0.1.0-alpha - Transpile Lua code to Bash, PowerShell, or both.

USAGE:
            lua main.lua <input.lua> [OPTIONS]
            lua main.lua -i <input.lua> [OPTIONS]

OPTIONS:
    -i, --input <file>     Path to input Lua script.
    -o, --output <file>    Base path for output files (Optional).
                           If target is 'all', target extensions (.sh/.ps1) are appended.
    -t, --target <target>  Target language: 'bash', 'ps1', or 'all' (Default: 'all').
    -a, --dump-ast         Print source Lua AST to stdout and exit.
    -v, --verbose          Print execution pipeline trace details.
    -h, --help             Show this help menu and exit.

As a Library (Support for >= lua 5.1)

-- Your custom lua script...
local ShLua = require("shlua")

local source = [[
local function greet(name)
    return "Hello, " .. name
end

print(greet("Lua"))
]] -- Or reading from another .lua file in CWD...

-- Transpiling (In memory)
local bash = ShLua.transpile(source, "bash")
local powershell = ShLua.compile(source, "ps1")
local both = ShLua.transpile(source, "all")

-- Resolve project-local modules relative to an input file before transpiling.
local bundledBash = ShLua.transpileFile("scripts/main.lua", "bash")

-- Transpiling (To output file!) Bash
local bashFile = assert(io.open("greet.sh", "w"))
bashFile:write(bash)
bashFile:close()

-- Transpiling (To output file!) Powershell
local ps1File = assert(io.open("greet.ps1", "w"))
ps1File:write(both.ps1) -- equivalent to `powershell`
ps1File:close()

---

Compatibility

ShLua accepts Lua 5.1 syntax and transpiles to Bash 3.2+ and PowerShell 3.0+ (including PowerShell Core 6+).

---

🚧 Limitations

🚧 Still in early development, conceptual-only so far.

require() is resolved before transpilation. Standard-library imports such as require("io"), require("os"), and require("string") are removed because their supported helpers are embedded in generated scripts. Project-local modules are recursively bundled from the input file's directory; dotted module names resolve to module/name.lua or module/name/init.lua. Missing modules and dependency cycles are rejected with clear errors.

The alpha bundler flattens modules that expose globals or perform side effects. Conventional return-value modules (for example, local M = {}; return M) are not yet preserved by the target-language subset.

Not whole 5.1 stdlib ported yet to bash and ps1. Working on that.

---

❓ Why?

While tweaking my nvim-config, I found myself repeating a tedious task: writing separate helper scripts in Bash and PowerShell for projects like PanelsPlus so contributors could build and set things up effortlessly on any OS without needing a deep dive into the repo.

So I thought:

Lua is simple, expressive, and lightweight—why shouldn't our build, CI, and helper scripts be as well?

That highlighted a few common pain points:

• Bash & PowerShell syntaxes are wildly different. Learning both completely and keeping their logic manually in sync is error-prone.
• Relying on AI gets tedious. Prompting AI to translate script logic back and forth every time you make a change wastes time and tokens (unless you're a token-maxxer, of course).
• Python or Node.js scripts add unnecessary bloat for non-related projects. Forcing contributors or CI/CD pipelines to install Node.js, Bun, or Python just to run a setup script—especially on projects that are possibly unrelated to JS or Python—is an annoying dependency lock-in, this applies for any other language.

The purpose is not a drop-in replacements for already stablished-mature building programs. Just provide an alternative for your multi-OS scripting, a simpler one.

But, I already use ***** tool for building. Should I replace it with this?

Makefiles, package.json scripts, python, or anything you use are fine if you're already using them. But they're tied down to their specific ecosystems. Of course, its natural to use package.json in js/ts projects or Make in C/C++ projects, (etc...), but what if you need your scripts outside of that ecosystem?, maybe for easily installation, faster CI actions pipelines...

This aims for projects that:

• Their build system lang is not related to the language of the project itself.
• Want create multi-platform native scripts (sh and ps1) without having to learn those 2 and maintain them separately.
• Want curious git cloners that just want to clone-build fast without needing extra-effort. (Improving your proyect for possible new contributors)
• Want to optimize their CI, so they can run all the needed scripts without needint to install a whole runtime or binary just to run lint, build, formatting (& more) scripts?