Using Gemini CLI with Terraform: A Practical Guide

Gemini CLI is a terminal coding agent from Google that you start in a Terraform project with gemini. It works best when project-specific rules live in GEMINI.md, and for Terraform that means explicit commands, environment boundaries, and an approval rule before any apply. This guide shows how to run it safely on real Terraform codebases.

Where Gemini CLI helps with Terraform

Terraform is declarative and spread across many files; changes can ripple through modules, state, and provider versions. Gemini CLI can reason across variables.tf, main.tf, outputs.tf, and module callers in one pass, which is more useful than single-file autocomplete. It is especially good for repetitive changes like adding tags, enforcing naming conventions, moving blocks, and upgrading providers, because it can apply the same HCL pattern consistently and then run terraform fmt and terraform validate. The key is to keep that validation loop tight rather than letting it design a large refactor in one turn.

Prepare the repo with GEMINI.md

Add GEMINI.md at the repository root. This file is the agent’s source of truth for commands, folder conventions, and Terraform-specific rules. Keep it concrete; vague instructions produce vague changes. Here is a realistic example for a multi-environment Terraform repo:

# GEMINI.md

## Commands
- Init: terraform init -backend-config=environments/dev/backend.conf
- Plan: terraform plan -var-file=environments/dev/terraform.tfvars
- Apply: terraform apply -var-file=environments/dev/terraform.tfvars
- Validate: terraform validate
- Format check: terraform fmt -check -recursive
- Lint: tflint --recursive
- Test: terraform test

## Folder conventions
- environments/<env>/ is a root module; each has its own backend.conf and terraform.tfvars.
- modules/<name>/ contains reusable modules; no provider blocks, only required_providers version constraints.
- Variables and outputs use snake_case. Every variable has type and description; every output has description.

## Terraform rules
- Never run terraform apply or terraform destroy. Show the command and wait for approval.
- After any edit, run terraform fmt, terraform validate, and tflint.
- Prefer plan -out and review the plan before proposing a final diff.
- When changing a module signature, update variables.tf, outputs.tf, and all module callers in the same change.
- Keep remote state untouched; do not remove backend blocks or add local state overrides.
- After provider version changes, run terraform init -upgrade and commit the lock file change.

A short file map helps the agent stay on the right paths:

You may also point the agent to the how to use Gemini CLI guide if it needs more context.

Keep changes small: plan, edit, validate, review

Treat it like an AI pair programming session, not a one-shot code generator. The safest loop is: plan a small change, let the agent edit, run format/validate/lint, inspect the git diff and terraform plan, then repeat. Avoid broad prompts like “improve the infrastructure”; prefer one resource or one module boundary.

Example prompts that work well:

• “Add the tag team = 'platform' to all aws_s3_bucket and aws_instance resources under environments/dev, then run terraform fmt and terraform validate.”
• “In modules/static-site, replace the repeated inline S3 bucket policy with a reusable aws_iam_policy_document data source or a submodule. Update all callers, then show the terraform plan diff.”
• “Upgrade the hashicorp/aws provider constraint to >=5.0, <6.0 across all root modules. Run terraform init -upgrade, fix deprecated arguments, and list any resource recreation from the plan.”
• “Create a new module modules/event-bus with variables.tf and outputs.tf containing types, descriptions, and sensible defaults. Wire it into environments/staging with an output for the bus ARN.”
• “Audit current uncommitted Terraform changes for state drift, unused variables, and missing provider version pins. Suggest the smallest reversible sequence to clean them up.”

Each of these keeps the change scoped and ends with a validation or review artifact.

What Gemini CLI does well and where to double-check

Gemini CLI handles many Terraform jobs well:

• Adding or updating tags and labels across a large set of resources consistently.
• Generating variables.tf and outputs.tf with sensible types and descriptions.
• Renaming or moving resources and inserting moved blocks to avoid recreation.
• Upgrading provider version constraints and fixing resulting validation errors.
• Extracting repeated inline blocks into reusable modules.

Watch it closely in these areas:

• State and plan side effects: it may propose terraform state rm, import, or taint too eagerly. Require it to show the exact command and explain the reason before you run anything.
• Plan interpretation: the agent reads plan output but can miss forced replacement caused by count or for_each changes. Always inspect the destroy/create sections yourself.
• Secrets and sensitive values: without a rule, it might put secret values in outputs or locals without sensitive = true. Add that to GEMINI.md.
• Module caller drift: when it changes a module input but misses a caller in another environment, terraform validate may still pass. Ask it to search all callers before finishing.
• Backend and state migration: it may attempt to change backend blocks or reinitialize remote state. Disallow that unless you explicitly request and review the change.

Validate and verify Terraform changes

After each agent turn, run:

• terraform fmt -check -recursive
• terraform validate
• tflint --recursive
• terraform test for modules that have test fixtures

Have the agent include these commands in its own turn rather than assuming it already ran them. After validation, review git diff --stat and the full diff for accidental changes outside the target module. Then run terraform plan -out=/tmp/plan.tfplan in the relevant environment and read the plan together. For module changes, test in at least one root environment and, where possible, add a small terraform test that asserts an output value or a resource count. If the plan shows unexpected destroys, ask the agent to explain each one before you approve.

Parallel Terraform work with AgentVera

For Terraform projects where you want to parallelize changes across modules or environments, AgentVera lets each agent work in its own git worktree so one agent’s edit cannot overwrite another’s. Automatic code review after each turn catches unsafe plan diffs and links findings to file:line, which matters before any state-related change. Checkpoints let you undo a whole turn and replay a questionable terraform state suggestion without leaving the project stuck. Token budgets per agent keep a planning loop from consuming the session when an agent repeatedly retries validation.

Keep control of the loop

Gemini CLI becomes a real Terraform assistant when you give it explicit commands and a hard rule to never apply without review. Keep changes small, validate after every turn, and read the plan diff yourself. For parallel work, separate worktrees plus automated review and checkpoints turn multiple agents from a risk into a useful division of labor across modules and environments.