caddy-website/src/docs/markdown/command-line.md

title
Command Line

Command Line

Caddy has a standard unix-like command line interface. Basic usage is:

caddy <command> [<args...>]

The <carets> indicate parameters that get replaced by your input.

The[brackets] indicate optional parameters.

The ellipses ... indicates a continuation, i.e. one or more parameters.

Quick start: caddy help

---

• caddy adapt Adapts a config document to native JSON

• caddy build-info Prints build information

• caddy environ Prints the environment

• caddy file-server A simple but production-ready file server

• caddy fmt Formats a Caddyfile

• caddy hash-password Hashes a password and outputs base64

• caddy help View help for caddy commands

• caddy list-modules Lists the installed Caddy modules

• caddy reload Changes the config of the running Caddy process

• caddy reverse-proxy A simple but production-ready HTTP(S) reverse proxy

• caddy run Starts the Caddy process in the foreground

• caddy start Starts the Caddy process in the background

• caddy stop Stops the running Caddy process

• caddy trust Installs a certificate into local trust store(s)

• caddy untrust Untrusts a certificate from local trust store(s)

• caddy upgrade Upgrades Caddy to the latest release

• caddy add-package Upgrades Caddy to the latest release, with additional plugins added

• caddy remove-package Upgrades Caddy to the latest release, with some plugins removed

• caddy validate Tests whether a config file is valid

• caddy version Prints the version

Subcommands

caddy adapt

caddy adapt
	[--config <path>]
	[--adapter <name>]
	[--pretty]
	[--validate]

Adapts a configuration to Caddy's native JSON config structure and writes the output to stdout, along with any warnings to stderr, then exits.

--config is the path to the config file. If omitted, assumes Caddyfile in current directory if it exists; otherwise, this flag is required.

--adapter specifies the config adapter to use; default is caddyfile.

--pretty will format the output with indentation for human readability.

--validate will load and provision the adapted configuration to check for validity (but it will not actually start running the config).

Note that a config which is successfully adapted may still fail validation. For an example of this, use this Caddyfile:

localhost

tls cert_notexist.pem key_notexist.pem

Try adapting it:

caddy adapt --config Caddyfile

It succeeds without error. Then try:

caddy adapt --config Caddyfile --validate
adapt: validation: loading app modules: module name 'tls': provision tls: loading certificates: open cert_notexist.pem: no such file or directory

Even though that Caddyfile can be adapted to JSON without errors, the actual certificate and/or key files do not exist, so validation fails because that error arises during the provisioning phase. Thus, validation is a stronger error check than adaptation is.

Example

To adapt a Caddyfile to JSON that you can easily read and tweak manually:

caddy adapt --config /path/to/Caddyfile --pretty

caddy build-info

caddy build-info

Prints information provided by Go about the build (main module path, package versions, module replacements).

caddy environ

caddy environ

Prints the environment as seen by caddy, then exits. Can be useful when debugging init systems or process manager units like systemd.

caddy file-server

caddy file-server
	[--root <path>]
	[--listen <addr>]
	[--domain <example.com>]
	[--browse]
	[--templates]
	[--access-log]

Spins up a simple but production-ready static file server.

--root specifies the root file path. Default is the current working directory.

--listen accepts a listener address. Default is :80, unless --domain is used, then :443 will be the default.

--domain will only serve files through that hostname, and Caddy will attempt to serve it over HTTPS, so make sure any public DNS is configured properly first if it's a public domain name. The default port will be changed to 443.

--browse will enable directory listings if a directory without an index file is requested.

--templates will enable template rendering.

--access-log enables the request/access log.

This command disables the admin API, making it easier to run multiple instances on a local development machine.

caddy fmt

caddy fmt [--overwrite] [<path>]

Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless --overwrite is used.

<path> specifies the path to the Caddyfile. If -, the input is read from stdin. If omitted, a file named Caddyfile in the current directory is assumed instead.

--overwrite causes the result to be written to the input file instead of being printed to the terminal. If the input is not a regular file, this flag has no effect.

caddy hash-password

caddy hash-password
	[--plaintext <password>]
	[--algorithm <name>]
	[--salt <string>]

Hashes a password and writes the output to stdout in base64 encoding, then exits.

--plaintext is the plaintext form of the password. If omitted, interactive mode will be assumed and the user will be shown a prompt to enter the password manually.

