Tools Format

Tools can be defined in a YAML file. godyl will look for a file named tools.yml in the current directory, if not specified.

See tools.yml for a sample configuration.

You can use a full or simple form for the tool definitions. Most fields follow the same format, with a full and simple form.

Configuration

- idelchi/envprof

This is the simplest form to download the latest release of envprof from the the default source type (for example, github or gitlab).

For more complex configurations, you can use the extended form:

name: idelchi/envprof
description: Environment profile manager
exe:
  name: envprof
  patterns:
    - "**/{{ .Exe }}{{ .EXTENSION }}"
aliases:
  - ep
source:
  type: github
tags:
  - cli
  - env
strategy: sync

A complete reference for all fields is available below.

Full form

# Name of the tool to download. Used as display name and for inferring other fields.
name: idelchi/envprof
# Optional description of the tool, for documentation purposes.
description: Profile-based environment variable manager
# Version tracking of the tool. Specifies the target version, as well as how to parse the current version.
version:
  # For `github` and `gitlab` sources, leave empty to fetch the latest release from the API.
  # The version is always available as {{ .Version }}, expect when not set.
  # It is then only available after the API call has been made.
  version: v0.1.0
  # Commands to run to get the current installed version (for syncs),
  # whenever not available in the cache.
  commands:
    - --version
    - version
  # Regex patterns to extract the version from command output (for syncs),
  # whenever not available in the cache.
  patterns:
    - '.*?(\d+\.\d+\.\d+).*'
# The download url. For `github` and `gitlab` sources,
# leave empty to populate from the API.
url: "https://github.com/idelchi/envprof/releases/download/v0.0.1/envprof_{{ .OS }}_{{ .ARCH }}.tar.gz"
# The output directory where the tool will be placed.
output: ~/.local/bin # [`--output`]
# The executable name. Specifies the desired output name of the executable,
# as well as the patterns to find it in the downloads.
exe:
  # The name to use for the executable.
  # Will be inferred from `name` using source-specific rules if not provided.
  # If no suffix is provided, the platform-specific suffix will be added.
  name: envprof
  # Glob patterns to find the executable in the downloads.
  # Uses globstar, so you can use `**` to match any number of directories.
  patterns:
    - "**/{{ .OS }}-{{ .Exe }}*{{ .EXTENSION }}"
# A list of aliases for the tool. Will create symlinks (or copies on Windows).
# If no suffix is provided, the platform-specific suffix will be added.
aliases:
  - gd
# A list of fallback strategies to try if the main source strategy fails.
# Will be used in the order they are defined.
fallbacks:
  - go
# Hints to find the correct asset to download.
hints:
  # Pattern to match the asset name. See `type` for allowed syntax.
  - pattern: "*amd64*"
    # Weight of the hint. Defaults to 1 if not provided.
    weight: |-
      {{- if eq .ARCH "amd64" -}}
      1
      {{- else -}}
      0
      {{- end -}}
    # Method to use for matching the pattern.
    type: glob|regex|globstar|startswith|endswith|contains
    # Whether to use the weight for matches, require the match, or exclude the match.
    match: weighted|required|excluded
source:
  type: github|gitlab|url|go|none # [`--source`]
  github:
    # Inferred from first part of `name` if not provided
    owner: idelchi
    # Inferred from last part of `name` if not provided
    repo: envprof
    token: secret # [`--github-token`]
  gitlab:
    # Inferred from first part of `name` if not provided
    namespace: idelchi/go-projects
    # Inferred from last part of `name` if not provided
    project: envprof
    token: secret # [`--gitlab-token`]
    server: https://gitlab.self-hosted.com
    no-token: false # Suppress usage of token
  url:
    token: secret # [`--url-token`]
    headers:
      Authorization:
        - "Bearer {{ .Tokens.URL }}"
      Content-Type:
        - application/json
        - application/x-www-form-urlencoded
  go:
    # Specifies the path for the `go install` command.
    # Useful when the installable is not in the default path (e.g `cmd/<tool>` or `.`).
    command: cmd/envprof
# Run custom commands after the installation (or only commands if `source.type` is `none`).
commands:
  # The list of commands to run.
  commands:
    - "mkdir -p {{ .Output }}"
  # Whether to suppress failures in the commands.
  allow_failure: true
  # Whether to exit immediately on error.
  exit_on_error: false
# List of tags to filter tools.
tags:
  - env
# Strategy for updating existing tools.
strategy: none|sync|force
# Skip the tool if the condition is met.
skip:
  - reason: "envprof is not available for Darwin"
    condition: '{{ eq .OS "darwin" }}'
# The mode for downloading and installing the tool.
# `find` will download, extract, and find the executable.
# `extract` will download and extract directly to the output directory.
mode: find|extract
# A collection of arbitrary values.
# Will be available as `{{ .Values.<name> }}` anywhere templating is supported.
values:
  customScalar: scalarValue
  customMap:
    key1: value1
    key2: value2
  customList:
    - item1
    - item2
# A collection of environment variables.
# Will be accessible as `{{ .Env.<ENV_VAR> }}` anywhere templating is supported.
env:
  GH_TOKEN: $GODYL_GITHUB_TOKEN
# Disable SSL verification.
no_verify_ssl: false
# Disable cache usage
no_cache: false
# A list of defaults to inherit from.
inherit:
  - default

Most of the fields also support simplified forms which is described below.

Templating

Many fields in the configuration support templating with variables like:

