esmeril 0.5.0

Scaffold, validate, format, audit and build Roblox Luau projects from the terminal
esmeril-0.5.0 is not a library.

esmeril

crates.io downloads License CI

Scaffold, validate, format, audit and build Roblox Luau projects from the terminal.

Twenty-five commands, one binary:

  • esmeril init (or esmeril new) - scaffold a modern Roblox project: Rojo, Selene, StyLua, Aftman, Wally and a CI workflow, preconfigured
  • esmeril check - verify the tooling configs and structure, get an A-F grade; exit code 1 on a failing grade, safe to gate CI on
  • esmeril deps - audit wally.toml against the registry: outdated, missing and unknown packages; exit code 1 on any problem
  • esmeril doctor - check the local toolchain: rojo, selene, stylua, wally and aftman, with versions and install hints
  • esmeril update - bump wally.toml requirements to the latest published versions; --write applies, dry-run by default
  • esmeril fmt - format with StyLua and lint with Selene; --check only reports
  • esmeril build - run check, then build with Rojo (game.rbxl or lib.rbxm)
  • esmeril clean - remove build artifacts (target/, .lune/, *.rbxl, *.rbxm)
  • esmeril info - show project summary: name, version, grade, dependencies and toolchain
  • esmeril tree - show project file tree with config, source and other files categorized
  • esmeril validate - validate config files quickly without full check
  • esmeril lint - dedicated linting with selene and stylua; --fix auto-fixes
  • esmeril watch - poll for file changes and auto-run fmt + check
  • esmeril publish - validate and publish to Wally; dry-run by default
  • esmeril scan - static analysis: detect Luau/Roblox anti-patterns and code smells with fix suggestions
  • esmeril deps-graph - visualize module dependency graph, detect circular dependencies and orphans
  • esmeril dashboard - unified project health overview with grade tracking over time
  • esmeril sim - static runtime simulation: predict race conditions, memory leaks and performance issues without running code
  • esmeril add - add a dependency to wally.toml (scope/name@version)
  • esmeril rename - rename the project across all config files
  • esmeril stats - project statistics: files, lines and breakdown by extension
  • esmeril benchmark - analyze project performance: code complexity, function sizes and anti-patterns
  • esmeril template - manage project templates: list, show, create from built-in templates
  • esmeril env - show environment info: OS, tools, versions and PATH
  • esmeril 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 config
  • aftman.toml - pinned Rojo / Selene / StyLua versions
  • wally.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