Dev Server

Three commands cover the inner dev loop: wheels start brings a development server up, wheels stop takes it down, and wheels reload reinitializes the running application without restarting the JVM. You’ll compose these every day while iterating on a Wheels app.

You’ll use this for:

• Running your Wheels app locally while you work on it.
• Stopping the dev server cleanly when you’re done — or before switching branches.
• Reinitializing framework state (routes, settings, DI bindings) after edits that require a full app reload without killing the JVM.

Overview

wheels start is the preferred way to run a Wheels app during development. It wraps LuCLI’s lower-level wheels server start with Wheels-specific bootstrap — forwarding any extra flags through to the underlying server command so things like --port and --version still work. wheels stop is a thin wrapper around wheels server stop for the project directory. wheels reload is Wheels-specific: it talks to the running app over HTTP rather than restarting anything.

Two commands named similarly

wheels start (Wheels module) and wheels server start (LuCLI core) are related but distinct surfaces. wheels start is the short, Wheels-aware form you’ll reach for 99% of the time. wheels server is LuCLI’s general-purpose server manager and exposes more subcommands (status, list, restart, log, and so on). See the LuCLI server reference for the full surface.

wheels start

Start a Wheels development server for the current project. Delegates to wheels server start under the hood and forwards extra flags to it.

Synopsis

"

wheels start [flags]

wheels start handles --port, --force, --engine and --dry-run itself. Every other flag is forwarded verbatim to wheels server start; the common ones are listed below. See wheels server start for the full list.

Flags handled by wheels start

Flag	Description
-p, --port=<port>	Port number for the server (e.g., 8080). wheels start writes the port, and a free shutdown port, into lucee.json, so later starts reuse it. -p <port> and -p=<port> are the same as --port.
--force	Replace a stopped server registration that belongs to another project with the same server name. It does not restart a running server.
--engine=<engine>	The engine to run (default lucee). See wheels server start.
--dry-run	Show the resolved configuration without starting the server. Nothing is written: a --port value is passed to the dry run instead of into lucee.json. Not supported with --engine=rustcfml.

Flags forwarded to wheels server start

Flag	Description
-n, --name=<name>	Custom name for the server instance.
-v, --version=<version>	Lucee version to use (e.g., 6.2.2.91).
-e, --env, --environment=<env>	Apply the matching environments profile from lucee.json (e.g., dev, staging, prod). An explicit --env/--environment value wins.
-c, --config=<file>	Configuration file to use (defaults to lucee.json).
--disable-open-browser	Don’t open a browser after the server starts.
--sandbox	Start a transient background server without writing lucee.json.

Example

example

wheels start

Prints Starting Wheels server... in cyan and hands control off to wheels server start in the current project directory. The server runs in the background and the command returns once the server is up, leaving your terminal free.

If the port in lucee.json is already taken, wheels start stops before starting anything. It names the Wheels server that holds the port, when it’s one of yours, with the cd <its folder> && wheels stop to free it, and suggests a free port to pass as wheels start --port=<port>.

Background process

wheels start returns control to your shell once the server is up — it does not block the terminal. Stop the server with wheels stop. Running wheels start while the server is already up prints Server '<name>' is already running. and exits 0. It doesn’t restart the server or change lucee.json, even with --force; restart with wheels stop && wheels start.

wheels stop

Stop the running Wheels development server for the current project.

Synopsis

"

wheels stop [--name=<name>] [--config=<file>] [--all]

With no flags, resolves the server instance from the project directory and asks LuCLI to stop it. Under the hood it runs wheels server stop scoped to the project root.

Flag	Description
--name=<name>	Stop the named server instance. Use it when more than one server is registered to the project directory (wheels server list shows them). --name <name> also works.
--config=<file>	Resolve the server name from a lucee*.json file (e.g. lucee-docker.json).
--all	Stop every running Lucee server on the machine.

Since 4.1.1 these flags are forwarded to wheels server stop; earlier releases ignored them.

Example

illustrative — requires running server

wheels stop

Prints Stopping Wheels server... in cyan and delegates to wheels server stop. Run it from the project root to take down the background server that wheels start brought up.

Stopping by name or all at once

wheels stop --name=<name> and wheels stop --all are equivalent to the core commands wheels server stop --name=<name> and wheels server stop --all. See the server reference for the rest of the server-management flags.

wheels reload

Reinitialize the running Wheels application without restarting the JVM. Useful after edits to config/settings.cfm, config/routes.cfm, config/services.cfm, or any file that is only read during framework bootstrap.

Synopsis

"

wheels reload [--password=<pw>]

wheels reload finds the port of this project’s own running server (the one wheels start registered) and hits http://localhost:<port>/?reload=true&password=<password> with the reload password it finds in your project config (.env, then config/settings.cfm). Pass --password=<pw> to override the detected password. If this project’s server isn’t running, it prints Reload requires this project's own server (started with: wheels start). and exits with a non-zero status.

Why the CLI doesn't re-prompt for the reload password

The reload password gates the HTTP endpoint ?reload=true — it’s an ACL against remote attackers who could otherwise hit that URL and wipe your app’s state. The CLI runs locally, has filesystem access to your project, and reads the configured password directly from .env or config/settings.cfm. Re-prompting you for a password the tool just read from disk wouldn’t add security: an attacker with disk read would already have the password.

This matches how Rails (no reload password concept; bin/rails restart/deploy tooling instead), Laravel (php artisan optimize:clear and friends never authenticate), Symfony (bin/console cache:clear), Django (manage.py runserver/migrate), and Phoenix (mix phx.server) treat the CLI/HTTP boundary. The CLI carries owner-of-the-project trust by definition.

If you need to keep wheels reload itself behind a credential check (e.g. a shared dev box where multiple users have shell access), gate it at the OS level with file permissions on .env. See Security Hardening — Reload password for the full threat model.

Example

illustrative — requires running server

wheels reload

On success: Application reloaded successfully. in green. On a password mismatch the server serves the page normally instead of redirecting, and the command prints Reload was not triggered: the server served the page normally (HTTP 200) instead of answering with the reload redirect (302). The application was NOT reloaded — check the reload password. If the request itself fails it prints Failed to reload: <message>. Both exit with a non-zero status; when no password was found, it also hints at setting WHEELS_RELOAD_PASSWORD in .env or config/settings.cfm.

When you need reload

Most CFML source changes are picked up on the next request without a reload. In development, changes to app/global/functions.cfm (and any files it <cfinclude>s) are also auto-detected on bare ?reload=true (the reloadOnGlobalChange setting). You need wheels reload when you change config that’s only read at bootstrap — routes, settings, DI bindings, package manifests — or when you want to force every per-request cache to clear.

Dev loop example

The three commands compose into a typical inner loop:

illustrative — dev loop example

# Bring the server up — it runs in the background and returns control
wheels start

# Iterate on your app
# For most CFML edits: just save the file and hit refresh.
# For config/routes/services changes, force a reload:
wheels reload

# When you're done for the day
wheels stop

Related commands

Quick Start The fastest path from install to a running Wheels app.

Creating a Project wheels new — scaffolds the project that wheels start boots.

LuCLI `server` The lower-level server surface that wheels start and wheels stop wrap.

Configuration Environment files, reload passwords, and settings that wheels reload reinitializes.