Learn
Reference
Examples
Learn
Reference
Examples

Common Flows

First-five-minutes onboarding

The canonical onboarding flow imports an existing Terraform state into the local dashboard. No server or account required.

1. Create a mapping config

# terrantula.yaml
entity_types:
  - name: Server
    tf_resource_types:
      - aws_instance

relationship_types: []

2. Import state

terrantula import terraform \
  --state terraform.tfstate \
  --config terrantula.yaml

Add --dry-run to preview changes without writing:

terrantula import terraform \
  --state terraform.tfstate \
  --config terrantula.yaml \
  --dry-run

3. Open the dashboard

terrantula dashboard

This starts a local server and opens your browser to the graph view.

Import Terraform state from S3

terrantula import terraform \
  --state s3://my-bucket/path/terraform.tfstate \
  --config terrantula.yaml \
  --org my-org \
  --project my-project

Import from Terraform Cloud

terrantula import terraform \
  --state tfc://my-org/my-workspace \
  --config terrantula.yaml \
  --tfc-token "$TFC_TOKEN" \
  --org my-org \
  --project my-project

Or set TF_TOKEN_app_terraform_io in your environment.

Multi-state import

Pass --state multiple times to import from several state files in one operation:

terrantula import terraform \
  --state s3://bucket/prod.tfstate \
  --state s3://bucket/staging.tfstate \
  --config terrantula.yaml

Import Atmos stacks

terrantula import-atmos ./stacks \
  --entity-type Tenant \
  --name "{{.stack}}" \
  --project my-project \
  --org my-org

Use --recursive to walk subdirectories:

terrantula import-atmos ./stacks \
  --entity-type Tenant \
  --name "{{.stack}}" \
  --recursive

Graduate local state to a server

Export local data as YAML and apply it to a remote server:

# Export to a file and inspect
terrantula export --out my-fleet.yaml

# Or pipe directly to a remote server
terrantula export \
  --apply-to https://api.example.com \
  --dest-project <remote-project-id>

Delete stale entities with --replace

After removing resources from Terraform, use --replace to drop the corresponding Terrantula entities:

terrantula import terraform \
  --state terraform.tfstate \
  --config terrantula.yaml \
  --replace

This deletes entities that were previously synced from the same state but are no longer present. Preview with --dry-run first.

ON THIS PAGE