Mastering the Caddy Command Line Interface: A Comprehensive Guide

Caddy, the powerful, extensible server platform, offers a user-friendly and efficient command-line interface (CLI) for managing your server and configurations. This guide provides a comprehensive overview of the Caddy command line, detailing its subcommands, options, and how to effectively utilize it for various tasks. Whether you’re adapting configurations, running a file server, or managing your Caddy instance, understanding the Caddy command line is essential.

The basic structure of a Caddy command is:

caddy [command] [subcommand] [flags]

Square brackets [] indicate optional parameters, parentheses () denote required parameters, and ellipses ... signify continuation for one or more parameters. Flags, often with single-letter shortcuts (e.g., -f), modify command behavior.

For a quick start, simply type caddy, caddy help, or man caddy (if man pages are installed) in your terminal.

Caddy Command Line Subcommands

Let’s explore the various subcommands available in the Caddy command line interface.

`caddy adapt`

The caddy adapt subcommand converts a configuration file into Caddy’s native JSON format. This is incredibly useful for understanding how your Caddyfile or other configuration formats are interpreted by Caddy.

caddy adapt [-c, --config <path>] [-a, --adapter <name>] [-p, --pretty] [--validate]

--config <path> or -c <path>: Specifies the path to your configuration file. If omitted and a Caddyfile exists in the current directory, it will be used by default. Otherwise, this flag is required.
--adapter <name> or -a <name>: Defines the configuration adapter to use. The default is caddyfile. Other adapters might be available depending on your Caddy build.
--pretty or -p: Formats the output JSON with indentation, making it human-readable.
--validate: Goes beyond just adapting and attempts to load and provision the configuration. This checks for deeper validity, ensuring that the configuration is not only structurally sound but also semantically correct and that modules can be provisioned.

It’s crucial to understand that successful adaptation doesn’t guarantee a valid configuration. Validation, using the --validate flag, performs a more thorough check.

caddy adapt --config Caddyfile

This command adapts the Caddyfile in the current directory to JSON.

caddy adapt --config /path/to/my_caddy_config.yaml --adapter yaml --pretty

This example adapts a YAML configuration file located at /path/to/my_caddy_config.yaml using the yaml adapter and outputs pretty-printed JSON.

caddy adapt --config Caddyfile --validate

This command adapts and validates the Caddyfile, checking for potential errors that might only surface during the provisioning phase, such as missing certificate files as illustrated in the original article.

`caddy build-info`

caddy build-info

This simple command displays build information about your Caddy binary, provided by Go. This includes the main module path, package versions, and module replacements, which can be helpful for debugging and understanding your Caddy build environment.

`caddy completion`

Enhance your command-line experience with shell completion scripts generated by caddy completion.

caddy completion [bash|zsh|fish|powershell]

This subcommand generates scripts for popular shells like bash, zsh, fish, and PowerShell, enabling tab-completion and auto-completion for caddy commands. To get specific installation instructions for your shell, run caddy help completion or caddy completion -h.

`caddy environ`

caddy environ

Use caddy environ to print the environment variables as seen by Caddy. This is particularly useful when troubleshooting init systems or process managers like systemd, ensuring that Caddy is running with the expected environment.

`caddy file-server`

Quickly serve static files with the production-ready caddy file-server.

caddy file-server [-r, --root <path>] [--listen <addr>] [-d, --domain <example.com>] [-b, --browse] [--reveal-symlinks] [-t, --templates] [--access-log] [-v, --debug] [--no-compress] [-p, --precompressed]

--root <path> or -r <path>: Sets the root directory for serving files. Defaults to the current working directory.
--listen <addr>: Specifies the listener address. Default is :80, or :443 if --domain is used.
--domain <example.com> or -d <example.com>: Serves files only for the specified domain name and automatically configures HTTPS. Ensure DNS is properly configured beforehand.
--browse or -b: Enables directory listings when a directory lacks an index file.
--reveal-symlinks: When used with --browse, shows the target of symbolic links in directory listings.
--templates or -t: Activates template rendering for served files.
--access-log: Enables request logging.
--debug or -v: Enables verbose debug logging.
--no-compress: Disables compression (Zstandard and Gzip are enabled by default).
--precompressed <format> or -p <format>: Specifies encoding formats to look for pre-compressed files (e.g., gzip, br). Can be repeated for multiple formats.

The file-server command disables the admin API, simplifying local development setups with multiple instances.

caddy file-server --root /var/www/html --domain example.com --browse

This command serves files from /var/www/html for the domain example.com over HTTPS, with directory browsing enabled.

