Learn
Reference
Examples
Learn
Reference
Examples

CLI Reference

The Terrantula CLI (terrantula) is the primary interface for the first-five-minutes onboarding flow and ongoing platform operations. It connects to either a self-hosted Terrantula API server or runs in local-only mode via terrantula dashboard.

Installation

# Requires Bun >= 1.0
bun install -g @terrantula/cli

Verify:

terrantula --version

Authentication

Authenticate against a self-hosted Terrantula API server:

terrantula --token terr_xxxx login --base-url https://api.example.com

The token and base URL are saved to ~/.config/terrantula/config.json (permissions: 600). Subsequent commands pick them up automatically.

Override per-invocation:

terrantula --base-url https://api.example.com --token terr_xxxx <command>

Or via environment variables:

export TERRANTULA_BASE_URL=https://api.example.com
export TERRANTULA_TOKEN=terr_xxxx
terrantula <command>

Common flows

First-five-minutes onboarding (local mode)

# Import existing Terraform state into the local dashboard
terrantula import terraform \
  --state terraform.tfstate \
  --config terrantula.yaml

# Open the local dashboard in your browser
terrantula dashboard

Import and inspect (remote API)

terrantula login --base-url https://api.example.com
terrantula import terraform \
  --state s3://my-bucket/terraform.tfstate \
  --config terrantula.yaml \
  --org my-org \
  --project my-project

Atmos workflow

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

Global options

All commands accept these global flags:

FlagDescription
--base-url <url>API base URL (overrides config)
--token <token>API token (overrides config)
--org <id>Org ID (slug) for org/project-scoped commands
--project <id>Project ID for project-scoped commands
--env <name>Environment name (defaults to default)
--jsonOutput raw JSON instead of pretty JSON

Command index

See the generated command reference for a full listing of every command with its flags and examples.

Core commands:

CommandDescription
loginSave API credentials to local config
useSet the default project for project-scoped commands
dashboardOpen the local Terrantula dashboard in your browser
import terraformImport Terraform state into Terrantula as entities and relationships
import-atmosImport Atmos stack manifests into Terrantula as entities
exportDump the project catalog as apply-shaped YAML
project nukeDrop all project-scoped runtime and catalog rows
ON THIS PAGE