#Install & Authenticate

#Prerequisites

The Terrantula CLI is distributed as an npm package and requires Bun (>= 1.0) or Node.js (>= 18) to run.

#Install

bun install -g @terrantula/cli

Or with npm:

npm install -g @terrantula/cli

Verify the installation:

terrantula --version

#Modes

The CLI operates in two modes:

Local mode — no API server required. Data is stored in a local SQLite database. Ideal for the first-five-minutes onboarding flow.

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

Remote mode — connects to a self-hosted Terrantula API server. Required for multi-user, multi-org, and production use.

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

#Authenticate

#Interactive login

Obtain an API token from your Terrantula server (Settings > API Tokens), then:

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

The credentials are saved to ~/.config/terrantula/config.json with permissions 600. Subsequent commands use them automatically.

#Environment variables

For CI, Makefiles, and scripted use:

export TERRANTULA_BASE_URL=https://api.example.com
export TERRANTULA_TOKEN=terr_xxxx

#Per-invocation override

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

Resolution order (highest priority first):

1. --base-url / --token flags
2. TERRANTULA_BASE_URL / TERRANTULA_TOKEN environment variables
3. Saved config file (~/.config/terrantula/config.json)

#Set a default project

After login, set a default project so you don't need --project on every command:

terrantula use <project-id>

This writes currentProject to your config file. Override per-invocation with --project <id> or TERRANTULA_PROJECT_ID.