`caddy file-server export-template`

caddy file-server export-template

Exports the default HTML template used for file browsing to standard output. You can customize this template and use it with the templates directive in a full Caddy configuration.

`caddy fmt`

Format your Caddyfiles for consistency and readability with caddy fmt.

caddy fmt [<path>] [-w, --overwrite] [-d, --diff]

<path>: Path to the Caddyfile. If -, reads from stdin. If omitted, assumes Caddyfile in the current directory.
--overwrite or -w: Writes the formatted output back to the input file.
--diff or -d: Outputs a diff of the changes instead of the formatted Caddyfile.

caddy fmt Caddyfile

Formats the Caddyfile in the current directory and prints the result to stdout.

caddy fmt /path/to/my/Caddyfile --overwrite

Formats the Caddyfile at /path/to/my/Caddyfile and overwrites the file with the formatted content.

`caddy hash-password`

Securely hash passwords for use in your Caddy configurations with caddy hash-password.

caddy hash-password [-p, --plaintext <password>] [-a, --algorithm <name>]

--plaintext <password> or -p <password>: The plaintext password to hash. If omitted, prompts for interactive input.
--algorithm <name> or -a <name>: Specifies the hashing algorithm (e.g., bcrypt, argon2id). Defaults to bcrypt.

caddy hash-password -p "MySecretPassword"

Hashes the password “MySecretPassword” using the default bcrypt algorithm and prints the hash.

`caddy help`

Get help and information about Caddy commands using caddy help.

caddy help [command]

Running caddy help without any arguments displays general help. caddy help <command> provides help for a specific command.

`caddy list-modules`

Discover installed Caddy modules with caddy list-modules.

caddy list-modules [--packages] [--versions] [-s, --skip-standard]

--packages: Includes package information from Go modules.
--versions: Shows module versions.
--skip-standard or -s: Excludes standard modules from the output.

This command is useful for understanding which modules are included in your Caddy build, especially when using custom builds or xcaddy.

`caddy manpage`

Generate man pages for Caddy commands with caddy manpage.

caddy manpage (-o, --directory <path>)

--directory <path> or -o <path>: (Required) Specifies the directory to write the man pages to.

This command generates man pages that can be read using the man command in your terminal, providing offline documentation for Caddy.

