esmeril
Scaffold, validate, format, audit and build Roblox Luau projects from the terminal.
Twenty-five commands, one binary:
esmeril init(oresmeril new) - scaffold a modern Roblox project: Rojo, Selene, StyLua, Aftman, Wally and a CI workflow, preconfiguredesmeril check- verify the tooling configs and structure, get an A-F grade; exit code 1 on a failing grade, safe to gate CI onesmeril deps- auditwally.tomlagainst the registry: outdated, missing and unknown packages; exit code 1 on any problemesmeril doctor- check the local toolchain: rojo, selene, stylua, wally and aftman, with versions and install hintsesmeril update- bumpwally.tomlrequirements to the latest published versions;--writeapplies, dry-run by defaultesmeril fmt- format with StyLua and lint with Selene;--checkonly reportsesmeril build- run check, then build with Rojo (game.rbxlorlib.rbxm)esmeril clean- remove build artifacts (target/,.lune/,*.rbxl,*.rbxm)esmeril info- show project summary: name, version, grade, dependencies and toolchainesmeril tree- show project file tree with config, source and other files categorizedesmeril validate- validate config files quickly without full checkesmeril lint- dedicated linting with selene and stylua;--fixauto-fixesesmeril watch- poll for file changes and auto-run fmt + checkesmeril publish- validate and publish to Wally; dry-run by defaultesmeril scan- static analysis: detect Luau/Roblox anti-patterns and code smells with fix suggestionsesmeril deps-graph- visualize module dependency graph, detect circular dependencies and orphansesmeril dashboard- unified project health overview with grade tracking over timeesmeril sim- static runtime simulation: predict race conditions, memory leaks and performance issues without running codeesmeril add- add a dependency to wally.toml (scope/name@version)esmeril rename- rename the project across all config filesesmeril stats- project statistics: files, lines and breakdown by extensionesmeril benchmark- analyze project performance: code complexity, function sizes and anti-patternsesmeril template- manage project templates: list, show, create from built-in templatesesmeril env- show environment info: OS, tools, versions and PATHesmeril completions <shell>- generate shell completion scripts (bash, zsh, fish, powershell, elvish)
install
From crates.io:
cargo install esmeril
Or download a prebuilt binary for Linux, macOS or Windows from the releases page.
scaffold
esmeril init mygame
cd mygame
aftman install # downloads Rojo, Selene and StyLua
rojo serve # connect from Studio
esmeril init writes the files a professional Roblox workflow needs, all wired together:
default.project.json- Rojo project tree (src/server,src/client,src/shared).luaurc- Luau language mode for the source tree.selene.toml+stylua.toml- lint and format configaftman.toml- pinned Rojo / Selene / StyLua versionswally.toml- package manifest.github/workflows/ci.yml- lint + format + build on every push
Flags: --strict sets the Luau language mode to Strict instead of NonStrict, --lib scaffolds a library package (a single src/init.lua module, ready to publish to Wally) instead of a game, --force overwrites a non-empty target directory, -s / --scope sets the Wally package scope (default: user), --git runs git init and creates an initial commit. The directory name is kebab-cased for the wally.toml package name (esmeril init "My Game" --scope roblox → roblox/my-game), so a scaffolded project always passes its own check. --template selects a specific template (game, lib, strict, strict-lib, place, experience).
check
esmeril check
esmeril check path/to/project
esmeril check --fix
esmeril check --json
esmeril check --markdown
esmeril check --explain
esmeril check validates the project and grades it A-F. --fix creates the standard files that are missing instead of only reporting them - point it at any messy project and watch the grade jump from F to A. It never overwrites an existing file; a config that exists but is invalid is listed as needing manual attention. --explain shows a detailed explanation for each check.
| check | weight | fails when |
|---|---|---|
default.project.json |
15 | missing, invalid JSON, or no name |
| project paths | 10 | a $path target in the tree does not exist |
src/ |
10 | missing |
.luaurc |
10 | missing, invalid JSON, or no valid languageMode (NonStrict/Strict) |
.selene.toml |
15 | missing or invalid TOML |
stylua.toml |
15 | missing or invalid TOML |
aftman.toml |
15 | missing, invalid TOML, or no rojo + selene + stylua as owner/repo@tag under [tools] |
wally.toml |
5 | missing, invalid TOML, or no complete [package] (scoped name, version, registry, realm) |
.github/workflows |
5 | no workflow file |
Missing wally.toml or the CI workflow are recommended, not required - a project without both still grades A (90/100). README.md, .gitignore and whether rojo/selene/stylua are on PATH are shown as info, not scored. --markdown prints the report as a markdown table, ready to paste into a PR or README.
deps
esmeril deps
esmeril deps path/to/project
esmeril deps --offline
esmeril deps --json
esmeril deps --outdated
esmeril deps reads wally.toml and checks every dependency against the package registry (GitHub-hosted indexes only, like the official https://github.com/UpliftGames/wally-index). Dependencies are written in the Wally form scope/name@version; git dependencies and the [server-dependencies]/[dev-dependencies] sections are reported but not scored. Index manifests are cached locally for an hour ($ESMERIL_CACHE overrides the location) and reused on later runs; --offline uses only the cache and fails on packages that are not cached.
Each dependency gets a status:
| status | meaning |
|---|---|
| ok | the newest published version satisfies your requirement |
| outdated | a newer version exists but your requirement excludes it (exit 1) |
| missing | no published version satisfies your requirement (exit 1) |
| not found | package does not exist in the registry (exit 1) |
| error | the registry could not be reached (exit 1) |
| git / unsupported | reported as info, not scored |
--outdated shows only outdated dependencies, hiding ok and other statuses.
Versions follow SemVer: a bare requirement like 1.8.4 behaves as ^1.8.4 (Cargo style); =1.8.4 pins exactly and ~1.8.4 allows patch updates only. latest is the newest stable release - pre-releases like 1.13.0-rc.3 are never considered a target.
update
esmeril update
esmeril update path/to/project --write
esmeril update finds dependencies whose requirement excludes a newer published version and proposes the bump, one line per dependency. It is a dry-run by default - --write rewrites wally.toml in place, preserving comments and formatting. A dependency pinned with =1.8.4 is left alone; a caret requirement like 1.8.4 is bumped to the latest stable, matching what wally update would resolve. Like deps, it uses the local index cache and supports --offline.
fmt
esmeril fmt
esmeril fmt --check
esmeril fmt path/to/project
esmeril fmt runs StyLua and Selene on src/: format and fix by default, --check only reports problems (exit code 1 on any). Missing tools show the install command instead of failing silently.
build
esmeril build
esmeril build path/to/project -o build.rbxl
esmeril build runs the check first and refuses to build a failing project, then calls rojo build. Output defaults to game.rbxl for games and lib.rbxm for libraries; -o overrides.
clean
esmeril clean
esmeril clean removes build artifacts from the current directory: target/, .lune/, *.rbxl, *.rbxlx, *.rbxmx, *.rbxm. Safe to run anywhere.
info
esmeril info
esmeril info path/to/project
esmeril info shows a project summary: package name, version, scope, realm, dependency count, check grade and which tools (rojo, selene, stylua) are on PATH. --json emits a machine-readable report.
tree
esmeril tree
esmeril tree path/to/project
esmeril tree shows the project file tree, categorizing files as config (⚙️), source (📄) or other (📝). Directories are marked with 📁. Hides target/, .lune/, .git and other hidden directories (except .github).
validate
esmeril validate
esmeril validate path/to/project
esmeril validate checks each config file (default.project.json, .luaurc, .selene.toml, stylua.toml, aftman.toml, wally.toml) and reports its status as ok, missing, invalid or unreadable. Faster than check when you only need to verify config validity. Exit code 1 when any file has an error. --json emits a machine-readable report.
lint
esmeril lint
esmeril lint --fix
esmeril lint -f src/init.lua
esmeril lint --tool selene
esmeril lint runs selene and stylua on src/ (or a specific file with -f). By default it checks only; --fix auto-fixes lint issues. --tool selene or --tool stylua runs only one tool. Exit code 1 when a tool fails or is missing. --json emits a machine-readable report.
watch
esmeril watch
esmeril watch -i 2
esmeril watch polls for file changes and auto-runs fmt --check + check when .lua, .luau, or config files are modified. -i / --interval sets the polling interval in seconds (default: 1). Ctrl+C to stop.
publish
esmeril publish
esmeril publish --publish
esmeril publish validates the project (check must pass), then runs wally publish. Dry-run by default; --publish actually publishes to the Wally registry. Exit code 1 on check failure or publish error. --json emits a machine-readable report.
add
esmeril add roblox/treasure@1.2.3
esmeril add roblox/ui@2.0.0 --server
esmeril add roblox/test@3.0.0 --dev
esmeril add roblox/t@1.0.0 --dry-run
esmeril add inserts a dependency into wally.toml under [dependencies]. --server and --dev target [server-dependencies] and [dev-dependencies]. --dry-run shows what would be added without modifying the file. Duplicates are rejected. --json emits a machine-readable report.
rename
esmeril rename my-new-game
esmeril rename "Cool RPG"
esmeril rename updates the project name across wally.toml (package name), default.project.json (project name) and README.md. The name is kebab-cased for wally.toml ("Cool RPG" → cool-rpg). The existing scope is preserved. --json emits a machine-readable report.
stats
esmeril stats
esmeril stats path/to/project
esmeril stats shows project statistics: total files and lines, breakdown by extension with visual bars, and category breakdown (luau, config, ci, docs, etc.). --json emits a machine-readable report.
doctor
esmeril doctor
esmeril doctor checks that the local toolchain is ready: rojo, selene, stylua, wally and aftman. Tools that are installed report their version (tool --version); missing ones show the install command. Exit code 1 when any of the core tools (rojo, selene, stylua) is missing - run it on a fresh machine to see exactly what is left to install.
scan
esmeril scan
esmeril scan path/to/project
esmeril scan performs static analysis on Luau source files, detecting anti-patterns and code smells. Each finding has a severity (critical, warning, hint), a rule name, and an actionable suggestion.
| rule | severity | what it catches |
|---|---|---|
direct-service-access |
critical | game.Workspace instead of game:GetService("Workspace") |
missing-error-handling |
warning | HTTP/DataStore calls without pcall/xpcall |
global-mutation |
warning | mutation of global variables |
shadowed-global |
warning | local game = ... shadows the Roblox global |
service-in-loop |
warning | GetService called inside a loop instead of cached |
deprecated-wait |
warning | wait() instead of task.wait() |
deprecated-spawn |
warning | spawn() instead of task.spawn() |
deprecated-delay |
warning | delay() instead of task.delay() |
deprecated-tick |
warning | tick() instead of os.clock() |
string-concat-loop |
warning | x = x .. y pattern (use table.concat) |
uncached-require |
warning | require() result not stored in a local |
print-in-code |
hint | print() left in production code |
warn-in-code |
hint | warn() left in production code |
todo-comment |
hint | TODO/FIXME/HACK/XXX/TEMP comments |
magic-number |
hint | unexplained numeric literals |
hardcoded-cframe |
hint | CFrame/Vector3 without a comment |
instance-new-no-parent |
hint | Instance.new() without setting Parent |
getservice-in-function |
hint | GetService called inside function bodies |
deep-nesting |
hint | code more than 4 tabs deep |
long-line |
hint | lines over 120 characters |
multiple-statements |
hint | semicolons joining multiple statements |
empty-function |
hint | function with an empty body |
Exit code 1 when any critical issue is found. --json emits a machine-readable report.
deps-graph
esmeril deps-graph
esmeril deps-graph path/to/project
esmeril deps-graph --dot
esmeril deps-graph scans src/ and builds a module dependency graph by analyzing require() calls. It visualizes the graph as ASCII art, resolves script.Parent requires, and reports:
- circular dependencies - modules that depend on each other (exit code 1)
- orphan modules - files that are never required by anything else
- root modules - entry points with no dependencies
--dot outputs Graphviz DOT format (digraph { ... }) for generating diagrams with dot -Tpng graph.dot -o graph.png. --json emits a machine-readable report.
dashboard
esmeril dashboard
esmeril dashboard path/to/project
esmeril dashboard generates a unified health overview combining:
- project grade and score (from check)
- scan findings (critical, warnings, hints)
- dependency status (outdated, broken)
- project stats (files, lines, Luau lines)
- code metrics (function count, average function size, max function size)
- health score (0-100) combining all factors
- grade history and trend
The dashboard records each run as a snapshot in .esmeril/history.json, building a history of project health over time. It shows whether the project is improving, declining, or stable. Exit code 1 when the project has critical issues or a failing grade. --json emits a machine-readable report.
sim
esmeril sim
esmeril sim path/to/project
esmeril sim is a static runtime simulation engine that predicts game behavior without executing code. It scans src/ and generates per-script profiles analyzing complexity, memory usage, and risk patterns.
| category | what it detects |
|---|---|
race-condition |
unsynchronized shared state, missing pcall around HTTP/DataStore, nested async spawns, global variable mutations |
memory-leak |
event connections created inside loops, uncached Instance.new(), recursive functions without base cases |
performance |
GetService called in nested blocks, string concatenation in loops, deprecated wait()/spawn(), uncached require(), Instance.new() without Parent, yields in loops |
load-time |
circular dependencies, large scripts (> 500 lines) |
Each script gets a complexity score based on lines, functions, nesting depth, loops, event connections and requires. Memory is estimated from local variables, Instance.new() calls, event connections and module caches. The overall risk score (0-100) determines the deploy verdict: low (0-20), moderate (21-40), elevated (41-60), high (61-80) or critical (80+). Exit code 1 when the risk score is >= 70. --json emits a machine-readable report.
benchmark
esmeril benchmark
esmeril benchmark path/to/project
esmeril benchmark analyzes project performance characteristics without running code. It scans src/ and measures:
- file sizes - average and maximum lines per file
- function sizes - average and maximum lines per function
- nesting depth - average and maximum indentation levels
- code statistics - functions, loops, conditionals, event connections
- anti-patterns - string concatenation in loops, uncached GetService calls
- hotspots - specific locations that need optimization
Each analysis produces a performance score (0-100) with a verdict: excellent, good, fair, poor, or critical. Hotspots are ranked by severity with actionable suggestions. Exit code 1 when the score is below 50. --json emits a machine-readable report.
template
esmeril template list
esmeril template show game
esmeril template create myproject --template game
esmeril template create mylib --template lib --scope roblox
esmeril template manages project templates:
| template | description | recommended for |
|---|---|---|
game |
Standard Roblox game with server, client and shared | games, experiences, most projects |
lib |
Library package ready for Wally publishing | reusable modules, packages |
strict |
Game with Strict Luau language mode | type-safe projects, larger codebases |
strict-lib |
Library with Strict mode | type-safe libraries, API packages |
place |
Game with place.json for Studio publishing | published places, Studio integration |
experience |
Full experience with services, systems, controllers | large games, complex architecture |
esmeril template list shows all available templates. esmeril template show <name> displays file list and details. esmeril template create <name> creates a new project. --scope sets the Wally package scope (default: user). --json emits a machine-readable report.
env
esmeril env
esmeril env shows environment information:
- system - OS, architecture, shell, home directory, config directory
- versions - esmeril version, Rust version (if installed)
- tools - presence, version, and PATH for rojo, selene, stylua, wally, aftman, lune
- PATH - relevant directories (aftman, cargo, tool dirs)
Useful for debugging installation issues and sharing your environment when reporting bugs. --json emits a machine-readable report.
verbose mode
esmeril -v check
esmeril --verbose init mygame
The global --verbose / -v flag enables verbose output. When active, esmeril shows a banner with version information at the start of each command. More verbose features may be added in future versions.
exit codes
esmeril check exits 0 when the grade is A, B or C, and 1 when it is D or F - including when a $path in default.project.json points at a directory that does not exist. esmeril deps exits 1 when any dependency is outdated, missing, not found or errored. esmeril update exits 1 when a dependency cannot be checked. esmeril fmt exits 1 when a tool is missing or a check fails. esmeril build exits 1 when check or the Rojo build fails. esmeril doctor exits 1 when a core tool is missing. esmeril check --fix exits with the grade after fixing. esmeril validate exits 1 when any config file has an error. esmeril lint exits 1 when a tool fails or is missing. esmeril publish exits 1 on check failure or publish error. esmeril scan exits 1 on critical issues. esmeril sim exits 1 when risk score >= 70. esmeril benchmark exits 1 when score < 50. That makes them safe to gate CI on. On Windows PowerShell use $LASTEXITCODE to read it - $? is a boolean there and prints False for a non-zero exit.
why
Setting up a professional Roblox workflow means installing and configuring seven separate tools - Rojo, Selene, StyLua, Aftman, Wally, a language mode and CI - by hand, each with its own docs. esmeril is one binary and a few flags: esmeril init produces the whole setup, esmeril check keeps it honest (and --fix repairs it), esmeril fmt formats and lints, esmeril lint lints with --fix, esmeril build compiles it, esmeril deps keeps dependencies current, esmeril update bumps them, esmeril add installs new ones, esmeril publish ships to Wally, esmeril rename renames the project, esmeril watch auto-checks on save, esmeril validate verifies configs fast, esmeril stats shows the codebase at a glance, esmeril scan catches anti-patterns, esmeril deps-graph visualizes module dependencies, esmeril dashboard gives a unified health overview with history, esmeril sim predicts runtime issues, esmeril benchmark analyzes performance, esmeril template manages project scaffolds, and esmeril doctor verifies the machine. esmeril env shows your environment.
license
MIT