Skip to content

ToolFetch

ToolFetch is a CLI for fetching and installing external tools from release URLs (e.g. GitHub releases) using a YAML configuration file.

It is designed for:

  • setting up new developer machines quickly and consistently
  • reproducible tool installations

Installation demo using toolfetch.yaml:

Demo

Installation

  1. Download the latest release for your OS/architecture from Releases
  2. Move the toolfetch binary to a directory in your $PATH (e.g., system-wide: /usr/local/bin or user-specific: $HOME/.local/bin)

Verify Releases

See VERIFICATION.md for details.

Usage

Given the following configuration file named toolfetch.yaml:

destination: "/opt"
tools:
  - id: "toolfetch"
    url: "https://github.com/jdheim/toolfetch/releases/download/v0.0.7/toolfetch-0.0.7-linux-amd64.tar.gz"

When you invoke the command: toolfetch install, the latest version of the tool will be installed like this:

/opt
|-- toolfetch

Note

The configuration file is autodetected as toolfetch.yaml or toolfetch.yml in the current directory. You can customize the configuration path with -c or --config, for example: toolfetch install --config "path/to/config.yaml".

You can use optional placeholder: ${version} in url which will be replaced with version value at runtime:

destination: "/opt"
tools:
  - id: "toolfetch"
    version: "0.0.7"
    url: "https://github.com/jdheim/toolfetch/releases/download/v${version}/toolfetch-${version}-linux-amd64.tar.gz"
  - id: "intellij-idea"
    version: "2026.2.3"
    url: "https://download.jetbrains.com/idea/idea-${version}.tar.gz"

When you invoke the command again, tools will be installed like this:

/opt
|-- intellij-idea
|-- toolfetch

You can optionally define a destination key for a specific tool to install it somewhere else:

destination: "/opt"
tools:
  - id: "toolfetch"
    version: "0.0.7"
    url: "https://github.com/jdheim/toolfetch/releases/download/v${version}/toolfetch-${version}-linux-amd64.tar.gz"
    destination: "best-tools" # or absolute path: "/opt/best-tools"
  - id: "intellij-idea"
    version: "2026.2.3"
    url: "https://download.jetbrains.com/idea/idea-${version}.tar.gz"

Now, when you invoke the same command, tools will be installed like this:

/opt
|-- intellij-idea
|-- best-tools
    |-- toolfetch

Checksum Verification Formats

You can optionally define a checksums key for a specific tool to verify the downloaded archive before it is extracted:

destination: "/opt"
tools:
  - id: "toolfetch"
    version: "0.0.7"
    url: "https://github.com/jdheim/toolfetch/releases/download/v${version}/toolfetch-${version}-linux-amd64.tar.gz"
    checksums:
      sha256: "b505e3f905c9440f7719bf7b97e8e42f1d2dadc864223add1a759885c2935281"
  - id: "intellij-idea"
    version: "2026.2.3"
    url: "https://download.jetbrains.com/idea/idea-${version}.tar.gz"
    checksums:
      sha256: "68751c8ae4d49407251cd197df795fbed91b6fdc85d10c73c4649a99e496ab37"

Currently, the following Checksum Verification Formats are supported:

  • sha256
  • sha384
  • sha512

Environment Variables

You can optionally use environment variables in toolfetch.yaml using either $VAR or ${VAR} syntax.

Currently supported in:

  • destination
  • http.ssl.trustStore.path
  • tools[].destination

Example:

destination: "$HOME/tools"
tools:
  - id: "toolfetch"
    version: "0.0.7"
    url: "https://github.com/jdheim/toolfetch/releases/download/v${version}/toolfetch-${version}-linux-amd64.tar.gz"
    destination: "${DEV_HOME}/best-tools"
  - id: "intellij-idea"
    version: "2026.2.3"
    url: "https://download.jetbrains.com/idea/idea-${version}.tar.gz"

HTTP Client Settings

You can optionally define an http key to customize HTTP client settings:

destination: "/opt"
http:
  connectTimeout: 30  # HTTP connect timeout in seconds. Default: 10 seconds
  requestTimeout: 300 # HTTP request timeout in seconds. Default: 900 seconds (15 minutes)
tools:
  - id: "toolfetch"
    version: "0.0.7"
    url: "https://github.com/jdheim/toolfetch/releases/download/v${version}/toolfetch-${version}-linux-amd64.tar.gz"

If your organization uses a custom Certificate Authority, you may need to configure a TrustStore:

destination: "/opt"
http:
  ssl:
    trustStore:
      path: "/path/to/truststore" # Location of the TrustStore file containing trusted CA certificates.
                                  # Default: lib/security/cacerts or jre/lib/security/cacerts under JavaHome, which ToolFetch resolves from the first valid java executable on $PATH;
                                  # otherwise the bundled default TrustStore
      type: "PKCS12"              # TrustStore type. Default: autodetected. Set the type if autodetection fails
      # If the TrustStore is password-protected, specify the password using the TOOLFETCH_HTTP_SSL_TRUSTSTORE_PASSWORD environment variable
tools:
  - id: "toolfetch"
    version: "0.0.7"
    url: "https://github.com/jdheim/toolfetch/releases/download/v${version}/toolfetch-${version}-linux-amd64.tar.gz"

Otherwise, you may encounter an exception like this:

(certificate_unknown) PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

Note

TrustStore precedence:

  1. http.ssl.trustStore.path
  2. JavaHome/lib/security/cacerts (JDK 9+)
  3. JavaHome/jre/lib/security/cacerts (JDK 8)
  4. The bundled default TrustStore

Tip

ToolFetch resolves JavaHome from the first valid java executable on $PATH. If you import a Certificate for the CA into JavaHome/lib/security/cacerts or JavaHome/jre/lib/security/cacerts, you do not need to configure http.ssl.trustStore.

Archive and Compression Formats

Currently, the following Archive Formats are supported:

  • tar
  • zip
  • jar

Warning

7z support is planned

and Compression Formats:

  • brotli
  • bzip2
  • deflate
  • gzip
  • lz4
  • lzma
  • pack200 (for jars)
  • snappy (excluding iwa)
  • xz
  • z
  • zstandard
  • concatenated streams for bzip2, gzip, xz and lz4

Troubleshooting

ToolFetch stores log messages, including DEBUG messages, and exception stack traces in .toolfetch/toolfetch.log under the user's home directory.

The log file is overwritten on each run. Console output includes messages at INFO level and above. DEBUG level messages are available in the log file for troubleshooting.

If you encounter an issue with ToolFetch, report it in GitHub Issues. Describe the issue in detail, include toolfetch.log and steps to reproduce it.