Configuration

godyl can be configured in several ways.

Settings are applied (in order of highest to lowest priority) by:

Definition in tools.yml
Command-line flags
Environment variables
.env file(s)
.yml file
defaults.yml file (embedded or passed as configuration)
Command-line flag default values

In addition, tokens can be set in the keyring, or from a few other commonly used environment variables. See Authentication for more details.

All of above will be merged for run-time settings and to form the complete definition for each tool.

Configuration File Location

Unless --config-file or GODYL_CONFIG_FILE selects a specific file, godyl uses the first existing configuration file in this order:

./godyl.yaml
./godyl.yml
The global godyl.yaml
The global godyl.yml

If none exists, the active path is the global godyl.yml. The global configuration directory is platform-specific:

Platform	Directory
Linux and other Unix systems	`${XDG_CONFIG_HOME}/godyl`, or `~/.config/godyl` when `XDG_CONFIG_HOME` is unset
macOS	`~/Library/Application Support/godyl`
Windows	`%AppData%\godyl`

Print the exact active path on the current system with:

godyl config path

A configuration file in the current directory intentionally takes precedence over the global file. Consequently, godyl config set, godyl config remove, and authentication commands that are not using the keyring operate on the active file shown by godyl config path.

Commandline flags

See Command Reference and sub-commands for details on available flags and their default values.

Environment variables

Environment variables are available for all flag arguments and are prefixed with GODYL_ and further with <SUBCOMMAND>_ for each subcommand.

The .env files follow the same format.

Examples:

# Set the output directory for the `install` command
GODYL_INSTALL_OUTPUT=~/.local/bin

# Set the full flag for the `dump tools` command
GODYL_DUMP_TOOLS_FULL=true

All environment variables are also loaded into the run-time environment, regardless of whether they came directly from the environment or from a .env file.

They can be accessed with {{ .Env.<ENV_VAR> }}.

YAML Configuration

A YAML file can set the same values as long command-line flags and environment variables. The names are derived mechanically:

Scope	Command-line flag	Environment variable	YAML key
Root	`--log-level`	`GODYL_LOG_LEVEL`	`log-level`
Subcommand	`godyl install --output`	`GODYL_INSTALL_OUTPUT`	`install.output`
Nested subcommand	`godyl dump tools --full`	`GODYL_DUMP_TOOLS_FULL`	`dump.tools.full`

YAML preserves hyphens in long flag names. Environment variables replace hyphens with underscores and use uppercase letters. Short flag aliases do not affect either name.

In YAML, the dot-separated keys above are represented by nested mappings. A representative global configuration file looks like this:

# Root flags
log-level: info
parallel: 4
no-progress: true
keyring: true
env-file:
  - .env

# `godyl install` flags
install:
  output: ~/.local/bin
  strategy: sync
  tags:
    - "!native"

# `godyl download` flags
download:
  output: ./downloads
  source: github

# `godyl dump tools` flags
dump:
  tools:
    embedded: true
    full: true

Only include settings that should differ from the built-in defaults. See the command reference for available flags, or run godyl validate to validate the complete active configuration.

Defaults Configuration

The defaults.yml file is used to set default values for all tools. It supports the same fields as the tools.yml file.

An example of sane default values are provided in defaults.yml which is also embedded in the binary.

See Default Configuration File for more details.