go-tfe Go SDK

The client uses a path-based naming convention for its API surface. Every interface starting with API follows a pattern where you chain path segments followed by the operation method (e.g., Get, Post, Patch, Delete).

• Unparameterized paths: client.API.Account().Details().Get(ctx, nil) maps to GET /account/details.
• Parameterized paths: client.API.Organizations().ByOrganization_name("foo").Projects().Post(ctx, body, nil) maps to POST /organizations/{organization_name}/projects.

The v2/examples directory contains runnable examples of the SDK client. You can build the example CLI tool using go build. Once built, you can explore available subcommands using the --help flag.

# Build the example client
$ go build -o tfe cmd/tfe/main.go

# Explore subcommands
$ ./tfe account --help

To install the HCP Terraform and Terraform Enterprise Go SDK Client 2.0, use the go get command with the v2 suffix.

go get github.com/hashicorp/go-tfe/v2

The v2 module introduces completely new interfaces. While v1 and v2 can be imported into the same project simultaneously, significant behavioral changes exist:

• Configuration: The v2 module is no longer sensitive to environment variables. You must configure the client using the NewClient function.
• Initialization: v2 no longer performs an initial request to decode and store platform configuration.
• Mocks: v2 does not include up-to-date mocks. If you require mocks for testing, you may need to use the mocks found in the v1 mocks module.

To upgrade, fetch the v2 module using the following command (replace VERSION with your desired version):

go get github.com/hashicorp/go-tfe/v2@VERSION

$ go get github.com/hashicorp/go-tfe/v2@VERSION

To run the examples, you must provide authentication and connection details via the following environment variables:

• TFE_TOKEN: Your HCP Terraform or Terraform Enterprise API token.
• TFE_ADDRESS: The URL of your Terraform Cloud/Enterprise instance (e.g., https://app.terraform.io).

$ TFE_TOKEN=example TFE_ADDRESS=https://app.eu.terraform.io ./tfe account details

To access HTTP response headers, you must use kiota-http-go to create a HeadersInspectionOptions object and include it in the request's Options slice.

import (
	"github.com/microsoft/kiota-abstractions-go"
	khttp "github.com/microsoft/kiota-http-go"
)

// 1. Create the HeadersInspectionRequestOption
inspectionOptions := khttp.NewHeadersInspectionOptions()
inspectionOptions.InspectResponseHeaders = true

// 2. Add the option to the RequestConfiguration
req := abstractions.RequestConfiguration[abstractions.DefaultQueryParameters]{
	Options: []abstractions.RequestOption{inspectionOptions},
}

// 3. Execute the request
_, err = client.API.Account().Details().Get(ctx, &req)

// 4. Access the headers
headers := inspectionOptions.GetResponseHeaders()
for _, key := range headers.ListKeys() {
	log.Printf("%s: %v", key, headers.Get(key))
}

For endpoints that accept a request body, you must construct the appropriate data envelope and parse values for type enums using the provided models package. All operations follow a similar pattern of setting attributes on a data object and wrapping it in an envelope.

// Example: Creating a variable envelope
func NewVar(key, value, category string, sensitive bool) *models.VarsEnvelope {
	hcl := false
	attrib := &models.Vars_attributes{}
	attrib.SetKey(&key)
	attrib.SetValue(&value)
	attrib.SetSensitive(&sensitive)
	attrib.SetHcl(&hcl)
	attrib.SetCategory(mustParseCategory(category))

	data := &models.Vars{}
	data.SetAttributes(attrib)

	body := &models.VarsEnvelope{}
	body.SetData(data)

	return body
}

The Client struct is the primary entry point and organizes functionality into two main namespaces:

1. API: An *api.ApiClient used to access the core Terraform Enterprise API resources.
2. Meta: A Meta struct containing APIs that provide metadata about the TFE instance itself, such as IPRanges and OpenAPI definitions.

Example structure:

// Accessing core API
client.API.Workspaces.Get(...)

// Accessing metadata
client.Meta.IPRanges.List(...)

Use tfe.NewClient with a *tfe.Config object to initialize the client. At a minimum, you must provide a Token for authentication. The Address defaults to https://app.terraform.io if not specified.

client, err := tfe.NewClient(&tfe.Config{
	Token:   os.Getenv("TFE_TOKEN"),
	Address: os.Getenv("TFE_ADDRESS"),
})

To add query parameters to a GET request, use the RequestConfiguration type provided by kiota-abstractions-go. Each operation defines its own specific query parameter type based on its path.

import (
	"github.com/hashicorp/go-tfe/v2/api/organizations"
	abstractions "github.com/microsoft/kiota-abstractions-go"
)

// Include subscriptions in the response by setting the include query parameter
includeSubscriptions := organizations.SUBSCRIPTION_GETINCLUDEQUERYPARAMETERTYPE
req := abstractions.RequestConfiguration[organizations.OrganizationsRequestBuilderGetQueryParameters]{
	QueryParameters: &organizations.OrganizationsRequestBuilderGetQueryParameters{
		Include: &includeSubscriptions,
	},
}

response, err := client.API.Organizations().Get(ctx, &req)

The Config struct allows you to customize the behavior of the API client. Key configuration options include:

• Address: The base URL of the Terraform Enterprise API (defaults to https://app.terraform.io).
• BasePath: The API base path (defaults to /api/v2).
• Token: The API token required for authentication (mandatory).
• Headers: Custom http.Header values to be included in every request.
• RetryRateLimited: Enables automatic retries for rate-limited requests.
• RetryServerErrors: Enables retry logic for server-side errors.
• RetryMaxRetries: The maximum number of retry attempts (defaults to 5).
• RetryHook: A RetryHookCallback function invoked before each retry.
• HTTPTransport: An optional http.RoundTripper to use as the base transport.