braze-sync
GitOps CLI for managing Braze configuration as code.
braze-sync lets you keep Braze workspace state in a Git repository and synchronize it to Braze with the same workflow you'd use for terraform plan / kubectl diff — including dry-run previews, drift detection in CI, and an --allow-destructive gate that has to be crossed explicitly before anything is dropped.
Status: 5 resources + init + Braze-managed placeholder resolution
braze-sync manages Braze configuration as code. The five managed resource kinds are:
- Catalog Schema (field definitions, types, constraints)
- Content Block (reusable Liquid fragments)
- Email Template (HTML/Liquid templates)
- Custom Attribute registry (definition-level; deprecation toggle)
- Tag registry (workspace tags referenced by other resources;
derived from local frontmatter because Braze exposes no tag API)
Out of scope: runtime data like catalog items, user attribute values, events, and campaigns. Those have their own systems of record; use the Braze REST API or data pipelines directly. See docs/scope-boundaries.md.
| Command | What it does | |:---|:---| | braze-sync init | Scaffolds a new workspace (config, directories, .gitignore) | | braze-sync export | Pulls current Braze state into local files | | braze-sync diff | Shows drift between local files and Braze | | braze-sync apply | Applies local intent to Braze (dry-run by default) | | braze-sync validate | Local-only structural and naming checks (no API call) | | braze-sync templatize | One-shot migration: rewrite raw lid / cbid to placeholders (see docs/per-env-values.md) |
Content Block specifics
Content Blocks live as contentblocks/<name.liquid files: YAML frontmatter (name, description, tags, state) followed by the Liquid body. braze-sync apply can create new blocks and update existing ones, but the Braze API has no DELETE for content blocks, so blocks that exist in Braze but not in Git become orphans — diff and apply report them but never mutate them. Retire an orphan by archiving it in the Braze dashboard, or add it to excludepatterns to keep it. The data is never silently dropped. The same report-only policy applies to email template orphans — see docs/orphan-tracking.md.
When a block body references another block via the Liquid include syntax {{contentblocks.${other} | id: '...'}}, apply topologically sorts so the referenced block is created before the referrer. Without this, Braze rejects forward references at create time with an opaque HTTP 500. Cycles abort the apply with a named-blocks error before any write fires. Set resources.contentblock.applyorder: alphabetical to restore pre-v0.11 ordering.
Install
Pre-built binaries (recommended):
Download from GitHub Releases for Linux (x8664, aarch64), macOS (x8664, Apple Silicon), and Windows (x8664).
Homebrew (macOS / Linux):
brew install uny/tap/braze-synccargo install (requires Rust toolchain):