> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/tools-terraform/vendor/github.com/hashicorp/hc-install.md).

# hc-install

An **experimental** Go module for downloading or locating HashiCorp binaries, verifying signatures and checksums, and asserting version constraints.

This module is a successor to tfinstall, available in pre-1.0 versions of [terraform-exec](https://github.com/hashicorp/terraform-exec). Current users of tfinstall are advised to move to hc-install before upgrading terraform-exec to v1.0.0.

## hc-install is not a package manager

This library is intended for use within Go programs or automated environments (such as CIs) which have some business downloading or otherwise locating HashiCorp binaries.

The included command-line utility, `hc-install`, is a convenient way of using the library in ad-hoc or CI shell scripting outside of Go.

`hc-install` does **not**:

* Determine suitable installation path based on target system. e.g. in `/usr/bin` or `/usr/local/bin` on Unix based system.
* Deal with execution of installed binaries (via service files or otherwise).
* Upgrade existing binaries on your system.
* Add nor link downloaded binaries to your `$PATH`.

## API

The `Installer` offers a few high-level methods:

* `Ensure(context.Context, []src.Source)` to find, install, or build a product version
* `Install(context.Context, []src.Installable)` to install a product version

### Sources

The `Installer` methods accept number of different `Source` types. Each comes with different trade-offs described below.

* `fs.{AnyVersion,ExactVersion,Version}` - Finds a binary in `$PATH` (or additional paths)
  * **Pros:**
    * This is most convenient when you already have the product installed on your system which you already manage.
  * **Cons:**
    * Only relies on a single version, expects *you* to manage the installation
    * *Not recommended* for any environment where product installation is not controlled or managed by you (e.g. default GitHub Actions image managed by GitHub)
* `releases.{LatestVersion,ExactVersion}` - Downloads, verifies & installs any known product from `releases.hashicorp.com`
  * **Pros:**
    * Fast and reliable way of obtaining any pre-built version of any product
    * Allows installation of enterprise versions
  * **Cons:**
    * Installation may consume some bandwidth, disk space and a little time
    * Potentially less stable builds (see `checkpoint` below)
* `checkpoint.LatestVersion` - Downloads, verifies & installs any known product available in HashiCorp Checkpoint
  * **Pros:**
    * Checkpoint typically contains only product versions considered stable
  * **Cons:**
    * Installation may consume some bandwidth, disk space and a little time
    * Currently doesn't allow installation of old versions or enterprise versions (see `releases` above)
* `build.GitRevision` - Clones raw source code and builds the product from it
  * **Pros:**
    * Useful for catching bugs and incompatibilities as early as possible (prior to product release).
  * **Cons:**
    * Building from scratch can consume significant amount of time & resources (CPU, memory, bandwidth, disk space)
    * There are no guarantees that build instructions will always be up-to-date
    * There's increased likelihood of build containing bugs prior to release
    * Any CI builds relying on this are likely to be fragile

## Example Usage

See examples at <https://pkg.go.dev/github.com/hashicorp/hc-install#example-Installer>.

## CLI

In addition to the Go library, which is the intended primary use case of `hc-install`, we also distribute CLI.

The CLI comes with some trade-offs:

* more limited interface compared to the flexible Go API (installs specific versions of products via `releases.ExactVersion`)
* minimal environment pre-requisites (no need to compile Go code)
* see ["hc-install is not a package manager"](https://github.com/hashicorp/hc-install#hc-install-is-not-a-package-manager)

### Installation

Given that one of the key roles of the CLI/library is integrity checking, you should choose the installation method which involves the same level of integrity checks, and/or perform these checks yourself. `go install` provides only minimal to no integrity checks, depending on exact use. We recommend any of the installation methods documented below.

#### Homebrew (macOS / Linux)

[Homebrew](https://brew.sh)

```sh
brew install hashicorp/tap/hc-install
```

#### Linux

We support Debian & Ubuntu via apt and RHEL, CentOS, Fedora and Amazon Linux via RPM.

You can follow the instructions in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide) to install the package from the official HashiCorp-maintained repositories. The package name is `hc-install` in all repositories.

#### Other platforms

1. [Download for the latest version](https://releases.hashicorp.com/hc-install/) relevant for your operating system and architecture.
2. Verify integrity by comparing the SHA256 checksums which are part of the release (called `hc-install_<VERSION>_SHA256SUMS`).
3. Install it by unzipping it and moving it to a directory included in your system's `PATH`.
4. Check that you have installed it correctly via `hc-install --version`. You should see the latest version printed to your terminal.

### Usage

```
Usage: hc-install install [options] -version <version> <product>

  This command installs a HashiCorp product.
  Options:
    -version  [REQUIRED] Version of product to install.
    -path     Path to directory where the product will be installed.
              Defaults to current working directory.
    -log-file Path to file where logs will be written. /dev/stdout
              or /dev/stderr can be used to log to STDOUT/STDERR.
```

```sh
hc-install install -version 1.3.7 terraform
```

```sh
hc-install: will install terraform@1.3.7
installed terraform@1.3.7 to /current/working/dir/terraform
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/tools-terraform/vendor/github.com/hashicorp/hc-install.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
