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 is stored in your OS keyring (Keychain / libsecret / Credential Manager) under the service name terrantula; the base URL is saved to ~/.config/terrantula/config.json (permissions: 600). Subsequent commands pick both up automatically.

Where the token actually landed is printed by login, because on a machine with no keyring it falls back to that same 600 config file rather than failing. TERRANTULA_KEYRING controls this:

Value	Behaviour
`auto` (default)	Use the keyring if one is available; otherwise write to the `600` file and say so.
`require`	Keyring or nothing. Never writes a credential to disk.
`off`	Never touch the keyring; use the `600` file.

Setting TERRANTULA_CONFIG_DIR implies off unless TERRANTULA_KEYRING is set explicitly — a keyring entry does not live inside the directory you redirected the CLI at.

A keyring-held token cannot be read from a session with no keyring (SSH, containers, CI). That is not a corrupted login; pass TERRANTULA_TOKEN or --token there instead.

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:

Flag	Description
`--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
`--json`	Output 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:

Command	Description
`login`	Save API credentials — token to the OS keyring, base URL to the config file
`use`	Set the default project for project-scoped commands
`dashboard`	Open the local Terrantula dashboard in your browser
`import terraform`	Import Terraform state into Terrantula as entities and relationships
`import-atmos`	Import Atmos stack manifests into Terrantula as entities
`export`	Dump the project catalog as apply-shaped YAML
`project nuke`	Drop all project-scoped runtime and catalog rows

ON THIS PAGE

#CLI Reference

#Installation

#Authentication

#Common flows

#First-five-minutes onboarding (local mode)

#Import and inspect (remote API)

#Atmos workflow

#Global options

#Command index