#Install

Install the CLI first — it's all you need for the first five minutes. Self-hosting the backend is optional and comes later.

#Install the CLI

bun install -g @terrantula/cli

Or with npm:

npm install -g @terrantula/cli

Bun is required at runtime. The binary's shebang is #!/usr/bin/env bun — if you don't already have it, install Bun from bun.sh first.

#Verify

terrantula --version
terrantula --help

#Try it — no server, no signup

The CLI runs in local mode out of the box. Point it at a Terraform state file and open a dashboard — everything is stored in a local SQLite database, nothing leaves your machine:

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

That's the whole first-five-minutes loop. For a step-by-step walkthrough — including the built-in starter configs that map AWS/Kubernetes resources to entity types — follow the Quick Start.

#Connect to a server (remote mode)

When you're ready for multiple users, orgs, or production use, the CLI talks to a Terrantula API server. Authenticate once:

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

The token goes into your OS keyring — Keychain on macOS, libsecret on Linux, Credential Manager on Windows — and never touches disk. The base URL and your current org/project stay in ~/.config/terrantula/config.json (permissions 600). login prints which of the two took the token, so you always know.

On a machine with no keyring — a container, a CI runner, an SSH session — there is nothing to store into, and login falls back to writing the token into that same 600 config file, saying so on the way. Set TERRANTULA_KEYRING=require to refuse that fallback and fail instead.

A token in the keyring is readable only from a session that can reach the keyring, so scripted and CI callers should skip login entirely and pass credentials per-invocation:

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

The full flag matrix, auth model, and config-file format live in the CLI reference → Install & Authenticate.

#Self-host the backend

The Terrantula backend is Apache 2.0 and self-hostable end-to-end — the cattle wedge runs with zero SaaS dependencies. You bring your own Postgres; Terrantula owns the fleet layer above your Terraform.

At minimum you'll set a DATABASE_URL (Postgres 14+) and an ENCRYPTION_KEY (used to encrypt third-party credentials at rest). The deployment guide walks through the full configuration.

Hosted option. If you'd rather not operate Postgres — or you want managed multi-tenancy, SSO/OIDC, and audit out of the box — there's a hosted offering. It adds routes; it doesn't fork the OSS API. The self-hosted path is never second-class: no cattle-wedge feature is gated behind a paywall.

#Next steps

• What is Terrantula — the plain-language definition.
• Quick Start — import your state and open the dashboard.
• Learn Terrantula — build the mental model before you build a fleet.