Skip to main content
The caddy adapt command adapts a configuration to Caddy’s native JSON format and outputs the result.

​
Usage

caddy adapt --config <path> [flags]

​
Description

Adapts a configuration to Caddy’s native JSON format and writes the output to stdout, along with any warnings to stderr. This is useful for:
  • Previewing how your Caddyfile will be converted to JSON
  • Debugging config adapter behavior
  • Validating your config syntax
  • Learning Caddy’s JSON structure
  • Generating JSON configs from other formats

​
Flags

​
--config
string
required
Configuration file to adapt (required).Use - to read from stdin instead of a file.
​
--adapter
string
default:"caddyfile"
Name of config adapter to use.Default: caddyfileAvailable adapters depend on what’s compiled in. Common ones:
  • caddyfile - Caddyfile format
  • yaml - YAML format (if installed)
​
--pretty
boolean
default:"false"
Format the output with indentation for human readability.Without this flag, output is compact JSON on a single line.
​
--validate
boolean
default:"false"
Validate the adapted config.If the config is invalid, an error will be printed to stderr and a non-zero exit status will be returned.
​
--envfile
string[]
default:"[]"
Environment file(s) to load in KEY=VALUE format.Useful if your config references environment variables.

​
Examples

​
Basic adaptation

caddy adapt --config Caddyfile
Outputs compact JSON to stdout.

​
Pretty-printed output

caddy adapt --config Caddyfile --pretty
Outputs formatted JSON: 
{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [
            ":443"
          ],
          "routes": [
            ...
          ]
        }
      }
    }
  }
}

​
Adapt and validate

caddy adapt --config Caddyfile --validate
This ensures the adapted JSON config is valid before using it.

​
Adapt from stdin

cat Caddyfile | caddy adapt --config - --adapter caddyfile --pretty

​
Save to file

caddy adapt --config Caddyfile --pretty > config.json

​
Adapt with environment variables

caddy adapt --config Caddyfile --envfile .env --pretty
If your Caddyfile uses {env.VARIABLE}, the environment file will be loaded.

​
Adapt YAML config

caddy adapt --config caddy.yaml --adapter yaml --pretty

​
Output

The adapted JSON is written to stdout, and any warnings are written to stderr. 
example.com {
    reverse_proxy localhost:8080
}

​
Exit Codes

  • 0 - Success
  • 1 - Failed (adaptation error or validation error)

​
Warnings

Warnings are printed to stderr with file location: 
Caddyfile:10: some_directive: this is a warning message
Warnings don’t cause the command to fail, but you should review them.

​
Validation

With the --validate flag, the adapted config is:
  1. Unmarshaled into Go structs
  2. Validated by calling Validate() on all modules
  3. Checked for errors
If validation fails: 
Error: validation: field 'required_field' is required
Validation catches many errors but not all. Some errors only appear at runtime when the config is actually loaded.

​
Use Cases

​
1. Preview before applying

# Preview the JSON
caddy adapt --config Caddyfile --pretty

# If it looks good, apply it
caddy reload --config Caddyfile

​
2. Generate production JSON

# Generate and save
caddy adapt --config Caddyfile --pretty --validate > /etc/caddy/config.json

# Use in production
caddy run --config /etc/caddy/config.json

​
3. Debug config issues

caddy adapt --config Caddyfile --pretty --validate 2>&1 | less

​
4. Learn JSON structure

Write a simple Caddyfile feature, then adapt it to see the JSON equivalent: 
echo 'localhost { respond "Hello" }' | caddy adapt --config - --pretty

​
5. CI/CD validation

#!/bin/bash
if caddy adapt --config Caddyfile --validate; then
    echo "Config is valid"
else
    echo "Config is invalid"
    exit 1
fi

Build docs developers (and LLMs) love

Get started for freeTalk to us