Skip to content

Welcome to TFx Docs

tfx is a standalone CLI for Terraform Cloud and Terraform Enterprise.

The initial focus of tfx was to execute the API-Driven workflow for a Workspace but has grown to manage multiple aspects of the platform.

Note: This CLI is still under active development and subject to change!

Installation

Binaries are created as part of a release, check out the Release Page for the latest version.

MacOs Installation 

version="x.x.x"
curl -L -o tfx "https://github.com/straubt1/tfx/releases/download/${version}/tfx_darwin_amd64"
chmod +x tfx

Linux Installation 

version="x.x.x"
curl -L -o tfx "https://github.com/straubt1/tfx/releases/download/${version}/tfx_linux_amd64"
chmod +x tfx

Windows Installation 

version="x.x.x"
curl -L -o tfx.exe "https://github.com/straubt1/tfx/releases/download/${version}/tfx_windows_amd64"

Go Installation

From Go version 1.19, the following is supported. @latest can be @$VERSION 

go install github.com/straubt1/tfx@latest

Container

tfx is also packaged and published as a OCI Container Image in the Github Container Registry: 

docker pull ghcr.io/straubt1/tfx:latest

Configuration File

Each command has the ability to pass in parameters via flags, however there are several that are required for every command.

Example:

  --tfeHostname string       The hostname of TFE without the schema. Can also be set with the environment variable TFE_HOSTNAME. (default "app.terraform.io")
  --tfeOrganization string   The name of the TFx Organization. Can also be set with the environment variable TFE_ORGANIZATION.
  --tfeToken string          The API token used to authenticate to TFx. Can also be set with the environment variable TFE_TOKEN.

Rather than passing these flags on each call, it is recommended to put values such as hostname, token, etc... into a configuration file.

For convenience, creating a file with the name .tfx.hcl and placing it in one of the following locations will auto load these values:

  • Local path of where tfx commands are run from, ./.tfx.hcl
  • Home directory, ~/.tfx.hcl
  • Any directory you like, must specify with this path, --config /private/somefolder/.tfx.hcl

Example ./.tfx.hcl: 

tfeHostname     = "tfe.rocks" (omit to default to Terraform Cloud)
tfeOrganization = "my-awesome-org"
tfeToken        = "<Generated from Terraform Enterprise or Terraform Cloud>"

Common flags can also be set via environment values by using a key that is capitalized version of the flag. This only works for the following:

  • TFE_HOSTNAME
  • TFE_ORGANIZATION
  • TFE_TOKEN

Output Types

Most commands support a --json (or -j for short) flag that will return a proper JSON response.

Note: Not all commands today support this flag and will ignore it.

Default Output:

$ tfx variable list -w tfx-test               
Using config file: /Users/tstraub/.tfx.hcl
List Variables for Workspace: tfx-test
╭──────────────────────┬───────────┬────────────────┬───────────┬───────┬───────────┬──────────────────────╮
│ ID                   │ KEY       │ VALUE          │ SENSITIVE │ HCL   │ CATEGORY  │ DESCRIPTION          │
├──────────────────────┼───────────┼────────────────┼───────────┼───────┼───────────┼──────────────────────┤
│ var-7XYNuuo4tMjXeXG4 │ variable7 │ {              │ false     │ true  │ terraform │ I am a map in a file │
│                      │           │   "a" = "1",   │           │       │           │                      │
│                      │           │   "b" = "zoo", │           │       │           │                      │
│                      │           │   "c" = "42"   │           │       │           │                      │
│                      │           │ }              │           │       │           │                      │
│ var-MJaLJ7czxKuU48eu │ variable3 │ It is friday   │ false     │ false │ env       │ I am environmental   │
╰──────────────────────┴───────────┴────────────────┴───────────┴───────┴───────────┴──────────────────────╯

JSON Output:

$ tfx variable list -w tfx-test --json | jq .
[
  {
    "Category": "terraform",
    "Description": "I am a map in a file",
    "HCL": true,
    "Id": "var-7XYNuuo4tMjXeXG4",
    "Key": "variable7",
    "Sensitive": false,
    "Value": "{\n  \"a\" = \"1\",\n  \"b\" = \"zoo\",\n  \"c\" = \"42\"\n}"
  },
  {
    "Category": "env",
    "Description": "I am environmental",
    "HCL": false,
    "Id": "var-MJaLJ7czxKuU48eu",
    "Key": "variable3",
    "Sensitive": false,
    "Value": "It is friday"
  }
]

Disclaimer

TFx is an open source project built for use with Terraform Cloud and Terraform Enterprise under the MIT License (MIT).

While this tool is not officially supported by HashiCorp, it's current primary contributors are current or former HashiCorp employees.

References

https://github.com/hashicorp/go-tfe https://github.com/spf13/cobra