Configuration as Code

treadle, the Loom Loyalty CLI, manages your organization's configuration from one file, loom-loyalty-config.yaml. Keep the file in git, review changes to it like code, and let treadle show you what will change before anything does.

treadle pull    →  edit the file  →  treadle plan  →  treadle apply  →  approve in production

Before you start

• Early access. Configuration as code is in early access. Ask your Loom Loyalty contact to turn it on for your organization and to give you the CLI package. treadle needs Node.js 18.2 or later.

• Credentials. Sign in through the browser (run any command without a token), or use an API key with the org-admin role for your Development environment. Pass the key in an environment variable, never on the command line:

  export LOOM_API_TOKEN=llk_...   # read it from your password manager

Commands

Command	What it does	Writes
treadle pull --code <code>	Writes your live configuration to the file	the file only
treadle plan	Shows what apply would do to each record	nothing
treadle apply	Shows the plan, asks you to confirm, then applies it to Development	Development
treadle apply --env <code>	Applies, then opens approval requests into that environment	Development, plus the requests
treadle status	Lists the approval requests still waiting for the file's records	nothing

Every command takes -f <file> (default loom-loyalty-config.yaml).

plan exits 0 when nothing would change, 2 when something would, and 1 on an error, a conflict or a blocked record, so a CI job can gate on it.

What the file holds

schema: loom-loyalty-config.v1
code: acme # one file per code
name: Acme loyalty
dataModels: [...]
eventTypes: [...]
programs: [...]
programCurrencies: [...]
tiers: [...]
badges: [...]
targets: [...]
eventRules: [...]
customerAudiences: [...]
offers: [...]
flows: [...]
hub: { theme: ..., uiSettings: ..., entityOverrides: ..., featureFlags: ... }

• Records are matched by code, and references between them use codes (programCodes, tierCode, targetCode, badgeCode), never ids.
• A key the file leaves out keeps its live value. Removing a record from the file never deletes it.
• Your organization, environments, roles, API keys and the Hub's subdomain, domain and custom components stay outside the file.

What a plan shows

Result	Meaning
CREATE	The record doesn't exist yet and will be created
ADOPT	The record exists and the file takes it over
UPDATE	The record exists and differs from the file
UNCHANGED	The record already matches the file
CONFLICT	The file can't take this record; nothing is applied until it's fixed
BLOCKED	The record is live in production and you lack permission to change it

Bring your configuration under a file

1. treadle pull --code <code> writes what is live today. Read every warning it prints.
2. Remove anything you don't want to manage from the file, and commit it.
3. treadle plan shows every record as ADOPT or UNCHANGED.
4. treadle apply, then treadle plan exits 0.

Change your configuration

1. Edit the file on a branch and run treadle plan. Paste the plan into your pull request.
2. Once it's approved, run treadle apply to change Development.
3. Run treadle apply --env <production environment code>. This opens one approval request per record type. Nothing changes in production until each request is approved in the dashboard.
4. treadle status lists what is still waiting. When it prints "No workflow requests are waiting", production has everything the file declares.

Catch drift

Someone can still change a record in the dashboard or Hub. treadle plan then shows an UPDATE back to the file and exits 2. To discard the edit, run treadle apply. To keep it, run treadle pull -f live.yaml, copy the change into your file, and plan until it exits 0. Running treadle plan on a schedule in CI finds drift before an apply overwrites it.