Getting Started

Installation

Homebrew (macOS/Linux)

brew install straubt1/tap/tfx

Go

From Go version 1.19+:

go install github.com/straubt1/tfx@latest

@latest can be replaced with a specific version, e.g. @v0.2.1.

Docker

docker pull ghcr.io/straubt1/tfx:latest

Windows

Download the latest binary from the Releases page.

Authentication

The fastest way to authenticate is with tfx login. It walks you through creating a profile, validating your API token, and selecting an organization.

# HCP Terraform (default: app.terraform.io)
tfx login

# Terraform Enterprise
tfx login tfe.mycompany.com

The login flow will:

1. Ask for a profile name (defaults to default)
2. Let you open a browser to create a token or enter one directly
3. Validate the token against the API
4. Let you select a default organization
5. Save the profile to ~/.tfx.hcl

Once login completes, run tfx to launch the TUI or use CLI commands directly.

TUI vs CLI

TFx provides two ways to interact with your infrastructure:

	Interactive TUI	CLI Commands
Launch	tfx	tfx <command> (e.g., tfx ws list)
Best for	Exploring, browsing, investigating	Scripting, automation, CI/CD
Output	Terminal UI with keyboard navigation	Tables or JSON (--json)
Authentication	Same config file and profiles	Same config file and profiles

Both modes share the same configuration, API client, and authentication. Use whichever fits your workflow — or both.

Config file

tfx login writes profiles to ~/.tfx.hcl. You can also create or edit this file manually.

Migration required

Starting in v0.3.3, TFx requires profile blocks in .tfx.hcl. Flat key formats and legacy tfe-prefixed keys (e.g. tfeHostname, tfeOrganization, tfeToken) are no longer supported. If your config file uses the old format, the easiest way to migrate is to run tfx login — it will create a profile block for you automatically.

Profile format

Each profile is a named block containing your connection details:

profile "default" {
  hostname     = "app.terraform.io"
  organization = "my-org"
  token        = "my-token"
}

You can define multiple profiles for different environments:

profile "staging" {
  hostname     = "tfe.staging.myco.internal"
  organization = "my-org-staging"
  token        = "staging-token"
}

profile "production" {
  hostname     = "tfe.myco.internal"
  organization = "my-org"
  token        = "my-token"
}

Profile properties

Property	HCL key	Default	Required
Hostname	hostname	app.terraform.io	No
Organization	organization	(none)	No
Token	token	(none)	Yes

Selecting a profile

By default, TFx uses the profile named default. To use a different profile:

# Launch the TUI with a specific profile
tfx --profile staging

# Use with CLI commands
tfx workspace list --profile staging

# Via environment variable
TFX_PROFILE=staging tfx workspace list

The TUI also reads the active profile and displays it in the profile bar at the top of the screen.

Config file discovery

TFx looks for .tfx.hcl automatically — no flag required:

1. ./.tfx.hcl — current working directory (checked first)
2. ~/.tfx.hcl — home directory (fallback)

To use a specific file instead, set either:

• --config-file /path/to/.tfx.hcl flag, or
• TFX_CONFIG_FILE=/path/to/.tfx.hcl environment variable

The flag takes precedence over the env var; both override auto-discovery.

Configuration precedence

When the same setting is specified in multiple places, the highest-precedence source wins:

1. CLI flags (--hostname, --organization, --token) — highest
2. Environment variables (TFE_HOSTNAME, TFE_ORGANIZATION, TFE_TOKEN)
3. Profile values from .tfx.hcl
4. Defaults (hostname defaults to app.terraform.io)