Server

wheels server is LuCLI’s server management command group. It boots and controls real Lucee server instances — one or many, each with its own name, port, Lucee version, and configuration. The wheels binary inherits this surface directly from LuCLI, so every subcommand is available whether you installed LuCLI standalone or pulled it in through the Wheels distribution.

You’ll use this for:

• Managing multiple named server instances side-by-side (e.g. one per project, one per Lucee version).
• Pinning an explicit Lucee version for reproducible local runs.
• Tailing server, access, or error logs without hunting through ~/.lucli/servers/<name>/logs.
• Inspecting the running state of every server on your machine from one place.

Overview

wheels server comes from LuCLI itself — it is not part of the Wheels module. The project-centric commands you use daily (wheels start, wheels stop) are thin wrappers that forward to wheels server start and wheels server stop scoped to the current project directory. Drop down to wheels server directly when you need advanced control: naming, multi-instance management, explicit version pinning, or log inspection. For the typical inner-loop flow, see the project wrapper at Dev Server.

`servers` is an alias

wheels servers and wheels server are the same command. Use whichever reads better for you.

Synopsis

synopsis

wheels server <subcommand> [flags]

Calling wheels server without a subcommand prints the help summary and exits.

start

Boot a Lucee server instance in the background for the current (or specified) project directory.

Synopsis

synopsis

wheels server start [PROJECT_DIR] [flags]

Flags

Flag	Description
-v, --version=<version>	Lucee version to use (e.g. 6.2.2.91).
-n, --name=<name>	Custom name for the server instance.
-p, --port=<port>	Port number for the server (e.g. 8080).
-f, --force	Force replace an existing server with the same name.
-c, --config=<file>	Configuration file to use (defaults to lucee.json).
--env, --environment=<env>	Environment to use (e.g. dev, staging, prod).
--dry-run	Show the resolved configuration without starting the server.
--create-config	Generate server configuration and exit without starting the server.
--sandbox	Start a transient background server without writing lucee.json or persisting the instance.
--webroot=<path>	Override the webroot relative to the project directory.
--source=<dir>	Server template/source directory (defaults to the vendor distribution for the selected version).
--dest=<dir>	Server instance directory to write configuration into.
--disable-open-browser	Disable automatic browser opening after the server starts.
--open-browser[=true|false]	Explicitly control browser opening (default: true).
--disable-lucee / --enable-lucee	Toggle the Lucee CFML engine for this start (mutually exclusive).
--warmup	Enable Lucee warmup (sets LUCEE_ENABLE_WARMUP=true).
--prewarm	Pre-download runtime artifacts (Lucee Express/JAR) and exit without starting.
--no-agents	Disable all Java agents.
--agents=<ids>	Comma-separated list of agent IDs to include.
--enable-agent=<id>	Enable a specific agent by ID (repeatable).
--disable-agent=<id>	Disable a specific agent by ID (repeatable).
--include-lucee	Include Lucee CFConfig in --dry-run output.
--include-tomcat-web	Include Tomcat web.xml in --dry-run output.
--include-tomcat-server	Include Tomcat server.xml in --dry-run output.
--include-https-keystore-plan	Include HTTPS keystore plan in --dry-run output.
--include-https-redirect-rules	Include HTTPS redirect rules in --dry-run output.
--include-all	Include every available --dry-run preview.

Example

example

wheels server start --name=dev --version=6.2.2.91 --port=8080

Sample output:

Starting Lucee server 'dev' on port 8080...
Lucee version: 6.2.2.91
Server started successfully. Visit: http://localhost:8080/

run

Same as start, but runs the server in the foreground with log streaming. Useful when you want to keep the process attached to the terminal and hit Ctrl+C to stop it. Flags mirror start minus the --dry-run / --include-* preview set and --create-config.

Synopsis

synopsis

wheels server run [PROJECT_DIR] [flags]

stop

Terminate a running Lucee server instance.

Synopsis

synopsis

wheels server stop [flags]

Flags

Flag	Description
-n, --name=<name>	Name of the server instance to stop.
-c, --config=<file>	Configuration file to resolve the server name from (e.g. lucee-docker.json).
--all	Stop every running Lucee server on the machine.

Example

example

wheels server stop --name=dev

Sample output:

Stopping server 'dev'...
Server 'dev' stopped.

restart

Stop and then start a named server instance.

Synopsis

synopsis

wheels server restart [flags]

Flags

Flag	Description
-n, --name=<name>	Name of the server instance to restart.
-c, --config=<file>	Configuration file to resolve the server name from.

status

Report whether a server is running, along with port and process metadata.

Synopsis

synopsis

wheels server status [flags]

Flags

Flag	Description
-n, --name=<name>	Name of the server to check.
-c, --config=<file>	Configuration file to resolve the server name from.

Example

example

wheels server status --name=dev

Sample output:

Server: dev
Status: RUNNING
Port: 8080
PID: 42117
URL: http://localhost:8080/

list

List every configured server instance known to LuCLI.

Synopsis

synopsis

wheels server list [flags]

Flags

Flag	Description
-r, --running	Only show currently running instances.

Example

example

wheels server list

Sample output:

NAME          STATUS    PORT    VERSION       DIRECTORY
dev           RUNNING   8080    6.2.2.91      /Users/you/projects/app
scratchpad    STOPPED   8081    6.2.0.280     /Users/you/projects/scratch

log

View or follow logs for a named server instance.

Synopsis

synopsis

wheels server log [flags]

Flags

Flag	Description
-n, --name=<name>	Name of the server instance.
-f, --follow	Follow log output (like tail -f).
-t, --type=<type>	Log type: server, access, or error.

