The Caddy Command Line
The caddy binary is both the server and the tool that manages it. The same executable that answers HTTP requests also validates a configuration file before it is applied, converts a Caddyfile into the JSON the server actually runs, prints the list of modules compiled into that particular build, and offers a one-line static file server for testing a client. Once you know which command answers which question, the command line stops being a list to memorise and becomes a set of tools you reach for. By the end of this page you will be able to run Caddy under a supervisor, change its configuration without downtime, and diagnose a configuration problem by reading the JSON the adapter produces.
Every invocation follows the same pattern.
caddy <command> [<args...>] [--flags]
Angle brackets stand for a value you supply, square brackets for an optional one, and every flag has a long form and usually a single-letter shortcut. caddy help prints the list of commands, and caddy help <command> prints the details of one of them.
caddy help
caddy help reload
Some commands are stable and used every day, others exist for a specific operation such as upgrading the binary or moving the certificate storage between backends. The list below is ordered by how often it earns its place.
| Command | What it does |
|---|---|
caddy run | Runs the server in the foreground and blocks |
caddy start | Starts the server in the background and returns |
caddy stop | Gracefully stops the running server |
caddy reload | Gives the running server a new configuration |
caddy validate | Loads and provisions a configuration without starting it |
caddy adapt | Converts a configuration to native JSON |
caddy fmt | Formats a Caddyfile |
caddy version | Prints the version |
caddy environ | Prints the environment as the process sees it |
caddy list-modules | Lists the modules compiled into this build |
caddy run is the foreground command. It is the one a supervisor should use, because a foreground process that exits takes its supervisor down with it.
caddy run --config /etc/caddy/Caddyfile
The flags that matter are few.
--config is the path to the configuration file. The value - reads the configuration from standard input. If the flag is omitted, Caddy looks for a file named Caddyfile in the current directory and uses it.
--adapter names the config adapter when the file is not a Caddyfile. The flag is not needed when the filename starts with Caddyfile or ends with .caddyfile, because those imply the caddyfile adapter.
--envfile loads environment variables from a file in KEY=VALUE form. Comments beginning with # are supported, keys may be prefixed with export, values may be double-quoted with escaped inner quotes, and multi-line values are supported.
--environ prints the environment before starting and then continues, which is the same output as caddy environ without exiting. It is useful for confirming that a service unit is passing the variables the configuration expects.
--pidfile writes the process identifier to a file, which is how caddy stop and process supervisors find the process.
--resume starts the server with the last configuration that was autosaved, overriding --config. This is the pairing for an API-driven deployment, because it makes the configuration survive a power cycle.
--watch reloads the configuration whenever the file changes. The documentation is explicit that this is for local development only.
caddy start --config /etc/caddy/Caddyfile
caddy start returns as soon as the background process is running, or reports that it failed to start. It is convenient for a quick test and discouraged for a real deployment, because a service manager handles supervision, logging, and restart policy better.
Two details are worth knowing. The --config flag does not support - for standard input, because the backgrounded process has no terminal to read from. And on Windows the child process stays attached to the terminal, so closing the window stops the server.
The commands that manage the admin endpoint need to know where it is. If the running server uses the default address, they need no extra flags; otherwise, pass --address.
caddy stop --address localhost:2020
caddy reload --address localhost:2020 --config /etc/caddy/Caddyfile
caddy stop
caddy stop sends a graceful shutdown request, which is implemented as a call to the admin endpoint. The server stops accepting new connections and drains the ones in flight before exiting.
Do not use caddy stop and caddy start to apply a configuration change. That is a restart, and it is exactly the downtime that caddy reload was written to avoid.
caddy reload --config /etc/caddy/Caddyfile
This is the semantically correct way to change a running configuration. It posts the new configuration to the running server, which is the same operation as calling POST /load on the admin endpoint.
Two flags are useful.
--force reloads even when the new configuration is identical to the current one. That matters when you have replaced a certificate file on disk and need Caddy to read it again.
--address points the command at an admin endpoint that is not on the default address.
The important caveat is that this command uses the API, so the admin endpoint must not be disabled. A configuration with admin off cannot be reloaded at all.
Reload is also what a service manager should call, so that a restart of the service applies a configuration change rather than taking the site down.
[Service]
Type=notify
ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
caddy validate --config /etc/caddy/Caddyfile
caddy validate deserializes the configuration and then loads and provisions every module in it, exactly as if the server were starting, but it never starts. That is a much stronger check than parsing, and it catches errors that only appear at provision time, such as a certificate file that does not exist.
There is one caveat. Provisioning acquires real resources, and some modules hold exclusive locks. A configuration that uses the acme_server directive will fail to validate while another instance is already running, because the database cannot be opened twice. When you want to test a configuration against a running instance, use caddy reload instead: it provisions the new configuration inside the running process, so it does not contend for the same resources, and if provisioning fails the active configuration keeps serving.
caddy adapt --config /etc/caddy/Caddyfile --pretty
caddy adapt converts the configuration to Caddy native JSON and writes it to standard output, with any warnings on standard error, then exits. The --pretty flag indents the output so a human can read it.
Adding --validate makes the command provision the adapted configuration as well, which catches the class of errors that adaptation alone misses.
caddy adapt --config /etc/caddy/Caddyfile --pretty --validate
Reading this output is the most direct way to answer the question “what does this directive actually do”. When a route is not matching, the JSON shows the matcher that was actually built, which is frequently not the matcher you thought you wrote.
caddy fmt /etc/caddy/Caddyfile --overwrite
caddy fmt rewrites the file with canonical indentation and spacing. Without --overwrite it prints the result to standard output, and with --diff it prints a unified diff instead. The command exits with status 1 when the file is not already formatted, which makes it usable as a check in continuous integration.
Pass - to read from standard input.
cat Caddyfile | caddy fmt -
caddy version
caddy build-info
caddy list-modules
caddy version prints the version. caddy build-info prints the Go build information, including the module path and the version of each dependency, which is what you need when a bug report needs the exact set of dependencies.
caddy list-modules prints every module compiled into this binary, which is the definitive answer to the question “does this build support the directive I want”. Its flags make it scriptable.
caddy list-modules --skip-standard
caddy list-modules --json | jq
caddy list-modules --packages
--skip-standard omits the standard modules, leaving only the third-party ones, which is the list you care about when you are checking whether a plugin is present. --packages shows the package names of the non-standard modules, and --json produces machine-readable output.
Three commands spin up a working server with no configuration file at all. They exist for development, testing, and for demonstrating an HTTP client.
caddy respond --listen :8080 --body "hello" --status 200
caddy file-server --root /srv/www --listen :8080
caddy reverse-proxy --from :8080 --to localhost:9000
caddy respond returns a hard-coded response. With no arguments at all it listens on a random free port and answers with an empty 200, and it always prints the address it chose. A final unnamed argument is treated as a status code when it is three digits and as a body otherwise.
caddy respond --listen :2000-2004 "I am server {{.N}} on port {{.Port}}"
That starts five servers, one per port in the range, and the template variables .N, .Port, and .Address are available in the body.
caddy file-server serves a directory. Its --browse flag enables directory listings, --precompressed looks for sidecar files such as index.html.gz, and --domain restricts serving to one hostname over HTTPS.
caddy reverse-proxy proxies one address to another. --to may be repeated for several upstreams and may include a port range. --change-host-header sets the Host header to the upstream address, and --insecure disables verification of the upstream certificate, which removes a security guarantee and should only ever be used against a development machine.
Both caddy file-server and caddy reverse-proxy disable the admin API, which is what makes it safe to run several of them on one development machine.
caddy hash-password --plaintext "correct horse battery staple"
The result is written to standard output in a form the configuration accepts directly. The default algorithm is bcrypt with a cost of 14; --algorithm argon2id selects a key derivation function that is harder to attack with specialised hardware.
caddy hash-password --plaintext "secret" --algorithm argon2id --argon2id-memory 65536
caddy upgrade
caddy add-package github.com/caddy-dns/cloudflare
caddy remove-package github.com/caddy-dns/cloudflare
caddy upgrade replaces the binary with the latest release that has the same modules, including the third-party plugins. The current binary is backed up first and restored automatically if anything fails. The upgrade does not interrupt a running server, because it only replaces the file on disk; a restart is still needed to run the new binary.
caddy add-package and caddy remove-package do the same thing with the module set changed. To find the package names of the non-standard modules in the current binary, run caddy list-modules --packages.
All three are marked experimental in the documentation, and all three need write access to the executable file, which usually means elevated privileges.
Caddy traps some signals and ignores others.
| Signal | Behaviour |
|---|---|
SIGINT | Graceful exit. Send it again to force an immediate exit. |
SIGTERM | Graceful exit. |
SIGQUIT | Quits immediately, but still cleans up the locks in storage. |
SIGUSR1 | Reloads the configuration file. |
SIGUSR2 | Ignored. |
SIGHUP | Ignored. |
SIGUSR1 is only enabled in a narrow case: the server must have been started with caddy run from a configuration file, without --resume, and no configuration change must have been made through the API. Otherwise the signal is ignored with a warning, because the server would then have two sources of truth for its configuration.
A graceful exit means that new connections are refused while existing ones are drained. The grace period is unlimited by default.
The process exit codes are meaningful.
| Code | Meaning |
|---|---|
| 0 | Normal exit. |
| 1 | Failed startup. Do not restart automatically; it will fail again for the same reason. |
| 2 | Forced quit, without the usual cleanup. |
| 3 | Failed quit, with errors during cleanup. |
# Check the file, then apply it, and only apply it if the check passes.
caddy validate --config /etc/caddy/Caddyfile && \
caddy reload --config /etc/caddy/Caddyfile
# See what the Caddyfile becomes.
caddy adapt --config /etc/caddy/Caddyfile --pretty
# Confirm that a plugin is compiled into this build.
caddy list-modules --skip-standard | grep -q cloudflare && echo "plugin present"
# Check formatting in continuous integration.
caddy fmt --diff /etc/caddy/Caddyfile
# Print the environment the process actually receives.
caddy environ
# Stop a server whose admin endpoint is not on the default address.
caddy stop --address localhost:2020
| Mistake | What happens | Correction |
|---|---|---|
| Stopping and starting to apply a change | Causes avoidable downtime | Use caddy reload |
Expecting caddy adapt to catch every error | Adapt only converts; it does not provision | Add --validate, or use caddy validate |
| Validating against a running instance | Exclusive resources cause a false failure | Use caddy reload to test against the live server |
| Reloading with the admin endpoint disabled | Reload is impossible | Keep the endpoint enabled |
Omitting --adapter for a non-Caddyfile config | The file is parsed as the wrong format | Pass --adapter, or name the file Caddyfile |
Using --watch in production | Reloads on every editor save | Remove the flag and reload explicitly |
Approach:
The task is to run Caddy under a supervisor and to change its configuration later without dropping traffic. The decision that determines whether that is possible is which command applies the change: run blocks and is the command a supervisor should own, reload hands a new configuration to the process that is already running, and stop followed by start is a restart with the downtime that a restart implies. Everything else on the command line exists to make the change safe before it is applied.
Steps:
- Validate the configuration before it is applied.
caddy validateloads and provisions every module without starting the server, which is stronger than parsing and catches errors that only appear at provision time. - Check that the file formats cleanly, so that a diff in a review is about behaviour and not about whitespace.
- Read the adapted JSON with
caddy adapt --prettywhen a directive is not doing what was expected, because the JSON shows the matcher and handler that were actually built. - Start the server in the foreground with
caddy run, under a supervisor that owns the process and sends it the right signals. - Wire the supervisor so that a service restart calls
caddy reloadrather than stopping and starting, which is what turns a configuration change into a zero-downtime operation. - Apply later changes with
caddy reload --config ..., and add--forcewhen the configuration text is unchanged but the process must re-read something from disk, such as a replaced certificate. - Confirm the change from the running process rather than from the file, by reading the effective configuration through the admin endpoint.
- Upgrade the binary out of band with
caddy upgrade, which replaces the file on disk without interrupting the running server, and restart the service afterwards to pick it up.
Answer:
The service unit that makes this work looks like this.
[Unit]
Description=Caddy
After=network-online.target
Wants=network-online.target
[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/local/bin/caddy run --config /etc/caddy/Caddyfile
ExecReload=/usr/local/bin/caddy reload --config /etc/caddy/Caddyfile --force
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi.targetThe change procedure looks like this.
caddy fmt --diff /etc/caddy/Caddyfile
caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/Caddyfileand the verification looks like this.
curl -s http://localhost:2019/config/ | jq '.apps.http.servers | keys'
sudo systemctl status caddyThe result is that the server is supervised and restarted automatically on failure, that a configuration change is applied by the supervisor through reload rather than by a restart, that the change is refused before it is applied if it is invalid, and that a binary upgrade happens without dropping a single request.
