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.

1. The shape of the command

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.

2. The everyday commands

CommandWhat it does
caddy runRuns the server in the foreground and blocks
caddy startStarts the server in the background and returns
caddy stopGracefully stops the running server
caddy reloadGives the running server a new configuration
caddy validateLoads and provisions a configuration without starting it
caddy adaptConverts a configuration to native JSON
caddy fmtFormats a Caddyfile
caddy versionPrints the version
caddy environPrints the environment as the process sees it
caddy list-modulesLists the modules compiled into this build

3. Running the server

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.

4. Starting in the background

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

5. Stopping the server

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.

6. Reloading without downtime

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

7. Validating a configuration

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.

8. Adapting to JSON

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.

9. Formatting a Caddyfile

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 -

10. Inspecting the binary

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.

11. The shortcut servers

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.

12. Hashing a password

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

13. Upgrading the binary

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.

14. Signals and exit codes

Caddy traps some signals and ignores others.

SignalBehaviour
SIGINTGraceful exit. Send it again to force an immediate exit.
SIGTERMGraceful exit.
SIGQUITQuits immediately, but still cleans up the locks in storage.
SIGUSR1Reloads the configuration file.
SIGUSR2Ignored.
SIGHUPIgnored.

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.

CodeMeaning
0Normal exit.
1Failed startup. Do not restart automatically; it will fail again for the same reason.
2Forced quit, without the usual cleanup.
3Failed quit, with errors during cleanup.

15. Recipes

# 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

16. Common mistakes

MistakeWhat happensCorrection
Stopping and starting to apply a changeCauses avoidable downtimeUse caddy reload
Expecting caddy adapt to catch every errorAdapt only converts; it does not provisionAdd --validate, or use caddy validate
Validating against a running instanceExclusive resources cause a false failureUse caddy reload to test against the live server
Reloading with the admin endpoint disabledReload is impossibleKeep the endpoint enabled
Omitting --adapter for a non-Caddyfile configThe file is parsed as the wrong formatPass --adapter, or name the file Caddyfile
Using --watch in productionReloads on every editor saveRemove the flag and reload explicitly
caddy command linecaddy reloadcaddy validateservice management

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:

  1. Validate the configuration before it is applied. caddy validate loads and provisions every module without starting the server, which is stronger than parsing and catches errors that only appear at provision time.
  2. Check that the file formats cleanly, so that a diff in a review is about behaviour and not about whitespace.
  3. Read the adapted JSON with caddy adapt --pretty when a directive is not doing what was expected, because the JSON shows the matcher and handler that were actually built.
  4. Start the server in the foreground with caddy run, under a supervisor that owns the process and sends it the right signals.
  5. Wire the supervisor so that a service restart calls caddy reload rather than stopping and starting, which is what turns a configuration change into a zero-downtime operation.
  6. Apply later changes with caddy reload --config ..., and add --force when the configuration text is unchanged but the process must re-read something from disk, such as a replaced certificate.
  7. Confirm the change from the running process rather than from the file, by reading the effective configuration through the admin endpoint.
  8. 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.target

The change procedure looks like this.

caddy fmt --diff /etc/caddy/Caddyfile
caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/Caddyfile

and the verification looks like this.

curl -s http://localhost:2019/config/ | jq '.apps.http.servers | keys'
sudo systemctl status caddy

The 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.

Found an issue with this content?

Tell us what could be improved.