#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 your current selections to ~/.config/terrantula/config.json, created with 0600 permissions (owner read/write only). terrantula use <project-id> and the --org selection write the current context; terrantula login writes the base URL.

The API token is not in this file. It goes into the OS keyring — see Credential storage — and the file records only where it went, so the CLI can tell "the keyring is unreachable from this session" apart from "you never logged in".

{
  "baseUrl": "https://api.example.com",
  "currentOrg": "acme",
  "currentProject": "cattle-saas",
  "tokenInKeyring": true
}

#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":"write"}'

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

#Two database roles

Terrantula bounds tenants with PostgreSQL row-level security, and the policies are only a boundary against a role that does not own the tables. Against an owning role neither of the two levers holds — measured on PostgreSQL 16:

• A revoked privilege is not revoked. REVOKE ALL ON t FROM app makes the next read fail with permission denied, and then GRANT SELECT ON t TO app, run by that same role, succeeds. It re-grants itself at will.
• FORCE ROW LEVEL SECURITY is not forced. With FORCE on and no policy naming it, the owner reads zero rows — and ALTER TABLE t NO FORCE ROW LEVEL SECURITY, run by that same role, succeeds. The cage has an inside handle.

Worse, the failure is quiet. A table's owner matches none of the policies, so outside a scope a SELECT returns zero rows, an UPDATE and a DELETE report success having changed nothing, and only an INSERT raises.

So the deployment runs two roles against one database:

The pool role's only power is membership in terrantula_pool, the group role migration 0136 creates, and it must hold it WITH INHERIT FALSE and without ADMIN OPTION. Both matter and both fail silently when wrong: with INHERIT TRUE the role holds the tenant role's privileges ambiently with no scope entered, and a read that should be refused returns zero rows instead; with ADMIN OPTION it can grant itself INHERIT TRUE and get there on its own.

Creating the pool role is one out-of-band act, because a migration that created a login role with a password would ship that credential to every deployment that ran it. Either:

-- (a) make the group role itself login-capable
ALTER ROLE terrantula_pool LOGIN PASSWORD '<secret>';

-- (b) or point your own managed login role at it — what CNPG and
--     Crunchy deployments want, since they own the login role
CREATE ROLE app_pool LOGIN PASSWORD '<secret>';
GRANT terrantula_pool TO app_pool WITH INHERIT FALSE;

SET ROLE is transitive through an INHERIT FALSE membership chain, so (b) works exactly as (a) does while inheriting nothing at either hop.

#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"}'

#Credential storage

The CLI holds two secrets: your API token, and the encryption-at-rest key for local-mode secret values. Both live in the OS keyring — Keychain on macOS, libsecret on Linux, Credential Manager on Windows — under the service name terrantula.

TERRANTULA_KEYRING decides what happens on a machine that has no keyring, which is the normal state for a container, a CI runner, and an SSH session:

Setting TERRANTULA_CONFIG_DIR implies off unless TERRANTULA_KEYRING is set explicitly — a keyring entry does not live inside a directory, so a redirected config dir cannot isolate one.

• Upgrading. A token already sitting in config.json is moved into the keyring the first time the CLI can reach one, and removed from the file only after it has been read back out. You are not logged out, and there is no moment where the only copy is in flight.
• Headless sessions. A keyring-held token cannot be read from a session with no keyring. This is reported as exactly that, not as "not logged in". Pass TERRANTULA_TOKEN (from your secret manager) or --token there — which is what CI should do regardless, rather than running login at all.
• Local-mode encryption key. Stored in the keyring for new installs. An existing ~/.config/terrantula/local-secrets.key is left exactly where it is and never migrated: it is the only thing that decrypts the values already in local.db, so moving it would trade a recoverable inconvenience for unrecoverable loss. When the key is in the keyring and the keyring cannot be reached, terrantula dashboard refuses to start rather than generating a replacement that would silently orphan every stored value.
• 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).
• Triggers, GitHub App, Actions & Webhooks — what credentials each integration needs.
• Install — getting the CLI and self-hosting the server.