Config/CLI: Rename `--config-file` to `--defaults-yaml` and improve command help #1401

New issue

Open

opened 2026-02-20 00:11:58 -05:00 by deekerman · 0 comments

deekerman commented

2026-02-20 00:11:58 -05:00

Owner

Originally created by @lastzero on GitHub (Apr 13, 2022).

Originally assigned to: @lastzero on GitHub.

As a CLI user, the use of the flags is clearer if --config-file is renamed to --defaults-yaml, as I would otherwise expect it to be possible to set all configuration values in the YAML file passed as an argument.

If you pass a YAML file via --defaults-yaml/--config-file`, the values are only used to set defaults. These can still be overridden by CLI parameters and environment variables (which are always present in most Docker/Cloud environments, so you can't really change anything).

In case you want PhotoPrism to ignore the environment and prefer values from a configuration file instead, you should use the --config-path flag / the PHOTOPRISM_CONFIG_PATH variable:

Values in [config-path]/options.yml always take precedence over CLI flags and environment variables if present
Options changed in the advanced settings UI are automatically stored here
To avoid write conflicts, it is best to modify the options.yml file only when the backend is not running
Command help has been updated to explain which flag does what (which wasn't really the case before)

Originally created by @lastzero on GitHub (Apr 13, 2022). Originally assigned to: @lastzero on GitHub. **As a CLI user, the use of the flags is clearer if `--config-file` is renamed to `--defaults-yaml`, as I would otherwise expect it to be possible to set all configuration values in the YAML file passed as an argument.** If you pass a YAML file via --defaults-yaml` / `--config-file`, the values are only used to set defaults. These can still be overridden by CLI parameters and environment variables (which are always present in most Docker/Cloud environments, so you can't really change anything). In case you want PhotoPrism to ignore the environment and prefer values from a configuration file instead, you should use the `--config-path` flag / the `PHOTOPRISM_CONFIG_PATH` variable: - Values in `[config-path]/options.yml` always take precedence over CLI flags and environment variables if present - Options changed in the advanced settings UI are automatically stored here - To avoid write conflicts, it is best to modify the `options.yml` file only when the backend is not running - Command help has been updated to explain which flag does what (which wasn't really the case before)