Reference
The reference is lookup-oriented. You don't read it front-to-back; you jump to the artifact you need — a command, a config key, a catalog kind, a route, an interpolation function — and scan. If you want the teaching tour instead (the cattle mindset, modeling your first fleet), start in Learn.
Every page follows the same man-page template, so you always know where to look:
synopsis / overview → fields / flags table → examples → caveats → related
Each page has a right-rail table of contents, prev/next links, and heavy cross-links. Scan the table, copy the example, check the caveats, follow a related link.
The spines
The reference is split into eight spines plus two pockets. The first three are generated from source, so they never drift from the running code.
| Spine | What it answers | Source |
|---|---|---|
| CLI Reference | Every terrantula command and flag. | generated |
| SDK Reference | The @terrantula/sdk TypeScript surface. | generated |
| API Reference | Every project-scoped HTTP route + its RBAC permission. | generated |
| Catalog Schema Reference | One page per kind — EntityType, Cell, RelationshipType, Action, Secret, Entity, Relationship, and apply. The declarative model you herd your fleet with. | @terrantula/types |
| Configuration Reference | The CLI config file, global flags, environment variables, and project/org/token config. | CLI + server source |
| Interpolation Reference | The {{ ... }} template-function library used in Action triggers and operations. | @terrantula/cli |
| Triggers, GitHub App, Actions & Webhooks | The integration surfaces — TFC trigger, Atmos workflow, Atlantis, PR/webhook, GitHub App, Terrantula Actions. | integration source |
| RBAC & Drift | The role → permission matrix and the drift-event surface. | @terrantula/rbac |
Two pockets sit alongside the spines:
- How-To — task-oriented recipes (deprovision a tenant, cross-source drift, environments, the multi-stack golden path).
- Resources — the glossary and a one-page cheat sheet.
The model behind every page
Two facts shape how the whole reference behaves. Internalize them once and the rest of the reference reads cleanly.
Terrantula never runsterraform apply
Terrantula herds your fleet; it doesn't run it. Actions open pull requests
against your repo (or fire a TFC / Atmos / Atlantis run) — your CI applies. The
UI is a read-only projection of TF-derived state. So when a reference page
says an Action "provisions a tenant," read that as "opens a PR that, once your CI
applies it, provisions a tenant." This is why the Catalog Schema
is declarative and apply reconciles desired state rather than executing it.
Auth: Bearerterr_ tokens, RBAC on every route
Every API and SDK call is authenticated with a project API token — a
terr_-prefixed bearer token sent as Authorization: Bearer terr_…:
The CLI and SDK send this header for you once you've run
terrantula login (or set TERRANTULA_TOKEN). Tokens are
SHA-256 hashed at rest — only the terr_ prefix is stored for display, so a
leaked token can't be recovered from the database.
Each token carries a role (owner, admin, member, viewer) and may be
scoped to a single environment and/or a set of cells. Every project-scoped route
enforces a permission (data:read, catalog:write, secrets:set-value, …)
against that role. The API Reference lists the exact
permission each route requires; the RBAC & Drift spine
documents the full role → permission matrix. How to mint, scope, and revoke
tokens lives in the Configuration Reference.
On a fresh database with no tokens, the API runs in bootstrap mode — it accepts unauthenticated requests so you can mint your first token. Creating any project token closes bootstrap mode and turns on enforcement. See the Configuration Reference.
Where to start
- New to the model? Read Core Concepts and the Catalog YAML Guide first, then come back here to look things up.
- Writing a blueprint? Catalog Schema Reference.
- Wiring up auth, env vars, or tokens? Configuration Reference.
- Connecting a substrate? Triggers, GitHub App, Actions & Webhooks.
- Full end-to-end blueprints? Examples — TFC, Atmos, Atlantis, and bare-TF + GitHub Actions.