Install tfctl

This topic describes how to install the tfctl CLI on your system and how to integrate it with your AI agents. The tfctl CLI is available through Homebrew, as pre-built binaries, or you can build it from source.

Install the tfctl binary

HashiCorp distributes the tfctl cli as an executable binary that you can install on supported operating systems, including Microsoft Windows, macOS, and several Linux distributions.

Visit the HashiCorp releases website and download the appropriate binary for your operating system as a zip archive.

Unzip the archive, and then make sure that the tfctl binary is available in a directory in your system's PATH.

Every build of the binary includes a SHA256SUMS and a SHA256SUMS.sig file for verification. Refer to the verify HashiCorp binary downloads tutorial for more information.

To install tfctl with Homebrew, you need Homebrew installed on your system.

Homebrew is a free and open-source package management system for macOS. You can install the official HashiCorp tap and then tfctl from your terminal.

First, install the HashiCorp tap, which is a repository of all our Homebrew packages.

$ brew tap hashicorp/tap

Now, install tfctl with the hashicorp/tap/tfctl formula.

$ brew install hashicorp/tap/tfctl

To build tfctl from source, you need Go 1.26.4 or later installed on your system.

Clone the tfctl repository and change into the new directory:

$ git clone https://github.com/hashicorp/tfctl-cli.git && cd tfctl-cli

Build and install the binary using make:
```
$ make go/install
```

Verify installation

Verify that the installation worked by opening a new terminal and using the --help flag of tfctl:

$ tfctl --help
USAGE
  tfctl <command> [Optional Flags]

DESCRIPTION
  The tfctl command-line interface (CLI) is a unified tool for managing HCP
  Terraform and Terraform Enterprise from the command line.

COMMAND GROUPS
  auth:      Authenticate with HCP Terraform.
  harness:   Install coding agent skills and see agent context.
  profile:   View and edit tfctl CLI configuration properties.
  run:       Inspect and manage runs.
  variable:  Manage variables in workspaces or variable sets.

COMMANDS
  api:     Perform any API request
  create:  Create a resource
  get:     Get or list a resource

## ...

Install shell completion

We recommend installing the shell completion module for command, argument, and API path completion:

$ tfctl --autocomplete-install

You can uninstall shell completion with the following command:

$ tfctl --autocomplete-uninstall

Install AI agent skill

If you use an AI coding assistant such as Claude Code, GitHub Copilot, IBM Bob, or similar tools, you can install the tfctl skill to enable HCP Terraform operations. AI coding agents can execute tfctl commands on your behalf, giving your agent structured access to HCP Terraform operations.

Supported AI agents

You can install the skill using the tfctl harness install <AGENT> command. Replace <AGENT> with one of the following supported AI agents:

You can install agent skills using tfctl harness install or npx.

Install a skill with tfctl

To install the skill with tfctl, run:

$ tfctl harness install <AGENT> --global

This adds the skill to your user profile so that your agents can use tfctl commands on your behalf.

Install a skill with npx

To install the skill with npx, run:

$ npx skills add hashicorp/tfctl-cli --skill 'tfctl'

This opens an interactive prompt so that you can select the skills to install.

Run tfctl in Docker

If you have a TFCTL_TOKEN environment variable set, you can invoke tfctl using Docker:

$ docker run -e TFCTL_TOKEN hashicorp/tfctl

Refer to CLI reference - Configuration for more information about environment variables.

Telemetry

By default, HashiCorp collects anonymous, redacted trace telemetry for each command invocation, including the command name, exit status, network metrics, and basic process information. You can disable telemetry at any time. Refer to Telemetry in the CLI reference for more information.

Next steps

After installing tfctl, authenticate it with HCP Terraform:

Authenticate with HCP Terraform