# Add Pre-commit Hooks With fmt, validate, tflint and terraform-docs to a Terraform Repo

Yes. An agent adds a pre-commit setup that runs terraform fmt, validate, tflint and terraform-docs on your Terraform repo, runs it once, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pre-commit-hooks/terraform/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the configuration and what already checks it. In a repository like hashicorp-education/learn-terraform-provision-eks-cluster there are four `.tf` files and nothing else that runs: `terraform.tf` requires Terraform `~> 1.3` and pins `hashicorp/aws` at `~> 5.47.0` with `random`, `tls` and `cloudinit`; `main.tf` wires the `terraform-aws-modules/vpc/aws` module at `5.8.1`, the `eks` module at `20.8.5` and an `iam-assumable-role-with-oidc` module at `5.39.0` for the EBS CSI driver; `variables.tf` has one `region` variable and `outputs.tf` four outputs. `.terraform.lock.hcl` is committed, so `terraform init` installs the recorded provider versions, and there is no `.github/` directory, no `.pre-commit-config.yaml`, no `.tflint.hcl`, and a two-line README that documents none of the inputs or outputs.

It writes `.pre-commit-config.yaml` with two hook sources. From `pre-commit/pre-commit-hooks` come `end-of-file-fixer`, `trailing-whitespace` and `check-yaml`; the first run of `trailing-whitespace` matters here because two comment lines in `main.tf` end in a space. From `antonbabenko/pre-commit-terraform` come `terraform_fmt`, `terraform_validate`, `terraform_tflint` and `terraform_docs`. The validate hook initialises the directory without a backend before it validates, which is what lets it run on a laptop with no AWS credentials; the agent adds `--hook-config=--retry-once-with-cleanup=true` so a stale `.terraform` directory is cleared and retried rather than failing the commit. The tflint hook gets `--args=--config=__GIT_WORKING_DIR__/.tflint.hcl`, and a new `.tflint.hcl` enables the `aws` ruleset plugin with the `terraform` ruleset's recommended preset, so checks like unused declarations and invalid instance types run against the two node groups of `t3.small` instances in `main.tf`.

`terraform_docs` needs markers to write between, so the agent adds `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->` to `README.md` under the existing tutorial link and runs the hook once, which generates the requirements, providers, modules, inputs and outputs tables from the real files: the `region` input with its `us-east-2` default, the `cluster_endpoint`, `cluster_security_group_id`, `region` and `cluster_name` outputs, and the three module calls with their versions. A `.github/workflows/pre-commit.yml` runs `pre-commit run --all-files` on every pull request with Terraform, tflint and terraform-docs installed on the runner, so the hooks are not only local.

The proof is one full run in the sandbox. The agent installs `pre-commit`, a Terraform matching `required_version`, `tflint` and `terraform-docs`, runs `pre-commit run --all-files`, and reads what changed: whitespace fixes, any reformatting `terraform fmt` applied, the generated README section, and any tflint finding, which it either fixes when the fix is plain or lists in the pull request with the rule name. Nothing is applied against AWS and no state is touched; `validate` with no backend is the deepest Terraform step.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add pre-commit hooks to this Terraform repository. Read terraform.tf, main.tf, variables.tf, outputs.tf, .terraform.lock.hcl, .gitignore and README.md first. Write .pre-commit-config.yaml using pre-commit/pre-commit-hooks for end-of-file-fixer, trailing-whitespace and check-yaml, and antonbabenko/pre-commit-terraform for terraform_fmt, terraform_validate with retry-once-with-cleanup, terraform_tflint pointed at a repository .tflint.hcl, and terraform_docs. Write .tflint.hcl enabling the terraform recommended preset and the aws ruleset plugin. Add BEGIN_TF_DOCS and END_TF_DOCS markers to README.md and let the hook generate the tables. Add a GitHub Actions workflow that runs pre-commit run --all-files on pull requests with terraform, tflint and terraform-docs installed. Install the tools, run pre-commit run --all-files, fix what the hooks change or report, run again until it passes, and open a pull request that lists every finding. Do not run terraform plan or apply.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch with `.pre-commit-config.yaml`, `.tflint.hcl`, `.github/workflows/pre-commit.yml`, the README with its generated section, and whatever the hooks changed in the `.tf` files, which for whitespace is a few characters. `.terraform.lock.hcl`, the module versions and the variable default are unchanged.

