#CLI Reference

luxc is distributed as an alpha toolchain binary and can also be built from source. The release zip includes install-lux-path.ps1, which installs the compiler beside it into the user toolchain layout. Source builds can use the same script with -LuxcPath .\compiler\target\release\luxc.exe.

With luxc on PATH, run commands as:

luxc <command>

If luxc is not on PATH, use the explicit build output or installed user entrypoint:

.\compiler\target\release\luxc.exe <command>
%USERPROFILE%\.lux\bin\luxc.exe <command>

Official packages such as @lux/std are installed per project with luxc init --std or luxc install.

#Command Overview

luxc lex <path>
luxc parse <path>
luxc lint <path>
luxc format <path> [--check] [--write]
luxc build <source-root> --out <path> [--map] [--source-comments none|readable|boundary|dense]
luxc init [path] [--name <name>] [--std] [--out <path>] [--runtime-base <path>] [--no-autorun]
luxc install <package-id> --from <github:owner/repo|url|path> [--tag <tag>|--branch <branch>|--commit <commit>]
luxc remove <package-id> [--project <project-root>]
luxc lock [project-root]
luxc list [project-root]
luxc doctor [project-root]
luxc self install [version] [--from <path|url>] [--default]
luxc self update
luxc self default <version>
luxc self list
luxc self which [--project <project-root>]
luxc self pin <version> [--project <project-root>]
luxc self unpin [--project <project-root>]
luxc lsp
luxc compile <path> [--map <path>] [--source-comments none|readable|boundary|dense]
luxc map-error <map.json> <generated-line>
luxc gmod build <source-root> --out <path> [--runtime-base <path>] [--no-autorun] [--dry-run]
luxc gmod build --manifest <lux.toml> [--out <path>] [--runtime-base <path>] [--no-autorun] [--dry-run]
luxc gmod package --manifest <lux.toml> --root <path> --gmad <path> --out <path> [--run] [--build-out <path>] [--runtime-base <path>] [--no-autorun]
luxc gmod api update [--out <path>] [--coverage-out <path>] [--cache-dir <path>] [--offline] [--allow-failures]

All paths are read and written as UTF-8 text.

#lex

Print tokens for one file:

luxc lex examples\features.lux

Use this only when debugging parser or lexer behavior. Normal users should not need it.

#parse

Parse one file and print the syntax tree:

luxc parse examples\features.lux

This is useful when checking whether a new syntax form is recognized before lowering or codegen is implemented.

#lint

Run syntax, resolver, module, and style checks without generating Lua:

luxc lint examples\features.lux

lint reports diagnostics with source spans. It is the cheapest command to run in editors and pre-commit checks.

@lint.disable("unused-local")
local debugValue = expensiveProbe()

Use local disables sparingly. If a rule is wrong for a whole project, configure the rule rather than scattering suppressions.

#format

Check formatting:

luxc format src\inventory\module.lux --check

Write formatting changes:

luxc format src\inventory\module.lux --write

Formatter output is intended to preserve comments and keep Lux-specific syntax readable. Generated Lua formatting is controlled by the emitter, not this command.

#build

Recursively compile .lux files under a source directory as isolated files and preserve their source-relative paths in the output directory:

luxc build src --out generated/lua

This is for gradual GLua integration where you want syntax improvements but do not want Lux to generate a GMod loader tree. Each input file is compiled like luxc compile, so imports, packages, exports, and realms are not resolved as a project graph.

Add source maps and comments when debugging generated Lua:

luxc build src --out generated/lua --map --source-comments readable

#init

Create a project skeleton:

luxc init my_addon

Plain init is offline and writes an empty [dependencies] table. Add --std when the project should install the official standard package set:

luxc init my_addon --std

By default, init creates an addon-friendly GMod configuration:

[target.gmod]
source_root = "src"
out = "generated/lua"
runtime_base = "lux/my_addon"
autorun = true

Use --no-autorun when an existing entry point should include the generated Lux loaders:

luxc init my_addon --no-autorun --out generated

#install

Add a direct package dependency and rewrite lux.lock:

