#Quick Start — Simple

Get from zero to a fleet view in under five minutes. No signup. No server. No Docker.

This is the first-five-minutes path: point Terrantula at an existing Terraform state, then open a local dashboard to see your fleet as a graph. Everything runs on your machine; nothing leaves your workstation.

Want the deeper, end-to-end build? Do this page first, then continue to the Advanced tutorial — a multi-stack greenfield onboarding where a single Action cascade opens the right pull requests in the right order.

#Prerequisites

• Bun 1.x — the CLI's shebang is #!/usr/bin/env bun, so Bun must be on your PATH.
• A Terraform .tfstate file. If you don't have one handy, use the synthetic 50-resource AWS fixture and its config at examples/m1-timing/ in the repo (terraform.tfstate + terrantula.yaml).

#Install

bun install -g @terrantula/cli

Or with npm:

npm install -g @terrantula/cli

Verify:

terrantula --version
terrantula --help

#Write a mapping config

terrantula import terraform needs a YAML mapping config that says how Terraform resource types become Terrantula entity types. The --config flag takes a path to that file (not a named preset).

The fastest way to start is to extends one of the bundled starters and override only what you need:

# terrantula.yaml
extends:
  - terrantula/starters/aws-multi-account

The bundled starters cover the common provider shapes:

You can also write the mappings yourself instead of extending a starter — map each Terraform resource type to an entity type, name template, and optional properties/labels:

# terrantula.yaml
mappings:
  aws_eks_cluster:
    entity_type: K8sCluster
    name: '{{ .name }}'
    properties:
      region: '{{ .arn | split ":" | index 3 }}'
    labels:
      cell: '{{ .tags.cell | default "unassigned" }}'
  aws_vpc:
    entity_type: Vpc
    name: '{{ .id }}'

A complete, runnable example lives at examples/m1-timing/terrantula.yaml.

#Import your Terraform state

Point the CLI at your .tfstate file and your config:

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

Example output:

Add --dry-run (alias --plan) to preview the changes without writing anything:

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

--state also accepts s3://bucket/key and tfc://org/workspace URIs, and can be repeated to merge several state files into one project. See the CLI reference → Common Flows for the S3, Terraform Cloud, and multi-state variants.

#Import an Atmos stack (alternative)

If your fleet is managed with Atmos instead of plain Terraform state files, import the stacks directory directly. import-atmos takes the stacks directory as a positional argument, plus the entity type to map stacks to and a name template built from each stack's vars:

terrantula import-atmos ./stacks \
  --entity-type Tenant \
  --name "{{ vars.customer_id }}"

Add --recursive for nested Atmos layouts, or --plan to preview without writing.

#Open the dashboard

terrantula dashboard

Output:

By default the dashboard binds to a random free port and opens your browser automatically. Pass --port <n> to pin a port, or --no-open to just print the URL (handy over SSH). You'll see the entity browser showing the fleet you just imported.

#What you're seeing

The dashboard runs entirely on your machine. No data leaves your workstation. The local database lives at:

• macOS: ~/Library/Application Support/terrantula/local.db
• Linux: ~/.local/share/terrantula/local.db

The view is a read-only projection of what Terrantula derived from your Terraform state — it never writes back to your infrastructure. The entity browser shows:

• Entity types — the resource kinds Terrantula found in your state (K8sCluster, Vpc, IamRole, etc.)
• Entities — each individual resource
• Relationships — connections between entities (if your config defines them)

#Re-importing after state changes

terrantula import terraform is idempotent. Run it again to pick up changes:

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

Existing entities are updated with new attributes; new resources are added; removed resources are left in place by default. To also remove entities that no longer appear in the state, add --replace (preview it with --dry-run first).

#Explore from the CLI

You don't need the dashboard to query your fleet:

# List all entities of a type
terrantula entities list --entity-type K8sCluster

# Import multiple state files (merged into the same project)
terrantula import terraform \
  --state ./us-east-1.tfstate \
  --state ./eu-west-1.tfstate \
  --config ./terrantula.yaml

#Connect to a remote Terrantula server

The local dashboard is great for exploration. When you're ready to share fleet visibility with your team, point the CLI at a Terrantula server:

terrantula login --base-url https://terrantula.your-domain.com --token terr_xxxxxxxx

Credentials are saved to ~/.config/terrantula/config.json (permissions 600). All subsequent commands run against the remote project instead of the local database. You can also drive the CLI from TERRANTULA_BASE_URL / TERRANTULA_TOKEN env vars in CI.

#Performance

The on-ramp is designed to complete in under five minutes on a cold machine. Measured on a MacBook:

Install time is 30–90 seconds (bun install -g @terrantula/cli) on first run.

#Next steps

• Quick Start — Advanced — graduate from visibility to orchestration: a multi-stack greenfield build where one Action cascade opens PRs and your CI applies.
• Learn Terrantula — the cattle mindset and core concepts behind the graph you just saw.
• CLI reference → Common Flows — every import variant, export, and --replace.