--algorithm may be bcrypt or scrypt. Default is bcrypt.

--salt is used only if the algorithm requires an external salt (like scrypt).

caddy help

caddy help [<command>]

Prints CLI help text, optionally for a specific subcommand, then exits.

caddy list-modules

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

Prints the Caddy modules that are installed, optionally with package and/or version information from their associated Go modules, then exits.

In some scripted situations, it may be redundant to print all of the standard modules as well, so you may use --skip-standard to omit those from the output.

NOTE: Due to a bug in Go, version information is only available if Caddy is built as a dependency and not as the main module. Use xcaddy to make this easier.

caddy reload

caddy reload
	[--config <path>]
	[--adapter <name>]
	[--address <interface>]
	[--force]

Gives the running Caddy instance a new configuration. This has the same effect as POSTing a document to the /load endpoint, but this command is convenient for simple workflows revolving around config files. Compared to the stop, start, and run commands, this single command is the correct, semantic way to change/reload the running configuration.

Because this command uses the API, the admin endpoint must not be disabled.

--config is the config file to apply. If -, the config is read from stdin. If not specified, it will try a file called Caddyfile in the current working directory and, if it exists, it will adapt it using the caddyfile config adapter; otherwise, it is an error if there is no config file to load.

--adapter specifies a config adapter to use, if any.

--address needs to be used if the admin endpoint is not listening on the default address and if it is different from the address in the provided config file. Note that only TCP addresses are supported at this time.

--force will cause a reload to happen even if the specified config is the same as what Caddy is already running. Can be useful to force Caddy to reprovision its modules, which can have side-effects, for example: reloading manually-loaded TLS certificates.

caddy reverse-proxy

caddy reverse-proxy
	[--from <addr>]
	--to <addr>
	[--change-host-header]

Spins up a simple but production-ready HTTP(S) reverse proxy.

--from is the address to proxy from.

--to is the address to proxy to.

--change-host-header will cause Caddy to change the Host header from the incoming value to the address of the upstream.

Both --from and --to parameters can be URLs, as scheme and domain name will be inferred from the provided URL (paths and query strings ignored). Or they can be a simple network address and not a complete URL.

This command disables the admin API so it is easier to run multiple instances on a local development machine.

caddy run

caddy run
	[--config <path>]
	[--adapter <name>]
	[--pidfile <file>]
	[--environ]
	[--envfile <file>]
	[--resume]
	[--watch]

Runs Caddy and blocks indefinitely; i.e. "daemon" mode.

--config specifies an initial config file to immediately load and use. If -, the config is read from stdin. If no config is specified, Caddy will run with a blank configuration and use default settings for the admin API endpoints, which can be used to feed it new configuration. As a special case, if the current working directory has a file called "Caddyfile" and the caddyfile config adapter is plugged in (default), then that file will be loaded and used to configure Caddy, even without any command line flags.

--adapter is the name of the config adapter to use when loading the initial config, if any. This flag is not necessary if the --config filename starts with "Caddyfile" which assumes the caddyfile adapter. Otherwise, this flag is required if the provided config file is not in Caddy's native JSON format. Any warnings will be printed to the log, but beware that any adaptation without errors will immediately be used, even if there are warnings. If you want to review the results of the adaptation first, use the caddy adapt subcommand.

--pidfile writes the PID to the specified file.

--environ prints out the environment before starting. This is the same as the caddy environ command, but does not exit after printing.

--envfile loads environment variables from the specified file.

--resume uses the last loaded configuration that was autosaved, overriding the --config flag (if present). Using this flag guarantees config durability through machine reboots or process restarts. It is most useful in API-centric deployments.

--watch will watch the config file and automatically reload it after it changes. ⚠️ This feature is intended for use only in local development environments!

