CLI Reference

Synopsis

codegen -i <input> [-r <rules-dir>] -a <RuleName> [-a <RuleName>...] [OPTIONS]

Rules are loaded from <rules-dir>/<RuleName>/ for each -a on the command line. The rules directory defaults to .codegen/rules. The input is a single header or a directory (recursively scanned for .h / .hpp).

Required flag

Flag	Description
-i, --input <path>	Input file or directory

-a is required in practice — without it the engine has no rules to run.

Rule selection

Flag	Default	Description
-a, --attribute <name>	(none)	Rule (attribute) name to process. Repeatable.
-r, --rules-dir <path>	.codegen/rules	Root directory containing rule subfolders.

Preprocessor / parser

Flag	Description
-D, --define NAME[=VALUE]	Inert. Parsed into defines but never read; ADR-075 Phase B removed build-system probing. Repeatable.
-I, --include-path <path>	Inert. Same as -D — parsed, never read. Repeatable.
--workspace-dir <path>	Project root for the workspace daemon connection. Defaults to the current directory.

Source analysis always goes through the workspace daemon — there is no one-shot fallback pipeline and no flag to turn analysis on or off. The daemon must already be serving the root at <root>/.codexx/daemon.sock (codegen never auto-spawns it); if it isn’t reachable the run fails with E018. --workspace-dir only selects which root to connect to.

Permissions / params

Flag	Description
-P, --param KEY=VALUE	Override params:<KEY> for every loaded rule. Value is parsed as JSON when possible, otherwise stored as a string. Repeatable.
--allow-http <pattern>	Merge a host pattern into the HTTP allowlist for every loaded rule. * matches any host, *.example.com matches subdomains only (not the apex); otherwise the pattern is matched by exact host equality, not URL substring. Repeatable.
--allow-env <NAME>	Append an OS env name to the env allowlist for every loaded rule. Repeatable.
--env KEY=VALUE	Override a dotenv entry. Repeatable; takes precedence over per-rule and shared .env.

Run-mode flags

Flag	Default	Description
--dry-run	off	Don’t write outputs. Emits a unified diff (zero context, --- a/... / +++ b/... / @@) of every would-be file change to stdout. Intended for CI and LLM-driven workflows.
-B, --browse-rules-registry	off	Opens the interactive rules registry browser and exits; installs into -r (default .codegen/rules). Takes no -i.
--show-tui	off	Opens the interactive FTXUI diff viewer instead of printing plain output. Only consulted when --dry-run is also set — silently ignored otherwise. Accepting a change in the viewer writes the files.
-v, --verbose	off	Per-entity progress log.
--version	—	Print the channel-qualified version (e.g. insider/codegen@0.1.0-rc.1) and exit 0. Handled before argument validation, so it needs no -i.
-c, --config <path>	(unused)	Inert. Generic profile-config slot inherited from the support CLI; parsed, never read.
-p, --profile <name>	(unused)	Inert. Generic named-profile slot inherited from the support CLI; parsed, never read.
-h, --help	—	Print usage and exit 0.

Debugger flags

Flag	Default	Description
--debug	off	Enable the LuaU DAP server; the engine blocks until an IDE attaches.
--debug-port <port>	50001	TCP port the DAP server listens on.
--debug-source-root <path>	absolute path to --rules-dir	Source root reported to the IDE for file navigation.

These flags sit behind the LUAU_ENV_ENABLE_DEBUGGER compile-time macro, but shipped builds link luau_environment_dbg, which defines that macro publicly — so in practice the debugger flags are always present and free on every build.

Exit codes

Code	Meaning
0	Success — all entities processed and all files written (or the dry-run preview completed).
1	Recoverable failure — bad CLI, missing input, rule load failure, preamble error, etc.
2	Fatal — handler internal error or LuaU environment creation failure.

Examples

# Run one rule against a directory of headers
codegen -i ./include -r .codegen/rules -a ToString

# Multiple rules in one invocation
codegen -i ./include -a ToString -a MarkdownDocs

# Point at a workspace daemon serving a different project root
codegen --workspace-dir . -i src/api.hpp -a TypeScriptTypes

# Dry-run preview (unified diff to stdout — ideal for CI / LLMs)
codegen -i ./include -a ToString --dry-run

# Interactive TUI diff viewer
codegen -i ./include -a ToString --dry-run --show-tui

# Browse the rules registry and install a rule (no input file needed)
codegen --browse-rules-registry

# HTTP allowlist override (host-matched, not URL substring)
codegen -i ./include -a SchemaSync \
        --allow-http "schema.example.com"