Skip to main content

Luat CLI Reference

The Luat CLI is the command-line tool for creating, developing, building, and serving Luat applications.

Installation​

npm install -g @maravilla-labs/luat

Homebrew (macOS)​

brew install maravilla-labs/tap/luat

Shell Script (Linux/macOS)​

curl -fsSL https://raw.githubusercontent.com/maravilla-labs/luat/main/scripts/install.sh | sh

Cargo (Rust)​

cargo install luat-cli

Verify installation:

luat --version

Commands​

luat init​

Creates a new Luat project with SvelteKit-style structure.

luat init my-project
cd my-project

If no name is provided, initializes in the current directory:

mkdir my-project && cd my-project
luat init

Created structure:

my-project/
├── luat.toml
├── src/
│   ├── app.html
│   ├── routes/
│   │   ├── +layout.luat
│   │   ├── +page.luat
│   │   └── +page.server.lua
│   └── lib/
├── static/
└── public/

luat dev​

Starts the development server with live reload and file watching.

luat dev

Options:

OptionDescriptionDefault
--port PORTServer port3000
--host HOSTServer host127.0.0.1

Examples:

# Default (localhost:3000)
luat dev

# Custom port
luat dev --port 8080

# Listen on all interfaces
luat dev --host 0.0.0.0

# Both
luat dev --port 8080 --host 0.0.0.0

Features:

  • Automatic template recompilation on file changes
  • Live reload in browser
  • Frontend toolchain watch mode (Tailwind, Sass, TypeScript)
  • Automatic tool downloads on first run

luat build​

Builds the application for production.

luat build

Options:

OptionDescriptionDefault
--sourceOutput Lua source instead of binaryBinary output
--output DIROutput directorydist

Examples:

# Default build (binary bundle)
luat build

# Lua source bundle
luat build --source

# Custom output directory
luat build --output ./build

# Both
luat build --source --output ./my-build

Output:

dist/
├── bundle.bin          # or bundle.lua with --source
└── public/
    └── css/
        └── tailwind.css

luat serve​

Serves the production build.

luat serve

Options:

OptionDescriptionDefault
--port PORTServer port3000
--host HOSTServer host0.0.0.0

Examples:

# Default (0.0.0.0:3000)
luat serve

# Custom port
luat serve --port 80

# Localhost only
luat serve --host 127.0.0.1

Notes:

  • No live reload (production optimized)
  • Requires prior luat build
  • Default host is 0.0.0.0 (all interfaces)

luat watch​

Watches files and rebuilds on changes without starting a server.

luat watch

Useful for:

  • Build pipelines
  • Integration with external servers
  • CI/CD workflows

Configuration​

The CLI reads configuration from luat.toml in the project root:

[project]
name = "my-app"
version = "0.1.0"

[dev]
port = 3000
host = "127.0.0.1"

[build]
output_dir = "dist"
bundle_format = "source"

[routing]
simplified = false
routes_dir = "src/routes"
lib_dir = "src/lib"
static_dir = "static"
app_html = "src/app.html"

[frontend]
enabled = ["tailwind"]
tailwind_version = "4.0.5"
tailwind_output = "public/css/tailwind.css"
tailwind_content = ["src/**/*.luat", "src/**/*.html"]

Command-line options override configuration file settings.

Common Workflows​

Starting a New Project​

luat init my-app
cd my-app
luat dev

Development​

cd my-app
luat dev --port 8080
# Make changes, see live updates

Production Deployment​

# Build
luat build

# Test locally
luat serve

# Deploy dist/ to your server
rsync -av dist/ user@server:/var/www/app/

# Run on server
luat serve --port 80

Adding Pages​

  1. Create route file:
mkdir -p src/routes/about
touch src/routes/about/+page.luat
  1. Add content:
<h1>About Us</h1>
<p>Welcome to our about page.</p>
  1. View at http://localhost:3000/about

Troubleshooting​

Command Not Found​

Ensure the CLI is installed and in your PATH:

# Check installation
which luat

# Reinstall if needed
npm install -g @maravilla-labs/luat

Permission Denied​

On Unix systems, you may need to adjust permissions:

chmod +x $(which luat)

Port in Use​

# Check what's using the port
lsof -i :3000

# Use a different port
luat dev --port 3001

Frontend Tools Not Working​

Clear the tool cache and retry:

rm -rf ~/.cache/luat/tools/
luat dev

Build Errors​

Check for:

  • Syntax errors in .luat files
  • Missing modules in require() calls
  • Invalid luat.toml configuration

Run with verbose output:

RUST_LOG=debug luat build