https://github.com/hashicorp/go-tfe
HCP Terraform/Enterprise API Client/SDK in Golang
https://github.com/hashicorp/go-tfe
cloud sdk terraform-cloud terraform-enterprise tfe
Last synced: about 2 months ago
JSON representation
HCP Terraform/Enterprise API Client/SDK in Golang
- Host: GitHub
- URL: https://github.com/hashicorp/go-tfe
- Owner: hashicorp
- License: mpl-2.0
- Created: 2018-04-30T16:56:47.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-04-09T16:54:07.000Z (3 months ago)
- Last Synced: 2025-04-13T23:57:31.517Z (3 months ago)
- Topics: cloud, sdk, terraform-cloud, terraform-enterprise, tfe
- Language: Go
- Homepage: https://pkg.go.dev/github.com/hashicorp/go-tfe
- Size: 3.73 MB
- Stars: 239
- Watchers: 277
- Forks: 104
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Audit: audit_trail.go
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
HCP Terraform and Terraform Enterprise Go Client
==============================
[](https://github.com/hashicorp/go-tfe/actions/workflows/ci.yml)
[](https://github.com/hashicorp/go-tfe/blob/main/LICENSE)
[](https://godoc.org/github.com/hashicorp/go-tfe)
[](https://goreportcard.com/report/github.com/hashicorp/go-tfe)
[](https://github.com/hashicorp/go-tfe/issues)
The official Go API client for [HCP Terraform and Terraform Enterprise](https://www.hashicorp.com/products/terraform).
This client supports the [HCP Terraform V2 API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs).
As Terraform Enterprise is a self-hosted distribution of HCP Terraform, this
client supports both HCP Terraform and Terraform Enterprise use cases. In all package
documentation and API, the platform will always be stated as 'Terraform
Enterprise' - but a feature will be explicitly noted as only supported in one or
the other, if applicable (rare).
## Version Information
Almost always, minor version changes will indicate backwards-compatible features and enhancements. Occasionally, function signature changes that reflect a bug fix may appear as a minor version change. Patch version changes will be used for bug fixes, performance improvements, and otherwise unimpactful changes.
## Example Usage
Construct a new TFE client, then use the various endpoints on the client to
access different parts of the Terraform Enterprise API. The following example lists
all organizations.
### (Recommended Approach) Using custom config to provide configuration details to the API client
```go
import (
"context"
"log"
"github.com/hashicorp/go-tfe"
)
config := &tfe.Config{
Address: "https://tfe.local",
Token: "insert-your-token-here",
RetryServerErrors: true,
}
client, err := tfe.NewClient(config)
if err != nil {
log.Fatal(err)
}
orgs, err := client.Organizations.List(context.Background(), nil)
if err != nil {
log.Fatal(err)
}
```
### Using the default config with env vars
The default configuration makes use of the `TFE_ADDRESS` and `TFE_TOKEN` environment variables.
1. `TFE_ADDRESS` - URL of a HCP Terraform or Terraform Enterprise instance. Example: `https://tfe.local`
1. `TFE_TOKEN` - An [API token](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens) for the HCP Terraform or Terraform Enterprise instance.
**Note:** Alternatively, you can set `TFE_HOSTNAME` which serves as a fallback for `TFE_ADDRESS`. It will only be used if `TFE_ADDRESS` is not set and will resolve the host to an `https` scheme. Example: `tfe.local` => resolves to `https://tfe.local`
The environment variables are used as a fallback to configure TFE client if the Address or Token values are not provided as in the cases below:
#### Using the default configuration
```go
import (
"context"
"log"
"github.com/hashicorp/go-tfe"
)
// Passing nil to tfe.NewClient method will also use the default configuration
client, err := tfe.NewClient(tfe.DefaultConfig())
if err != nil {
log.Fatal(err)
}
orgs, err := client.Organizations.List(context.Background(), nil)
if err != nil {
log.Fatal(err)
}
```
#### When Address or Token has no value
```go
import (
"context"
"log"
"github.com/hashicorp/go-tfe"
)
config := &tfe.Config{
Address: "",
Token: "",
}
client, err := tfe.NewClient(config)
if err != nil {
log.Fatal(err)
}
orgs, err := client.Organizations.List(context.Background(), nil)
if err != nil {
log.Fatal(err)
}
```
## Documentation
For complete usage of the API client, see the [full package docs](https://pkg.go.dev/github.com/hashicorp/go-tfe).
## Examples
See the [examples directory](https://github.com/hashicorp/go-tfe/tree/main/examples).
## Running tests
See [TESTS.md](docs/TESTS.md).
## Issues and Contributing
See [CONTRIBUTING.md](docs/CONTRIBUTING.md)
## Releases
See [RELEASES.md](docs/RELEASES.md)