wheels environment
Display or switch the current Wheels environment.
Synopsis
wheels environment [action] [value] [options]
Description
The wheels environment
command manages your Wheels application environment settings. It can display the current environment, switch between environments, and list all available environments. Environment changes can trigger automatic application reloads to ensure your settings take effect immediately.
Arguments
action
action
Type: String
Default:
show
Options:
show
,set
,list
Description: Action to perform
Example:
wheels environment set production
value
value
Type: String
Description: Environment value when using set action
Options:
development
,testing
,production
,maintenance
Example:
wheels environment set development
Options
--reload
--reload
Type: Boolean
Default:
true
Description: Reload application after changing environment
Example:
wheels environment set production --reload=false
Examples
Basic Usage
# Show current environment
wheels environment
# Set environment to production
wheels environment set production
# Set environment without reload
wheels environment set development --reload=false
# List all available environments
wheels environment list
Quick Switching
# Shortcut syntax - if action matches an environment name
wheels environment development # Same as: wheels environment set development
wheels environment production # Same as: wheels environment set production
wheels environment testing # Same as: wheels environment set testing
Environment Details
development
Description: Development mode with debugging enabled, no caching
Use for: Local development and debugging
Features:
Debug information displayed
Error details shown
No query caching
No view caching
Hot reloading enabled
testing
Description: Testing mode for running automated tests
Use for: Running test suites and CI/CD pipelines
Features:
Consistent test environment
Test database connections
Predictable caching behavior
Error details available
production
Description: Production mode with caching enabled, debugging disabled
Use for: Live production servers
Features:
Query caching enabled
View caching enabled
Debug information hidden
Optimized performance
Error pages for users
maintenance
Description: Maintenance mode to show maintenance page
Use for: During deployments or maintenance windows
Features:
Maintenance page displayed
Admin access still available
Database migrations possible
Public access restricted
How It Works
Configuration Storage: Environment settings are stored in:
.env
file (WHEELS_ENV variable)Environment variables
Application configuration
Runtime Detection: The environment is determined by:
Checking server environment variables
Reading
.env
fileDefaulting to development
Change Process:
Updates
.env
fileOptionally reloads application
Changes take effect immediately (if reloaded)
Output Examples
Current Environment Display
Current Wheels Environment
=========================
Environment: development
Wheels Version: 2.5.0
Data Source: myapp_dev
Server: Lucee 5.3.10.120
Environment Settings:
cacheQueries: false
cachePartials: false
cachePages: false
cacheActions: false
showDebugInformation: true
showErrorInformation: true
Environment List
Available Wheels Environments
============================
development (current)
Description: Development mode with debugging enabled, no caching
Use for: Local development and debugging
testing
Description: Testing mode for running automated tests
Use for: Running test suites and CI/CD pipelines
production
Description: Production mode with caching enabled, debugging disabled
Use for: Live production servers
maintenance
Description: Maintenance mode to show maintenance page
Use for: During deployments or maintenance windows
Configuration
Using .env File
Create or modify .env
in your project root:
WHEELS_ENV=production
Using Environment Variables
Set system environment variable:
export WHEELS_ENV=production
Precedence Order
System environment variables (highest priority)
.env
fileDefault (development)
Best Practices
Development Workflow
Use
development
for local workSwitch to
testing
before running testsNever use
development
in production
Production Deployment
Always use
production
environmentSet via environment variables for security
Disable reload after deployment
Testing Strategy
Use
testing
for automated testsEnsure consistent test environment
Reset between test runs
Maintenance Windows
Switch to
maintenance
during deploymentsProvide clear maintenance messages
Switch back to
production
when complete
Troubleshooting
Environment not changing
Check if server needs restart:
wheels server restart
Verify
.env
file permissionsCheck for system environment variable conflicts
Server required for some operations
Some environment checks require running server
Start server first:
wheels server start
File-based changes work without server
Permission issues
Ensure write access to
.env
fileCheck directory permissions
Run with appropriate user privileges
Security Notes
Don't commit
.env
files with production settingsUse environment variables in production
Restrict access to environment commands in production
Log environment changes for audit trails
Related Commands
wheels reload
- Reload applicationwheels server restart
- Restart serverwheels console
- Test in different environments
See Also
Last updated
Was this helpful?