The description shows the final `pre-commit run --all-files` output with every hook passing, lists each finding the first run produced and what was done about it, and pastes the generated README tables so a reviewer sees the inputs and outputs the documentation now carries. The install and run commands are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer runs `pre-commit install` locally so the hooks fire on their own commits, checks the tflint rules they want on or off in `.tflint.hcl`, and decides whether `terraform_docs` should also update the README on every commit or only in CI. A follow-up message to the same session can add `terraform_trivy` or `terraform_checkov` to the same config.

## Run it on every terminal hand-off

A platform engineer who wants this in every Terraform repository starts one run per repository from the terminal with this body, changing only the repository URL. Each run reads that repository's own providers, modules and README and produces a configuration that fits it, in its own sandbox.

Send a `request_id`, a UUID, with each body so a retried start returns the run it already began. The pull request is on the run's `GET /o/{org}/sessions/{id}` answer when it is open.

## Why run it on Rush?

The hard part of this job is not writing the YAML, it is proving that the hooks pass on the real code with the real tools installed, which means a Terraform of the right version, a tflint with the AWS plugin downloaded, and a `terraform init` that fetches the pinned providers. The agent does that once in a clean sandbox and ships the result with the run log, so the first commit after merge does not fail on a surprise finding.

The pull request carries the final hook output and the first run's findings side by side, so a reviewer sees what the hooks will catch from now on. Many repositories can be done at once, each in its own sandbox, each with one pull request.

## Frequently asked questions

### Does the validate hook need AWS credentials?

No. It initialises without a backend, so providers are downloaded and the configuration is checked for internal consistency without contacting AWS or reading state. The lock file keeps the provider versions the repository already uses.

### Will terraform-docs rewrite my whole README?

Only the text between the two markers the agent adds. The tutorial link above them stays, and anything written below the end marker is left alone. The generated tables are regenerated from the `.tf` files on every run, which is the point.

### What does tflint check that validate does not?

Rules rather than syntax: the `terraform` ruleset flags unused declarations, deprecated syntax and missing version constraints, and the `aws` plugin knows the provider's resource arguments, for example whether an instance type exists. `terraform validate` only knows the configuration is well formed.

### Why also run it in GitHub Actions?

`pre-commit install` is per clone, and a contributor who skips it can still push. The workflow runs the same `pre-commit run --all-files` on every pull request with the same tools, so the hooks are the gate either way.

### Can I add security scanning later?

Yes. The same hook source provides `terraform_trivy` and `terraform_checkov`; adding either is one more entry in `.pre-commit-config.yaml` plus the tool on the CI runner, which a follow-up message to the session can do.

## More Terraform jobs

- [Move Terraform State to a Remote S3 Backend](https://getrush.ai/run/add-remote-state/terraform/)
- [Add Renovate to a Terraform Module Repository](https://getrush.ai/run/add-renovate/terraform/)
- [Add Consistent Resource Tags to a Terraform Configuration](https://getrush.ai/run/add-resource-tags/terraform/)

## The same job on other stacks

- [Add Pre-commit Hooks to a Textual App](https://getrush.ai/run/add-pre-commit-hooks/textual/)
- [Add pre-commit Hooks to an Ansible Role](https://getrush.ai/run/add-pre-commit-hooks/ansible/)
- [Add pre-commit Hooks to a CMake C++ Project](https://getrush.ai/run/add-pre-commit-hooks/cmake/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