• {{ .Name }} - The name of the tool (name)
• {{ .Env }} - The environment variables (env), accessed with {{ .Env.<ENV_VAR> }}
• {{ .Values }} - The custom values (values), accessed with {{ .Values.<name> }}
• {{ .Exe }} - The executable name (exe.name)
• {{ .Source }} - The source type (source.type)
• {{ .Output }} - The output path (output)
• {{ .Tokens }} - The tokens for the source type (source.tokens), accessed with {{ .Tokens.<source> }}
• {{ .Version }} - The version to fetch (version.version).

Note: If the version.version field is unset, the template variable will only be available after the API call has been made.

Platform-specific variables are upper-cased and available as:

• {{ .OS }} - The operating system
• {{ .ARCH }} - The architecture
• {{ .ARCH_VERSION }} - The architecture version
• {{ .ARCH_LONG }} - The architecture with version
• {{ .IS_ARM }} - Whether the architecture is ARM
• {{ .IS_X86 }} - Whether the architecture is x86
• {{ .LIBRARY }} - The library used for the platform
• {{ .DISTRIBUTION }} - The distribution used for the platform
• {{ .EXTENSION }} - The file extension for the platform

Examples:

url: https://example.com/download/{{ .Name }}_{{ .OS }}_{{ .ARCH }}.tar.gz
url: https://releases.hashicorp.com/terraform/{{ .Version | trimPrefix "v" }}/terraform_{{ .Version | trimPrefix "v" }}_{{ .OS }}_{{ .ARCH }}.zip

Available Fields

Below is a comprehensive list of fields that can be used to configure each tool.

For each tool, you can see whether it is required, supports templating, and whether it is exported as a template variable.

name

🔴 Required • 🧩 Templated • 📤 Exports as: {{ .Name }}

The name of the tool to download. Used as display name and for inferring other fields.

name: idelchi/envprof

Used for inferrence in exe and source

description

A description of the tool, for documentation purposes.

description: Asset downloader for GitHub releases, URLs, and Go projects

version

📤 Exports as: {{ .Version }}

The version of the tool to download. Will be inferred by the source type if not provided.

Simple form:

version: v0.1.0

Full form:

version:
  version: v0.1.0
  commands:
    - --version
  patterns:
    # Match "anything-v0.1.0" or "anything-0.1.0"
    - '.*?(v?\d+\.\d+).*'

url

🧩 Templated • 📤 Exports as: {{ .URL }}

The url of the tool to download. Must be a URL to a file. Will be inferred by the source type if not provided.

url: https://github.com/idelchi/envprof/releases/download/v0.1.0/envprof_linux_amd64.tar.gz

The most common use-case is to have it inferred from the source field configuration for the github and gitlab sources.

output

🔴 Required • 🧩 Templated • 📤 Exports as: {{ .Output }}

The directory where the tool will be installed.

output: ./bin/{{ .OS }}

exe

📤 Exports as: {{ .Exe }}

Information about the executable. exe.name will be inferred from name and the source type if not explicitly provided.

Simple form:

exe: envprof

Full form:

exe:
  name: envprof
  patterns:
    - "**/{{ .Exe }}{{ .EXTENSION }}"

aliases

Aliases for the tool. Will create symlinks (or copies on Windows).

aliases:
  - gd
  - godl

values

📤 Exports as: {{ .Values }}

Arbitrary values that can be used in templates.

values:
  protocol: https

Use as:

url: {{ .Values.protocol }}://example.com/download/{{ .Name }}_{{ .OS }}_{{ .ARCH }}.tar.gz

fallbacks

Fallback strategies if no matches were made in releases.

fallbacks:
  - go

hints

🧩 Templated

Hints to help godyl find the correct tool.

hints:
  - pattern: "*{{ .Exe }}*"
    weight: 1
  - pattern: "^{{ .OS }}"
    must: true
    regex: true

If weight is not provided, it will be set to 1.

source

🔴 Required • 🧩 Templated • 📤 Exports as: {{ .Source }}

Information about the source of the tool.

GitHub source:

source:
  type: github
  github:
    repo: envprof
    owner: idelchi
    token:

URL source:

source:
  type: url
  url:
    token:
    headers:

Go source:

source:
  type: go
  go:
    command: cmd/envprof

Note: Choosing go as a source or fallback, without having a local installation and the go command available, will result in the download of the latest version of go.

Templating

Only the token fields support templating.

Furthermore, the tokens themselves are available as:

{{ .Tokens.GitHub }}
{{ .Tokens.GitLab }}
{{ .Tokens.URL }}

commands

🧩 Templated

Commands to run after the main source has been executed.

commands:
  - |
    if ! command -v wget; then
      echo "wget is not installed. Please install wget to proceed."
      exit 1
    fi
  - mkdir -p {{ .Output }}
  - wget -qO- https://github.com/idelchi/envprof/releases/download/{{ .Version }}/envprof_{{ .OS }}_{{ .ARCH }}.tar.gz | tar -xz -C {{ .Output }}

tags

Tags to filter tools.

tags:
  - cli
  - downloader

The name of the current tool will always be added to the list of tags.

strategy

🔴 Required

Strategy for updating the tool.

strategy: sync

Valid values:

• none: Skip if the tool already exists
• sync: Sync the tool to the desired version
• force: Always download and install

skip

🧩 Templated

Conditions under which to skip the tool.

skip:
  - condition: '{{ eq .OS "windows" }}'
    reason: "Tool is not available on Windows"

Templating

Only the condition field supports templating.

mode

🔴 Required

Mode for downloading and installing.

mode: find

Valid values:

• find: Download, extract, and find the executable
• extract: Download and extract directly to the output directory