#Configuration Reference

How you configure Terrantula depends on which side you're on:

• Operating the fleet (CLI / SDK / CI) — you point at an API base URL and a token. That comes from the CLI config file, the global flags, or environment variables.
• Running the server (self-host or hosted) — you set the server environment variables: database, the encryption key, the auth secret, and the deployment mode.

Resolution order is consistent across the CLI: flag → environment variable → config file → built-in default. A --flag always wins; the config file is the persistent fallback you set once with terrantula login and terrantula use.

# All three configure the same thing; the flag wins this invocation.
terrantula --base-url https://api.example.com --token terr_xxx entities list
TERRANTULA_BASE_URL=https://api.example.com TERRANTULA_TOKEN=terr_xxx terrantula entities list
terrantula login --base-url https://api.example.com --token terr_xxx   # persists to the config file

#CLI config file

The CLI persists credentials and current selections to ~/.config/terrantula/config.json. terrantula login writes the credentials; terrantula use <project-id> and the --org / --env selections write the current context. The file is created with 0600 permissions (owner read/write only).

{
  "baseUrl": "https://api.example.com",
  "token": "terr_xxxxxxxxxxxxxxxx",
  "currentOrg": "acme",
  "currentProject": "cattle-saas",
  "currentEnv": "default"
}

#Global flags

These flags are accepted by every command and override the config file for that invocation.

#CLI environment variables

Read by the CLI and SDK. Each maps to a flag or config key in the resolution chain above.

# Drive the CLI from CI with no login step:
export TERRANTULA_BASE_URL=https://api.example.com
export TERRANTULA_TOKEN=terr_xxxxxxxxxxxxxxxx
export TERRANTULA_ORG_ID=acme
export TERRANTULA_PROJECT_ID=cattle-saas
terrantula apply --file blueprint.yaml --json

#Project API tokens

Tokens are how the CLI, SDK, and any integration authenticate. They are terr_-prefixed bearer tokens sent as Authorization: Bearer terr_…. Tokens are org-owned API keys scoped to one project; mint and revoke them under /orgs/:orgId/projects/:projectId/tokens (requires the tokens:manage permission — admin/owner).

# The raw token value is returned EXACTLY ONCE, at creation.
curl -X POST https://api.example.com/orgs/acme/projects/cattle-saas/tokens \
  -H "Authorization: Bearer terr_existing" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","role":"member","envName":"prod"}'

#Environments

Every project ships a default environment. Environments isolate data and secret values: the same secret name (e.g. tfc-api-token) can hold a different value per env, and a value set in one env is decrypted only for runs in that env. Select the active env with --env, TERRANTULA_ENV_NAME, or the currentEnv config key. Tokens can be pinned to one env via envName.

See the Secret catalog kind for how secrets reference env-scoped values, and the How-To pocket for the environments recipe.

#Server environment variables

Set these on the API server (and worker), not on the CLI. They are required to self-host. Never commit their values; mount them as secrets.

#Required

#Optional / deployment

#GitHub App (cloud deployments)

Required only when TERRANTULA_DEPLOYMENT=cloud and you connect the GitHub App. See Triggers, GitHub App, Actions & Webhooks.

#Bootstrap mode

On a fresh database with no tokens, the API runs in bootstrap mode: all requests are accepted without authentication so you can mint your first token. Creating any project token (POST /orgs/:orgId/projects/:projectId/tokens) closes bootstrap mode and turns on token enforcement for every subsequent request.

# Fresh DB: mint the first token while bootstrap mode is open.
curl -X POST https://api.example.com/orgs/terrantula/projects/terrantula/tokens \
  -H "Content-Type: application/json" \
  -d '{"name":"bootstrap","role":"owner"}'

#Secrets and storage

• CLI token at rest. ~/.config/terrantula/config.json stores the token in plaintext at 0600. On a shared machine, prefer TERRANTULA_TOKEN (from your secret manager) over login.
• Server credentials at rest. Third-party credentials (OIDC client secrets, catalog Secrets) are encrypted with ENCRYPTION_KEY. terr_ tokens are SHA-256 hashed — only the prefix is stored.
• In logs. Terrantula logs only token prefixes (terr_xxxxxxxx…), never full values.

#Related

• CLI Reference — login, use, and every command's flags.
• API Reference — the routes each token authenticates against.
• RBAC & Drift — the role → permission matrix.
• Secret — declaring catalog secrets (values set out-of-band, env-scoped).
• Triggers, GitHub App, Actions & Webhooks — what credentials each integration needs.
• Install — getting the CLI and self-hosting the server.