Example

example

wheels server log --name=dev --follow

Streams the server log until you hit Ctrl+C. Swap in --type=error for just the error log or --type=access for the request log.

info

Show a server configuration overview without starting anything. Useful for verifying what start will do before committing to it.

Synopsis

synopsis

wheels server info [PROJECT_DIR] [flags]

Flags

Flag	Description
-c, --config=<file>	Configuration file to use (defaults to lucee.json).
--env, --environment=<env>	Environment to use.
--webroot=<path>	Override the webroot.

env

Print the effective environment variables LuCLI will hand to the server — the merge of system environment, envFile, and envVars.

Synopsis

synopsis

wheels server env [flags]

Flags

Flag	Description
-d, --directory=<dir>	Project directory (defaults to current directory).
-c, --config=<file>	Configuration file to use.
--env, --environment=<env>	Environment to resolve.
--global	Include the full system environment in addition to envFile/envVars.

open

Open an already-running server instance in your default browser.

Synopsis

synopsis

wheels server open [flags]

Flags

Flag	Description
-n, --name=<name>	Name of the server to open (defaults to current directory).

prune

Remove stopped server instances from LuCLI’s registry.

Synopsis

synopsis

wheels server prune [flags]

Flags

Flag	Description
-a, --all	Remove every stopped server.
-n, --name=<name>	Remove a specific stopped server by name.
-c, --config=<file>	Configuration file to resolve the server name from.
-f, --force	Skip the confirmation prompt and attempt to stop the server before pruning.

new

Create a new lucee.json for this project (or edit the existing one) in the interactive config editor.

Synopsis

synopsis

wheels server new [flags]

Flags

Flag	Description
-d, --directory=<dir>	Project directory (defaults to current directory).
-f, --file=<file>	Configuration file (defaults to lucee.json in the project directory).
--env, --environment=<env>	Environment to apply.

edit

Open an existing lucee.json in the same interactive editor as new. Errors if the file does not exist.

Synopsis

synopsis

wheels server edit [flags]

Flags

Flag	Description
-d, --directory=<dir>	Project directory (defaults to current directory).
-f, --file=<file>	Configuration file (defaults to lucee.json).
--env, --environment=<env>	Environment to apply.

lock / unlock

Lock the server configuration for a given environment to a lucee-lock.json — or remove an existing lock. Useful for pinning a reproducible server layout in CI or production.

Synopsis

synopsis

wheels server lock [flags]
wheels server unlock [flags]

Flags (lock)

Flag	Description
-d, --directory=<dir>	Project directory.
--env, --environment=<env>	Environment to lock.
-c, --config=<file>	Configuration file to lock (defaults to lucee.json).
--update	Update an existing lock from the current configuration.

Flags (unlock)

Flag	Description
-d, --directory=<dir>	Project directory.
--env, --environment=<env>	Environment to unlock.

config get / config set

Read or write values in lucee.json without opening the interactive editor. Handy for scripting.

Synopsis

synopsis

wheels server config get <key> [flags]
wheels server config set <key=value> [<key=value> ...] [flags]

Flags (config get)

Flag	Description
-d, --directory=<dir>	Project directory.
--env, --environment=<env>	Environment to use.
-c, --config=<file>	Configuration file to use.

Flags (config set)

Flag	Description
-d, --directory=<dir>	Project directory.
--dry-run	Show what would be set without saving.

Example

example

wheels server config get port
wheels server config set port=8081 admin.enabled=false

Top-level `get` / `set` shortcuts

wheels server get <key> and wheels server set <key=value> are shortcut aliases for the config get / config set forms above.

monitor

Attach to a running server’s JMX endpoint and stream live performance metrics.

Synopsis

wheels server monitor [flags]

Flags

Flag	Description
-n, --name=<name>	Name of the server instance to monitor.
-h, --host=<host>	JMX host (default: localhost).
-p, --port=<port>	JMX port (default: 8999).
-r, --refresh=<seconds>	Refresh interval in seconds (default: 3).

Common workflows

Three recipes you’ll reach for often.

Start with a pinned version and a name

wheels server start --name=dev --version=6.0.1.103

Boots a background server named dev on Lucee 6.0.1.103. The name makes it addressable from every other subcommand (status --name=dev, log --name=dev, stop --name=dev).

Tail logs for an active server

wheels server log --name=dev --follow

Streams the server log until you Ctrl+C. Add --type=error for just the error log or --type=access for request logging.

Inventory and shut down

wheels server list
wheels server stop --name=dev

list prints every known server and its state. Pick the name you want and stop it — or use wheels server stop --all to take every running server down at once.

wheels server vs wheels start

Which one should I use?

• wheels start — Wheels project wrapper. Auto-scoped to the current project’s lucee.json, minimal ceremony, exactly what you want for the day-to-day dev loop. See Dev Server.
• wheels server start — LuCLI native. Full control over naming, version pinning, environments, and multi-instance layout. Reach for this when you need named servers, multiple Lucee versions running at once, or cross-project administration (e.g. list, prune, monitor).

Under the hood wheels start just forwards to wheels server start inside the project directory, so any flag you can pass here works there too.

Related commands

Dev Server wheels start / wheels stop / wheels reload — the project-scoped wrapper around wheels server.

Configuration lucee.json, environments, and the config fields wheels server start reads.

Installation How to install LuCLI / the wheels binary that exposes this command group.

MCP Integration Drive wheels_* tools (including server control) from an AI IDE via LuCLI's stdio MCP.