HCP Terraform and Terraform Enterprise Python Client (pyTFE)

The official Python API client for HCP Terraform and Terraform Enterprise.

This client targets the HCP Terraform V2 API. As Terraform Enterprise is the self-hosted distribution of HCP Terraform, this client supports both HCP Terraform and Terraform Enterprise use cases. In this repository and API, we refer to the platform generically as Terraform Enterprise unless a feature is explicitly called out as only supported in one or the other (rare).

Version Information

We follow Semantic Versioning. During the initial alpha period we use 0.y.z:

• Minor (0.y.z → 0.(y+1).z): new, backwards-compatible features and enhancements.
• Patch (0.y.z → 0.y.(z+1)): bug fixes and performance improvements.
• Occasionally, a function signature change that fixes incorrect behavior may appear in a minor version.

Example Usage

Construct a new pyTFE client, then use the resource services on the client to access different parts of the Terraform Enterprise API. The following example lists all organizations.

(Recommended) Using explicit config

from pytfe import TFEClient, TFEConfig

config = TFEConfig(
    host="https://tfe.local",
    token="insert-your-token-here",
    retry_server_errors=True,
    timeout=30.0,
    user_agent="example-app/0.1 pytfe/0.1",
)

client = TFEClient(config)

orgs = client.organizations.list()
for org in orgs.items:
    print(org.name)

Using the default config with environment variables

The default configuration reads the TFE_ADDRESS and TFE_TOKEN environment variables.

1. TFE_ADDRESS — URL of an HCP Terraform or Terraform Enterprise instance. Example: https://tfe.local
2. TFE_TOKEN — An API token for the HCP Terraform or Terraform Enterprise instance.

Environment variables are used as a fallback when host or token are not provided explicitly:

Using the default configuration

from pytfe import TFEClient, TFEConfig

# Equivalent to providing no values; falls back to env vars if set.
client = TFEClient(TFEConfig())
orgs = client.organizations.list()
for org in orgs.items:
    print(org.name)

When host or token is empty

from pytfe import TFEClient, TFEConfig

config = TFEConfig(address="", token="")
client = TFEClient(config)

orgs = client.organizations.list()
for org in orgs.items:
    print(org.name)

Documentation

• API reference and guides (SDK): coming soon
• Terraform Enterprise API: https://developer.hashicorp.com/terraform/enterprise/api-docs

Examples

See the examples/ directory for runnable snippets covering common workflows (workspaces, variables, configuration versions, runs/plans/applies, state, agents).

Running tests

See TESTS.md. Typical flow:

pip install -e .[dev]
make test

Issues and Contributing

See CONTRIBUTING.md. We welcome issues and pull requests.

Releases

See RELEASES.md.

License

This project is licensed under the MPL-2.0. See LICENSE.