#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 token is saved to your OS keyring; the base URL goes to ~/.config/terrantula/config.json with permissions 600. Subsequent commands use both automatically, and login prints which store took the token. On a machine with no keyring it falls back to that same 600 file and says so — see Credential storage.

#Environment variables

For CI, Makefiles, and scripted use. Prefer these over login for anything non-interactive: a keyring-held token is not readable from a container, a CI runner, or an SSH session, and these are.

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 credential — the OS keyring, or ~/.config/terrantula/config.json where there is no keyring

#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.