Referência prática da CLI do Terraform, organizada pelo fluxo de trabalho real — não pela ordem alfabética do help. Baseada na série 1.14 do Terraform (a mesma usada nos tutoriais KVM/Libvirt, cujos exemplos ilustram vários comandos abaixo).
A CLI se divide em três blocos: comandos do fluxo principal (que você usa todo dia), comandos de inspeção e gerenciamento (state, workspaces, módulos) e comandos avançados (import, test, força bruta em locks). O help completo de qualquer comando é
terraform <comando> -help.
Os cinco comandos que resolvem 95% do dia a dia, na ordem em que são usados:
terraform init # prepara o diretório
terraform validate # valida a sintaxe/lógica
terraform plan # mostra o que vai mudar
terraform apply # aplica as mudanças
terraform destroy # remove tudo
init — preparar o diretórioBaixa providers e módulos, inicializa o backend de state. É sempre o primeiro comando — e deve ser repetido quando você adiciona um provider, um módulo ou muda o backend.
terraform init # inicialização padrão
terraform init -upgrade # atualiza providers/módulos dentro das restrições de versão
terraform init -backend=false # só baixa dependências, ignora backend (útil para validate em CI)
O init gera o .terraform.lock.hcl — arquivo de lock de versões de provider que deve ser commitado no Git (garante que todo mundo usa exatamente as mesmas versões).
validate — conferir antes de planejarCheca sintaxe e consistência interna (atributos válidos, referências existentes) sem tocar em nenhuma infraestrutura e sem precisar de credenciais. Rápido o suficiente para rodar a cada edição:
terraform validate # "Success! The configuration is valid."
plan — o diffs da infraestruturaCompara configuração + state com a realidade e mostra o que seria criado, alterado ou destruído — sem aplicar nada.
terraform plan # plano interativo
terraform plan -out=plano.tfplan # salva o plano em arquivo (ver seção 3)
terraform plan -destroy # pré-visualiza uma destruição
terraform plan -target=module.compute # restringe a um alvo (ver seção 5)
Leitura do plano:
+cria,~altera in-place,-destrói,-/+destrói e recria. Sempre confira o resumo final —Plan: 17 to add, 0 to change, 0 to destroy— antes de qualquerapply.
apply — criar ou atualizarExecuta o plano:
terraform apply # mostra o plano e pede confirmação
terraform apply plano.tfplan # aplica um plano salvo (sem nova confirmação)
terraform apply -auto-approve # sem confirmação — evite fora de laboratório/CI
terraform apply -var="ssh_public_key=$(cat ~/.ssh/kvm.pub)"
-auto-approvepula a única revisão humana do processo. Em laboratório e pipelines é aceitável; em produção, prefiraplan -out+ revisão +apply plano.tfplan.
destroy — remover tudoDestrói todos os recursos do state, na ordem inversa das dependências:
terraform destroy
terraform destroy -target=module.network # só um alvo
Os comandos do fluxo principal aceitam variáveis por três vias (ordem de precedência crescente: .tfvars → *.auto.tfvars → -var/-var-file):
terraform plan -var="regiao=gru" # variável única
terraform plan -var-file=prd.tfvars # arquivo extra de variáveis
TF_VAR_ssh_public_key="$(cat ~/.ssh/kvm.pub)" terraform apply # via ambiente (segredos)
Nos nossos tutoriais usamos TF_VAR_ssh_public_key justamente para a chave SSH nunca tocar o disco nem o Git.
show — ler state ou plano salvoterraform show # state atual (legível)
terraform show -json # state em JSON (para jq/scripts)
terraform show plano.tfplan # o que um plano salvo vai fazer
output — valores de saídaterraform output # todos os outputs
terraform output vm_ips # um output específico
terraform output -json # para automação
state — cirurgia no stateO state é o "banco de dados" do Terraform; estes subcomandos mexem nele diretamente:
terraform state list # todos os recursos
terraform state show module.compute.libvirt_domain.domain["web-01"]
terraform state mv <origem> <destino> # renomeia/move sem recriar
terraform state rm <endereco> # esquece um recurso (NÃO destrói no provider!)
terraform state pull > backup.tfstate # backup do state remoto
state rmnão destrói o recurso real — ele só sai do controle do Terraform (fica "órfão"). Útil para adotar o caminho inverso doimport, mas use com cuidado.
providers, modules, version — contexto do projetoterraform providers # árvore de providers exigidos pela configuração
terraform modules # árvore de módulos declarados
terraform version # versão da CLI e dos providers instalados
O terraform providers é o diagnóstico rápido para o problema clássico de "sintaxe de exemplo antigo da internet": ele mostra exatamente qual versão do provider dmacvicar/libvirt está travada no lock — 0.9 tem sintaxe incompatível com 0.8, como alertamos no índice da série.
graph — o grafo de dependênciasGera um grafo no formato Graphviz (DOT) dos recursos e suas dependências:
terraform graph | dot -Tsvg > grafo.svg # precisa do pacote graphviz
Em projetos modulares como a parte 4 da série, o grafo mostra visualmente a cadeia network → storage/cloudinit → compute.
terraform workspace list # workspaces existentes
terraform workspace new staging # cria e muda para ele
terraform workspace select prd # muda de workspace
terraform workspace show # workspace atual
Cada workspace tem state próprio. É a alternativa "oficial" a pastas por ambiente — mas, para diferenças estruturais entre ambientes (como hml/prd com variáveis distintas), preferimos a abordagem de diretórios + módulos mostrada nos tutoriais: mais explícita e sem dependência de lembrar qual workspace está ativo.
import — adotar infraestrutura existenteAssocia um recurso criado fora do Terraform (à mão, por outra ferramenta) a um endereço do state:
terraform import libvirt_network.nat_net 8f3a2c1e-... # endereço no state + ID real
Após o import, ajuste o .tf até terraform plan retornar "No changes" — só então a adoção está completa. (Desde a 1.5 também existe o bloco import {} declarativo no próprio HCL.)
taint / untaint — forçar recriaçãoMarca um recurso como "estragado": o próximo plano vai destruí-lo e recriá-lo, mesmo sem mudança na configuração:
terraform taint module.compute.libvirt_domain.domain["web-01"]
terraform untaint module.compute.libvirt_domain.domain["web-01"] # desfaz a marca
Caso de uso clássico: VM cujo cloud-init falhou e você quer recriar do zero sem tocar nas demais. (Na prática moderna, terraform apply -replace=<endereco> faz o mesmo sem mexer no state permanentemente.)
force-unlock — destravar o stateQuando um apply morre no meio (queda de rede, Ctrl+C), o state remoto pode ficar travado:
terraform force-unlock <LOCK_ID> # o ID aparece na mensagem de erro do lock
Confirme que nenhum Terraform está rodando antes de destravar. Forçar unlock com outro processo ativo é receita para state corrompido. Em backend local (nossos tutoriais), locks presos são raros — mas em backend S3/remote é o comando de resgate padrão.
fmt — formatação canônicaterraform fmt # formata o diretório atual
terraform fmt -recursive # inclui subdiretórios (módulos!)
Roda antes de cada commit — diffs limpos e estilo consistente em toda a série.
console — testar expressõesREPL interativo para experimentar funções HCL contra as variáveis do projeto:
terraform console
> { for srv, s in var.servers : srv => s.vcpus }
> flatten([for srv, s in var.servers : [for d in s.extra_disks : "${srv}-${d.name}"]])
Perfeito para depurar expressões como o padrão flatten() dos discos extras antes de rodar um plan.
test — testes de módulosExecuta testes de integração de módulos declarados em arquivos *.tftest.hcl:
terraform test
Permite validar que um módulo cria os recursos esperados e que os outputs têm os valores corretos — o próximo degrau de maturidade depois de validate.
refresh — só ressincronizar o stateterraform refresh
Atualiza o state com a realidade sem aplicar mudanças. Obsoleto na prática: plan/apply já fazem refresh por padrão — o comando existe por compatibilidade.
login / logout — HCP Terraformterraform login # autentica no HCP Terraform / Terraform Enterprise
terraform logout
Só relevante para quem usa o backend remoto da HashiCorp — sem efeito em projetos com backend local ou S3.
metadata, modules, stacks, query — novidades da série 1.x| Comando | Para que serve |
|---|---|
metadata functions |
Lista todas as funções disponíveis na versão instalada |
stacks |
Operações de Stacks no HCP Terraform (configurações multi-componente) |
query |
Busca recursos em infraestrutura remota (list resources) |
-chdirDuas opções funcionam com qualquer subcomando:
terraform -chdir=environments/prd plan # executa como se estivesse na pasta prd
terraform -chdir=modules/compute fmt # formata um módulo sem cd
terraform -version # atalho para terraform version
O -chdir é especialmente útil em scripts e pipelines — com a estrutura de ambientes da parte 4, dá para aplicar hml e prd a partir da raiz do repositório.
# Dia a dia
terraform init && terraform validate
terraform fmt -recursive
terraform plan
terraform apply
# Inspeção
terraform output
terraform state list
terraform show
# Manutenção
terraform workspace list
terraform state mv <de> <para>
terraform apply -replace=<endereco>
# Emergência
terraform force-unlock <LOCK_ID>
terraform state rm <endereco> # só o state — o recurso real continua existindo!
-chdir e opções globais.tftest.hcl