https://github.com/hashicorp/python-tfe
HCP Terraform/Enterprise API Client/SDK in Python
https://github.com/hashicorp/python-tfe
doormat-managed python sdk terraform terraform-cloud terraform-enterprise
Last synced: 2 months ago
JSON representation
HCP Terraform/Enterprise API Client/SDK in Python
- Host: GitHub
- URL: https://github.com/hashicorp/python-tfe
- Owner: hashicorp
- License: mpl-2.0
- Created: 2025-08-22T06:12:37.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-04-24T09:28:58.000Z (2 months ago)
- Last Synced: 2026-04-24T10:39:04.787Z (2 months ago)
- Topics: doormat-managed, python, sdk, terraform, terraform-cloud, terraform-enterprise
- Language: Python
- Homepage: https://pypi.org/project/pytfe/
- Size: 1000 KB
- Stars: 10
- Watchers: 2
- Forks: 11
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# HCP Terraform and Terraform Enterprise **Python** Client (pyTFE)
[](https://pypi.org/project/pytfe/)
[](https://pypi.org/project/pytfe/)
[](https://github.com/hashicorp/python-tfe/actions/workflows/test.yml)
[](./LICENSE)
[](https://github.com/hashicorp/python-tfe/issues)
The official **Python** API client for [HCP Terraform and Terraform Enterprise](https://www.hashicorp.com/products/terraform).
This client targets the [HCP Terraform V2 API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs).
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
```python
from pytfe import TFEClient, TFEConfig
config = TFEConfig(
address="https://tfe.local",
token="insert-your-token-here",
timeout=30.0,
user_agent_suffix="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](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens) for the HCP Terraform or Terraform Enterprise instance.
Environment variables are used as a fallback when `address` or `token` are not provided explicitly:
#### Using the default configuration
```python
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
```python
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/`](./examples) directory for runnable snippets covering common workflows (workspaces, variables, configuration versions, runs/plans/applies, state, agents).
## Running tests
See [`TESTS.md`](./docs/TESTS.md). Typical flow:
```bash
pip install -e .[dev]
make test
```
## Issues and Contributing
See [`CONTRIBUTING.md`](./docs/CONTRIBUTING.md). We welcome issues and pull requests.
## Releases
See [`RELEASES.md`](./docs/RELEASES.md).
## License
This project is licensed under the **MPL-2.0**. See [`LICENSE`](./LICENSE).