Push-Location my_addon
luxc install @lux/gmod --from github:TimeWatcher/lux-packages
Pop-Location

Lux has no registry. The source passed with --from selects the package set: github:owner/repo, a zip url, or a local path. For GitHub sources, pin the selected package set with one of --tag, --branch, or --commit.

#remove

Remove a direct dependency from lux.toml and rewrite lux.lock:

luxc remove @lux/gmod --project my_addon

Transitive packages disappear naturally when no remaining direct dependency requires them. Removing a transitive-only package is rejected because it is not owned by the project manifest.

#lock

Regenerate lux.lock from the current lux.toml:

luxc lock my_addon

This command does not search for newer versions. With Lux's registryless model, version choice is the explicit source ref in the manifest; package versions in lux.package.toml are compatibility checks for the selected package graph.

#list

Print locked packages:

luxc list my_addon

#doctor

Inspect package manager state:

luxc doctor my_addon

#self

Install the current compiler into the user toolchain layout and make it the global default. Release zips normally use install-lux-path.ps1 instead; this command is mainly for explicit version management and source-build workflows:

luxc self install --default

The stable user entrypoint is ~/.lux/bin/luxc on Unix-like systems and %USERPROFILE%\.lux\bin\luxc.exe on Windows. Installed compilers live under ~/.lux/toolchains/<version>/.

Install or update explicit versions:

luxc self update
luxc self install 0.1.0-alpha.2 --default

Inspect and select installed versions:

luxc self list
luxc self which
luxc self default 0.1.0-alpha.2

Most projects use the global default. Pin only when a team or CI job needs a specific compiler:

luxc self pin 0.1.0-alpha.2 --project my_addon
luxc self unpin --project my_addon

#lsp

Start the compiler-backed Language Server Protocol process:

luxc lsp

Editors should launch this command from the compiler selected by the project or user configuration. This keeps diagnostics, completions, package resolution, and builds on the same luxc version.

#compile

Compile one Lux file to Lua:

luxc compile examples\features.lux

Emit source comments:

luxc compile examples\features.lux --source-comments readable

Emit a sidecar source map:

luxc compile examples\features.lux --map examples\features.lua.map.json

compile is for isolated examples and backend debugging. Use gmod build for real addon projects so modules, packages, and realms are handled together.

#map-error

Map a generated Lua location back to Lux source:

luxc map-error generated\features.lua.map.json 42

The input line/column should come from a GMod Lua stack trace or Lua syntax error. When source comments are disabled in production output, sidecar maps are the main way to recover Lux source locations.

#gmod build

Build a GMod project from a manifest:

luxc gmod build --manifest lux.toml

Build with explicit paths:

luxc gmod build src --out generated/lua

Preview the output plan without writing files:

luxc gmod build --manifest lux.toml --dry-run

gmod build performs module discovery, package resolution, realm splitting, loader generation, source map generation, and diagnostics for the whole project. --no-autorun disables only the addon-style forwarder under out/autorun; the Lux loader tree and module registry are still emitted.

#gmod package

Package a built addon with gmad.exe:

luxc gmod package --manifest lux.toml --root generated --gmad C:\path\to\gmad.exe --out dist\my_addon.gma

Add --run to actually invoke gmad. Without --run, Lux prints the package plan so CI and release scripts can inspect it.

luxc gmod package --manifest lux.toml --root generated --gmad C:\path\to\gmad.exe --out dist\my_addon.gma --run

Packaging does not replace gmod build; it packages the addon layout produced by the build step. --root is the package root passed to gmad; it is separate from the build out path. Use --build-out only when the package command should temporarily override the manifest build output.

#gmod api update

Regenerate the bundled official GMod API database:

luxc gmod api update `
  --out lsp\crates\gmod-api-db\data\generated\gmod_api.json `
  --coverage-out lsp\crates\gmod-api-db\data\generated\coverage_manifest.json `
  --cache-dir lsp\target\gmod-api-cache

Use --offline only with an existing cache. --allow-failures is for parser development and should not be used for release-quality bundled data.