Bring existing resources under state without guessing.

The adoption flow

Heckle prefers normal configuration-driven import blocks. If that first plan contains updates, it does not ask you to apply them blindly. Instead it rehearses state-only adoption in disposable local state and checks the resulting normal plan.

normal Terraform/OpenTofu import blocks
          |
          v
       plan
          |
   effective changes?
       /          \
     no            yes
      |             |
      v             v
 imports.tf     state-only rehearsal
 retained       using terraform/tofu import
                     |
                     v
                normal plan
                     |
          +----------+-----------+
          |          |           |
        no-op       known       unknown /
                    provider     effective
                    behaviour    change
          |          |           |
          +----------+           v
               |               FAIL
               v
           adopt.sh

Declarative imports first

When the provider can represent the existing remote object faithfully, Heckle keeps ordinary import blocks in the generated project. You review the plan and decide whether to apply it using your selected CLI.

# OpenTofu (default)
tofu plan -out=import.tfplan

# Terraform, when the project was generated with --tf terraform
terraform plan -out=import.tfplan

State-only fallback

Some provider versions cannot round-trip an existing object cleanly during configuration-driven import. When Heckle detects that, it rehearses CLI imports against temporary state that is never published. If the follow-up plan can be classified, the generated project contains a one-time adopt.sh instead of active import blocks.

The helper uses the Terraform/OpenTofu CLI selected during generation. HECKLE_TF_BIN can override the executable later if needed. OpenTofu remains Heckle's default.

Known provider behaviour

Heckle keeps narrowly scoped, version-specific knowledge about provider behaviour. For example, a provider may canonicalise subordinate settings while their parent feature is disabled. Heckle can identify that pattern when it matches an audited compatibility rule.

adopt.sh

adopt.sh performs only the one-time state adoption and verification steps that Heckle already rehearsed. It does not call apply. If the follow-up plan contains only recognised provider behaviour, it leaves the saved plan for you to review and decide what to do.

./adopt.sh

# Review what remains
tofu show adoption.tfplan      # or: terraform show adoption.tfplan

# Applying is an operator decision, not a Heckle action.
# If you choose to reconcile it:
tofu apply adoption.tfplan

tofu plan

After the resource state and configuration are where you want them, adopt.sh is no longer part of the project and can be removed.

The operator decides

Heckle discovers, generates, rehearses and classifies. It does not know your operational intent and cannot guarantee that a generated plan is complete, safe or appropriate. Always review the actual plan and understand the provider behaviour before applying changes.

If Heckle sees an update outside its audited compatibility rules—or any unexpected create, delete or replacement during adoption—it stops rather than deciding for you.

Existing Heckle state

Use --state-root when generating against an existing Heckle-managed state. Heckle can filter resources already adopted and emit moved blocks when its module address layout changes between versions. It refuses ambiguous cases rather than importing the same remote object at two state addresses.