caddy manpage --directory man
gzip -r man/
sudo cp man/* /usr/share/man/man8/
sudo mandb

This example generates man pages in the man directory, compresses them, and then installs them to the system man page directory (on typical Linux systems).

`caddy reload`

Apply a new configuration to a running Caddy instance gracefully using caddy reload.

caddy reload [-c, --config <path>] [-a, --adapter <name>] [--address <interface>] [-f, --force]

--config <path> or -c <path>: Path to the new configuration file. If -, reads from stdin. If omitted, tries to load Caddyfile from the current directory.
--adapter <name> or -a <name>: Configuration adapter to use (e.g., caddyfile, json).
--address <interface>: Address of the admin API if it’s not the default.
--force or -f: Forces reload even if the configuration is the same, useful for reprovisioning modules (e.g., TLS certificates).

caddy reload is the semantic way to update a running Caddy configuration without downtime, using the admin API.

caddy reload --config /etc/caddy/Caddyfile

Reloads Caddy with the configuration from /etc/caddy/Caddyfile.

caddy reload --force

Forces a reload with the current configuration, potentially reprovisioning modules.

`caddy respond`

Create simple, hard-coded HTTP servers for development and debugging with caddy respond.

caddy respond [-s, --status <status>] [-H, --header "<field>: <value>"] [-b, --body <content>] [-l, --listen <addr>] [-v, --debug] [--access-log] [<status>]

--status <status> or -s <status>: HTTP status code to return.
--header "<field>: <value>" or -H "<field>: <value>": Adds a response header. Can be used multiple times.
--body <content> or -b <content>: Response body. Can also be piped from stdin.
--listen <addr> or -l <addr>: Listener address, can include port ranges for multiple servers.
--debug or -v: Enables verbose debug logging.
--access-log: Enables access logging.

caddy respond is invaluable for testing HTTP clients, scripts, and load balancers.

caddy respond --status 204

Starts a server that responds with an empty 204 No Content response.

caddy respond --body "Hello, World!" --header "Content-Type: text/plain" --listen :8080

Starts a server on port 8080 that responds with “Hello, World!” as plain text.

cat maintenance.html | caddy respond --listen :80 --status 503 --header "Content-Type: text/html"

Serves a maintenance page (from maintenance.html) with a 503 Service Unavailable status.

`caddy reverse-proxy`

Set up a production-ready reverse proxy quickly with caddy reverse-proxy.

caddy reverse-proxy [-f, --from <addr>] (-t, --to <addr>) [-H, --header-up "<field>: <value>"] [-d, --header-down "<field>: <value>"] [-c, --change-host-header] [-r, --disable-redirects] [-i, --internal-certs] [-v, --debug] [--access-log] [--insecure]

--from <addr> or -f <addr>: Address to proxy from.
--to <addr> or -t <addr>: (Required) Address to proxy to (upstream). Can be repeated for multiple upstreams.
--header-up "<field>: <value>" or -H "<field>: <value>": Sets a request header to send to the upstream.
--header-down "<field>: <value>" or -d "<field>: <value>": Sets a response header to send back to the client.
--change-host-header or -c: Sets the Host header to the upstream address.
--disable-redirects or -r: Disables automatic HTTP-to-HTTPS redirects.
--internal-certs or -i: Forces issuance of certificates using the internal CA.
--debug or -v: Enables verbose debug logging.
--access-log: Enables access logging.
--insecure: Disables TLS verification with the upstream (WARNING: Insecure!).

caddy reverse-proxy simplifies setting up reverse proxies for various use cases.

caddy reverse-proxy --from :80 --to localhost:3000

Proxies HTTP traffic from port 80 to a backend server running on localhost:3000.

caddy reverse-proxy --from example.com --to http://backend.example.net --header-up "X-Forwarded-By: Caddy"

Proxies HTTPS traffic for example.com to http://backend.example.net, adding an X-Forwarded-By header.

`caddy run`

Start Caddy in the foreground (“daemon” mode) with caddy run.

caddy run [-c, --config <path>] [-a, --adapter <name>] [--pidfile <file>] [-e, --environ] [--envfile <file>] [-r, --resume] [-w, --watch]

--config <path> or -c <path>: Initial configuration file to load. If -, reads from stdin. If omitted, Caddy starts with a blank configuration, or loads Caddyfile if present in the current directory.
--adapter <name> or -a <name>: Configuration adapter to use.
--pidfile <file>: Writes the process ID to the specified file.
--environ or -e: Prints the environment before starting.
--envfile <file>: Loads environment variables from a file.
--resume or -r: Uses the last autosaved configuration, overriding --config.
--watch or -w: Watches the config file for changes and reloads automatically (development use only!).

caddy run keeps Caddy running in the foreground, blocking the terminal.

caddy run --config /etc/caddy/Caddyfile --pidfile /var/run/caddy.pid

Runs Caddy with the configuration from /etc/caddy/Caddyfile and writes the PID to /var/run/caddy.pid.

caddy run --watch --config Caddyfile

Runs Caddy with Caddyfile and watches for changes, reloading the configuration automatically during development.

`caddy start`

Start Caddy in the background with caddy start.

caddy start [-c, --config <path>] [-a, --adapter <name>] [--envfile <file>] [--pidfile <file>] [-w, --watch]

caddy start is similar to caddy run, but it starts Caddy as a background process and returns immediately after Caddy starts successfully. Note that --config - (stdin) is not supported with caddy start. Discouraged for system services or Windows; consider running Caddy as a service instead.

`caddy stop`

Gracefully stop a running Caddy instance with caddy stop.

caddy stop [--address <interface>] [-c, --config <path> [-a, --adapter <name>]]

--address <interface>: Address of the admin API if not default.
--config <path> or -c <path>: Configuration file path (used to infer admin API address if needed).
--adapter <name> or -a <name>: Configuration adapter (if --config is used).

caddy stop uses the admin API to initiate a graceful shutdown of Caddy.

`caddy storage`

(Experimental) Manage Caddy’s data storage using caddy storage.

caddy storage [export|import] ...

This experimental subcommand allows exporting and importing Caddy’s storage contents, useful for migrating between storage modules.

`caddy storage export`

caddy storage export -c, --config <path> [-o, --output <path>]

Exports Caddy’s storage to a tarball.

--config <path> or -c <path>: (Required) Configuration file to load to connect to the storage module.
--output <path> or -o <path>: Output filename for the tarball. Use - for stdout.

`caddy storage import`

caddy storage import -c, --config <path> -i, --input <path>

Imports Caddy’s storage from a tarball.

--config <path> or -c <path>: (Required) Configuration file to load to connect to the storage module.
--input <path> or -i <path>: Input filename of the tarball. Use - for stdin.

caddy storage export -c Caddyfile.old -o- | caddy storage import -c Caddyfile.new -i-

This example pipes the exported storage from a Caddy instance configured by Caddyfile.old to the import command for an instance configured by Caddyfile.new, effectively migrating storage between configurations.

`caddy trust`

Install root certificates for Caddy’s PKI app into local trust stores using caddy trust.

caddy trust [--ca <id>] [--address <interface>] [-c, --config <path> [-a, --adapter <name>]]

--ca <id>: ID of the CA (defaults to “local”).
--address <interface>: Admin API address if not default.
--config <path> or -c <path>: Configuration file (for admin API address).
--adapter <name> or -a <name>: Configuration adapter (if --config used).

caddy trust is necessary to pre-install root certificates, especially when Caddy runs as an unprivileged user.

`caddy untrust`

Remove trust for root certificates from local trust stores with caddy untrust.

caddy untrust [-p, --cert <path>] [--ca <id>] [--address <interface>] [-c, --config <path> [-a, --adapter <name>]]

--cert <path> or -p <path>: Path to the certificate file to untrust.
--ca <id>: CA ID (defaults to “local”).
--address <interface>: Admin API address if not default.
--config <path> or -c <path>: Configuration file (for admin API address).
--adapter <name> or -a <name>: Configuration adapter (if --config used).

caddy untrust uninstalls trust for certificates, but doesn’t necessarily delete the certificate files themselves.

`caddy upgrade`

(Experimental) Upgrade your Caddy binary to the latest version with caddy upgrade.

caddy upgrade [-k, --keep-backup]

--keep-backup or -k: Keeps the backup of the old binary after upgrade.

This command replaces the current Caddy binary with the latest version, preserving installed modules and plugins. It backs up the current binary for fault tolerance.

`caddy add-package`

(Experimental) Add packages to your Caddy binary with caddy add-package.

caddy add-package <packages...> [-k, --keep-backup]

<packages...>: List of packages to add.
--keep-backup or -k: Keeps the backup of the old binary.

Similar to caddy upgrade, but adds specified packages to the new binary. Use package names from the Caddy download page.

caddy add-package github.com/caddy-dns/cloudflare

Adds the Cloudflare DNS package to the Caddy binary.

`caddy remove-package`

(Experimental) Remove packages from your Caddy binary using caddy remove-package.

caddy remove-package <packages...> [-k, --keep-backup]

<packages...>: List of packages to remove.
--keep-backup or -k: Keeps the backup of the old binary.

Removes specified packages from the Caddy binary during an upgrade. Use caddy list-modules --packages to see installed package names.

`caddy validate`

Validate a Caddy configuration file with caddy validate.

caddy validate [-c, --config <path>] [-a, --adapter <name>] [--envfile <file>]

--config <path> or -c <path>: Configuration file to validate. If -, reads from stdin. Defaults to Caddyfile in current directory.
--adapter <name> or -a <name>: Configuration adapter to use.
--envfile <file>: Loads environment variables from a file.

caddy validate checks for configuration errors by deserializing, loading, and provisioning modules without actually starting the server.

`caddy version`

caddy version

Prints the Caddy version and exits.

Caddy Signals

Caddy responds to specific signals to control its behavior:

Signal	Behavior
`SIGINT`	Graceful exit. Send again to force immediate exit.
`SIGQUIT`	Immediate quit, but cleans up storage locks.
`SIGTERM`	Graceful exit.
`SIGUSR1`	Ignored. Use `caddy reload` or the API for config updates.
`SIGUSR2`	Ignored.
`SIGHUP`	Ignored.

Graceful exit involves stopping new connections and draining existing ones before closing sockets.

Caddy Exit Codes

Caddy returns exit codes to indicate the outcome of its execution:

Code	Meaning
`0`	Normal exit.
`1`	Failed startup. Do not automatically restart; investigate the error.
`2`	Forced quit. Caddy exited without full cleanup.
`3`	Failed quit. Caddy exited with errors during cleanup.

Use echo $? in bash to check the exit code of the last command.

This comprehensive guide should equip you with a solid understanding of the Caddy command line interface and its powerful subcommands. By mastering these tools, you can efficiently manage and configure your Caddy server for various web serving and proxying needs.

Alt text: Example of using the caddy adapt command in the command line interface to convert a Caddyfile to JSON format, showing both the command input and the formatted JSON output.

Alt text: Demonstration of the caddy file-server command in the command line, showcasing how to quickly serve files from a specified directory using Caddy’s built-in file server.