TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/nuejs/nue/llms.txt
Use this file to discover all available pages before exploring further.
nue CLI is the single entry point for every project task in Nue. You start the development server, build for production, preview the output, and scaffold new projects — all from the same command. Flags and file-match patterns let you narrow what gets built and how output is reported.
Syntax
file_matches are extension or filename fragments passed after the command. They tell the build step to process only files whose names contain those strings. Both patterns may appear together:
Commands
serve / dev
Start the development server with live-reload.
serve and dev are aliases for the same command. Running nue with no command also defaults to serve mode.build
Build a production-ready site into the
.dist directory. Sets is_prod = true, which activates the production configuration block.preview
Serve the already-built
.dist directory so you can verify the production output before deploying.create
Scaffold a new project from a starter template. Accepts a template name and an optional target directory.
serve / dev
Starts a local development server from the current directory. Any change to a source file triggers an incremental rebuild and a hot-reload signal to all connected browsers.serve requires a site.yaml file or an index.md / index.html in the working directory. If neither is found, Nue exits with Not a Nue directory.build
Compiles all sources into.dist. The is_prod flag is set to true, which causes the production block inside site.yaml to be merged into meta.
preview
Serves.dist on a local HTTP server so you can inspect the production output:
create
Scaffolds a new project. The first positional argument is the template name; the second optional argument sets the output directory.Flags
Global flags
Print the usage message and exit. No other work is performed.
Print the Nue version and the Bun runtime version, then exit.
Suppress all output messages. Useful in CI pipelines where you want to check only the exit code.
Emit detailed per-file progress information during a build or serve run.
Server flags
Override the port used by
serve or preview. The value is read from the next positional argument after the flag.Build flags
Print a list of files that would be built without actually writing anything to disk. Useful for verifying which files a match pattern selects.
Rebuild the Nue runtime files inside
.dist/@nue. You rarely need this; it runs automatically as part of a normal build.Delete the entire
.dist directory before building. Use this when you want a guaranteed clean output with no stale artifacts.File match patterns
Any positional arguments that appear after the command and flags are treated as file-match strings. The build step skips every file whose path does not contain at least one of the patterns.Argument parsing details
Nue’s argument parser (getArgs) expands combined short flags before processing. -np expands to -n -p, so compact flag clusters work as expected:
serve, dev, build, preview, create, push). The first token that matches this list sets the command; everything else is a flag or file-match pattern.
Exit behavior
| Situation | Exit |
|---|---|
--help printed | 0 (clean) |
--version printed | 0 (clean) |
| Not a Nue directory | Logs error, exits |
| Unknown flag | Throws Unknown option: "…" |
--port flag with no value | Throws port not set |