CLI Reference

Synopsis

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

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]	Preprocessor define. Repeatable.
-I, --include-path <path>	Include search path. Repeatable.
--use-workspace	Auto-load includes and defines from a build-system config (codexx.workspace.yaml or CMake file-api). Default workspace root is the CWD. Requires Professional or Team licence — emits E102 and exits otherwise.
--workspace-dir <path>	Override workspace root for --use-workspace.

When --use-workspace is active, includes and defines from the build-system config are merged with any explicit -I / -D. Manual -D flags take precedence over workspace defines (warning W002); inputs not found in the build-system config emit warning W001.

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>	Append a substring to the HTTP allowlist for every loaded rule. 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. Available on every licence tier; intended for CI and LLM-driven workflows.
--show-tui	off	With --dry-run, opens the interactive FTXUI diff viewer instead of printing plain output. Requires a Professional+ licence; on Community tier emits E102 and falls back to a filename list.
-v, --verbose	off	Per-entity progress log.
-c, --config <path>	(unused)	Generic profile-config slot inherited from the support CLI; codegen does not currently consume this value.
-p, --profile <name>	(unused)	Generic named-profile slot inherited from the support CLI; not currently consumed.
-h, --help	—	Print usage and exit 0.

Debugger flags (only present when built with LUAU_ENV_ENABLE_DEBUGGER)

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.

The Professional-tier vscode_dap_debugger capability is not currently enforced at runtime — when the binary is built with the debugger enabled, --debug works on any tier. The licence gate ships in a future release.

License subcommands

codegen license check              Show current licence status
codegen license fingerprint        Print this machine's fingerprint

The license subcommand short-circuits the regular pipeline (no rules are loaded). Activation and deactivation moved to the CodeXX DTDK manager (codexx_dtdk_manager); codegen license activate / deactivate now print a pointer to the manager and exit non-zero. Output formats:

$ codegen license check
License valid.
  Tier:    Professional
  Email:   user@example.com
  Offline: yes (cached token)
  Expiry:  2026-12-31T23:59:59Z          # only if the licence carries an expiry

$ codegen license fingerprint
<64-char hex SHA-256>

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, licence 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

# Build-system integration: pull includes/defines from CMake or workspace YAML
codegen --use-workspace --workspace-dir . -i src/api.hpp -a TypeScriptTypes

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

# Interactive TUI diff viewer (Professional+ licence)
codegen -i ./include -a ToString --dry-run --show-tui

# Manual preprocessor flags + HTTP allowlist override
codegen -i ./include -a SchemaSync \
        -I third_party/include -D BUILD_FEATURE=1 \
        --allow-http "https://schema.example.com/"