Skip to main content
The caddy environ command prints the environment as seen by the Caddy process.

​
Usage

caddy environ [flags]

​
Description

Prints the environment as seen by this Caddy process, including:
  • Caddy-specific paths (home, data, config directories)
  • Runtime information (Go version, OS, architecture)
  • All environment variables
This is useful for:
  • Debugging environment variable issues
  • Verifying Caddy can see expected variables
  • Troubleshooting path and configuration issues
  • Understanding how Caddy will behave in different environments
Security: Environments may contain sensitive data like API keys, passwords, and tokens. Be careful when sharing output from this command.

​
Flags

​
--envfile
string[]
default:"[]"
Environment file(s) to load in KEY=VALUE format before printing.Useful for testing how environment files will be loaded.

​
Examples

caddy environ
Output: 
caddy.HomeDir=/home/user
caddy.AppDataDir=/home/user/.local/share/caddy
caddy.AppConfigDir=/home/user/.config/caddy
caddy.ConfigAutosavePath=/home/user/.config/caddy/autosave.json
caddy.Version=v2.7.6 h1:w0NymbG2m9PcvKWsrXO6EEkY9Ru4FJK8uQbYcev1p3A=
runtime.GOOS=linux
runtime.GOARCH=amd64
runtime.Compiler=gc
runtime.NumCPU=8
runtime.GOMAXPROCS=8
runtime.Version=go1.21.5
os.Getwd=/home/user/myapp

PATH=/usr/local/bin:/usr/bin:/bin
HOME=/home/user
USER=user
SHELL=/bin/bash
LANG=en_US.UTF-8
...

​
Test environment file loading

caddy environ --envfile .env
This loads .env before printing, so you can verify the variables are set correctly.

​
Test multiple environment files

caddy environ --envfile .env --envfile .env.local
Later files override earlier ones.

​
Save environment to file

caddy environ > caddy-env.txt

​
Compare environments

Compare development vs production: 
# On dev machine
caddy environ > env-dev.txt

# On production server
ssh prod 'caddy environ' > env-prod.txt

# Compare
diff env-dev.txt env-prod.txt

​
Check specific variable

caddy environ | grep API_KEY

​
Output Format

The output has two sections:

​
1. Caddy Information

Caddy-specific paths and runtime info: 
caddy.HomeDir=/home/user
caddy.AppDataDir=/home/user/.local/share/caddy
caddy.AppConfigDir=/home/user/.config/caddy
caddy.ConfigAutosavePath=/home/user/.config/caddy/autosave.json
caddy.Version=v2.7.6 h1:...
runtime.GOOS=linux
runtime.GOARCH=amd64
runtime.Compiler=gc
runtime.NumCPU=8
runtime.GOMAXPROCS=8
runtime.Version=go1.21.5
os.Getwd=/current/working/directory

​
2. Environment Variables

All environment variables in KEY=VALUE format: 
PATH=/usr/local/bin:/usr/bin:/bin
HOME=/home/user
USER=user
LANG=en_US.UTF-8
MY_API_KEY=secret123
...

​
Caddy Path Variables

​
caddy.HomeDir
string
User’s home directory.On Unix: $HOME
On Windows: %USERPROFILE%
​
caddy.AppDataDir
string
Directory where Caddy stores data (TLS certificates, ACME accounts, etc.).Default:
  • Linux: $HOME/.local/share/caddy
  • macOS: $HOME/Library/Application Support/Caddy
  • Windows: %APPDATA%/Caddy
Can be overridden with $XDG_DATA_HOME/caddy
​
caddy.AppConfigDir
string
Directory where Caddy stores configuration.Default:
  • Linux: $HOME/.config/caddy
  • macOS: $HOME/Library/Application Support/Caddy
  • Windows: %APPDATA%/Caddy
Can be overridden with $XDG_CONFIG_HOME/caddy
​
caddy.ConfigAutosavePath
string
Path where Caddy saves the last running config for --resume.Usually {caddy.AppConfigDir}/autosave.json

​
Environment Variables in Config

If your Caddyfile uses environment variables: 
{$SITE_ADDRESS} {
    reverse_proxy {env.BACKEND_HOST}:{env.BACKEND_PORT}
    
    tls {env.TLS_EMAIL}
}
You can verify they’re set: 
caddy environ | grep -E '(SITE_ADDRESS|BACKEND_HOST|BACKEND_PORT|TLS_EMAIL)'

​
Common Use Cases

​
1. Debug missing variables

# Check if variable is set
caddy environ | grep MY_VARIABLE

# If not found, variable is not set

​
2. Verify service manager environment

Environments differ between shells and service managers: 
# In shell
caddy environ > env-shell.txt

# Via systemd
systemctl cat caddy  # Check EnvironmentFile
sudo systemctl show caddy --property=Environment

​
3. Test environment files

# See what .env adds
caddy environ --envfile .env | grep -v '^caddy\|^runtime\|^os'

​
4. CI/CD debugging

In GitHub Actions or other CI: 
- name: Debug Caddy environment
  run: caddy environ

​
5. Container debugging

# In Docker
docker exec caddy-container caddy environ

# Or in docker-compose
docker-compose exec caddy caddy environ

​
Platform Differences

​
Linux

Respects XDG Base Directory specification:
  • $XDG_DATA_HOME - Data directory
  • $XDG_CONFIG_HOME - Config directory
  • $XDG_CACHE_HOME - Cache directory
If not set, falls back to $HOME/.local/share, $HOME/.config, etc.

​
macOS

Uses standard macOS paths:
  • ~/Library/Application Support/Caddy

​
Windows

Uses Windows environment variables:
  • %APPDATA%\Caddy
  • %USERPROFILE%

​
Plan 9

Uses $home instead of $HOME.

​
Security Considerations

The output includes ALL environment variables, which may contain:
  • API keys and tokens
  • Database passwords
  • Private keys
  • Session secrets
Never share the output publicly without redacting sensitive data.
To redact sensitive data: 
# Remove specific variables
caddy environ | grep -v -E '(PASSWORD|SECRET|KEY|TOKEN)'

# Or manually redact
caddy environ | sed 's/PASSWORD=.*/PASSWORD=<redacted>/'

​
Alternative: Print environment when running

You can also print the environment when starting Caddy: 
caddy run --environ
This prints the environment and then continues to run Caddy (unlike caddy environ which exits).

Build docs developers (and LLMs) love

Get started for freeTalk to us