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]

Any flags you pass are forwarded verbatim to wheels server start. The common ones are listed below — see wheels server start for the full list.

Flags (forwarded to wheels server start)

Flag	Description
-p, --port=<port>	Port number for the server (e.g., 8080).
-n, --name=<name>	Custom name for the server instance.
-v, --version=<version>	Lucee version to use (e.g., 6.2.2.91).
--env, --environment=<env>	Environment to use (e.g., dev, staging, prod).
-c, --config=<file>	Configuration file to use (defaults to lucee.json).
-f, --force	Force a restart, replacing any server already running for this project.
--disable-open-browser	Don’t open a browser after the server starts.
--dry-run	Show the resolved configuration without starting the server.
--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.

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, and force a restart over an already-running instance with wheels start -f (or --force).

wheels stop

Stop the running Wheels development server for the current project.

Synopsis

wheels stop

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.

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

To stop a server by explicit name or to stop every running Lucee server on the machine, drop down to the core command: wheels server stop --name=<name> or wheels server stop --all. See the server reference.

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

wheels reload detects the running server’s port automatically (from lucee.json, then .env) and hits http://localhost:<port>/?reload=true&password=<password> with the reload password it finds in your project config. If no server is running, it prints No running Wheels server detected. Start one with: wheels start and exits.

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 failure — most often a password mismatch — it prints Failed to reload: <message> and 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.