Meta and Utility Commands

Meta and Utility Commands

Commands that inspect configuration, discover schema, manage shell completion, or simulate runs without doing real work.

--install

Install all packages declared in reqpack { ... } via ReqPack, then exit. Does not run a workflow, task, or step.

beez --install
beez --install --dry-run    # print rqp command only

Requires build.lua and rqp on PATH. See ReqPack Declaration.

On normal runs (without --install), Beez installs only plugins whose declaration changed (cache under .cache/reqpack/).

--dry-run

Loads and executes build.lua, builds the execution graph, and logs progress, but does not run shell commands or Lua step callbacks.

beez build --dry-run
beez -s compile --dry-run

Behavior:

• build.lua is loaded and the registry is built (same as a normal run)
• Shell steps: progress line shown, command not executed
• Lua callbacks: progress line shown, function not called
• Step cache lookups are skipped
• Unknown targets, steps, or ordering errors still fail (only execution is skipped)

Use to verify which steps would run without side effects.

--show-config

Prints the merged active configuration and the source of each value (global, project, default, CLI).

beez --show-config

Requires build.lua in the current directory (project config is loaded from it).

See Configuration Overview.

--config-options

Lists config schema keys or enum values. Does not require build.lua.

beez --config-options
beez --config-options cache
beez --config-options cache.compress.algorithm

Path given	Output
(none)	Top-level keys: performance, cache, ui, env
Object path	Child keys and types
Enum leaf	Allowed enum values

Unknown paths print an error and exit 1.

--complete-config-options

Internal helper for shell tab completion. Lists config paths matching an optional prefix.

beez --complete-config-options
beez --complete-config-options performance.

Does not require build.lua.

--dump-completion

Prints a completion script to stdout.

beez --dump-completion bash
beez --dump-completion zsh

Supported shells: bash, zsh only. Other values are a parse error.

--install-completion

Registers tab completion in your shell rc file (~/.bashrc or ~/.zshrc).

beez --install-completion

Does not require build.lua. Does not require make install-beez.

-j / --threads

Sets performance.max_threads for one run. Range: 1 to 1024. Default when omitted: CPU core count.

beez build -j 4
beez build --threads 1    # sequential within each parallel level

See Performance Settings.

Pass-through: -- user-options

Arguments after -- are stored in userOptions but not used by Beez today. Reserved for future custom tooling or step pass-through.

beez build -- -j8 release

Parsed as userOptions = ["-j8", "release"].

Commands that need build.lua

Command	Runs target after?
--show-config	No
--clean-cache	Only if target/-p/-s also given
--update	Only if target/-p/-s also given
--install	No
--list	No

Commands without build.lua

Command
--help, --version
--config-options
--complete-config-options
--dump-completion
--install-completion

Next steps

• CLI Overview - invocation priority
• ReqPack Declaration - reqpack { ... } and --install
• Configuration - config file format
• CLI Flag Reference - full table