Do not stop the server to change configuration while running in production! That will result in downtime. (This should be obvious but you'd be surprised how many complaints we get about it.) Use the caddy reload command instead.

caddy start

caddy start
	[--config <path>]
	[--adapter <name>]
	[--envfile <file>]
	[--pidfile <file>]
	[--watch]

Same as caddy run, but in the background. This command only blocks until the background process is running successfully (or fails to run), then returns.

Note: the flag --config doesn't support - to read the config from stdin.

Use of this command is discouraged with system services or on Windows. On Windows, the child process will remain attached to the terminal, so closing the window will forcefully stop Caddy, which is not obvious. Consider running Caddy as a service instead.

Once started, you can use caddy stop or the POST /stop API endpoint to exit the background process.

caddy stop

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

Stopping (and restarting) the server is orthogonal to config changes. Do not use the stop command to change configuration in production, unless you want downtime. Use the caddy reload command instead.

Gracefully stops the running Caddy process (other than the process of the stop command) and causes it to exit. It uses the POST /stop endpoint of the admin API to perform a graceful shutdown.

The address of this request can be customized using the --address flag, or from the given --config, if the running instance's admin API is not using the default listen address.

If you want to stop the current configuration but do not want to exit the process, use caddy reload with a blank config, or the DELETE /config/ endpoint.

caddy trust

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

Installs a root certificate for a CA managed by Caddy's PKI app into local trust stores.

Caddy will attempt to install its root certificates into the local trust stores automatically when they are first generated, but it might fail if Caddy doesn't have the appropriate permissions to write to the trust store. This command is necessary to pre-install the certificates before using them, if the server process runs as an unprivileged user (such as via systemd). You may need to run this command with sudo to unix systems.

By default, this command installs the root certificate for Caddy's default CA (i.e. "local"). You may specify the ID of another CA with the --ca flag.

This command will attempt to connect to Caddy's admin API to fetch the root certificate, using the GET /pki/ca/<id>/certificates endpoint. You may explicitly specify the --address, or use the --config flag to load the admin address from your config, if the running instance's admin API is not using the default listen address.

You may also use the caddy binary with this command to install certificates on other machines in your network, if the admin API is made accessible to other machines -- be careful if doing this, to not expose the admin API to untrusted clients.

caddy untrust

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

Untrusts a root certificate from the local trust store(s).

This command uninstalls trust; it does not necessarily delete the root certificate from trust stores entirely. Thus, repeatedly trusting and untrusting new certificates can fill up trust databases.

This command does not delete or modify certificate files from Caddy's configured storage.

This command can be used in one of two ways:

• By specifying a direct path to the root certificate to untrust with the --cert flag.
• By fetching the root certificate from the admin API using the GET /pki/ca/<id>/certificates endpoint. This is the default behaviour if no flags are given.

If the admin API is used, then the CA ID defaults to "local". You may specify the ID of another CA with the --ca flag. You may explicitly specify the --address, or use the --config flag to load the admin address from your config, if the running instance's admin API is not using the default listen address.

caddy upgrade

caddy upgrade
	[--keep-backup]

Replaces the current Caddy binary with the latest version from our download page with the same modules installed, including all third-party plugins that are registered on the Caddy website.

Upgrades do not interrupt running servers; currently, the command only replaces the binary on disk. This might change in the future if we can figure out a good way to do it.

The upgrade process is fault tolerant; the current binary is backed up first (copied beside the current one) and automatically restored if anything goes wrong. If you wish to keep the backup after the upgrade process is complete, you may use the --keep-backup option.

This command may require elevated privileges if your user does not have permission to write to the executable file.

caddy add-package

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

Similarly to caddy upgrade, replaces the current Caddy binary with the latest version with the same modules installed, plus the packages listed as arguments included in the new binary. Find the list of packages you can install from our download page. Each argument should be the full package name.

For example:

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

caddy remove-package

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

Similarly to caddy upgrade, replaces the current Caddy binary with the latest version with the same modules installed, but without the packages listed as arguments, if they existed in the current binary. Run caddy list-modules --packages to see the list of package names of non-standard modules included in the current binary.

caddy validate

caddy validate
	[--config <path>]
	[--adapter <name>]

Validates a configuration file, then exits. This command deserializes the config, then loads and provisions all of its modules as if to start the config, but the config is not actually started. This exposes errors in a configuration that arise during loading or provisioning phases and is a stronger error check than merely serializing a config as JSON.

--config is the config file to validate. If -, the config is read from stdin. Default is the Caddyfile in the current directory, if any.

--adapter is the name of the config adapter to use, if the config file is not in Caddy's native JSON format. If the config file starts with Caddyfile, the caddyfile adapter is used by default.

caddy version

caddy version

Prints the version and exits.