Skip to main content

Sync Commands

Two commands for keeping templates in sync between Unlayer and your local files:

  • pull — download templates as JSON files.
  • diff — compare a local design against its remote version.

These are the workhorse commands for git-based template workflows.

unlayer pull​

Download templates from a project to local files.

Syntax​

unlayer pull [options]

Description​

Pulls all templates in the active project (or one template with --id) and writes them as JSON files to the output directory. Each file is named {slugified-name}-{id}.json (e.g. welcome-email-42.json).

The output directory defaults to ./templates. Override with --output-dir, or set defaults.outputDir in unlayer.config.json.

Options​

FlagDescription
--id <id>Pull a single template by ID
--output-dir <dir>Output directory (default: ./templates)
--project-id <id>Project ID to scope the pull
--design-onlySave only the design JSON (not the full envelope)
--jsonOutput as JSON

Output Format​

Without --design-only, each file contains the template envelope:

{
  "id": 42,
  "name": "Welcome Email",
  "displayMode": "email",
  "design": {
    /* design JSON */
  },
  "createdAt": "2026-04-01T12:00:00.000Z",
  "updatedAt": "2026-05-05T09:30:00.000Z"
}

With --design-only, files contain just the design JSON — the same shape returned by the visual builder's saveDesign callback. That's the form you typically commit to git when you also want to load it via editor.loadDesign(...).

Examples​

# Pull all templates in the active project
unlayer pull

# Pull a single template
unlayer pull --id 42

# Pull design JSON only (cleaner for git)
unlayer pull --design-only

# Pull from a specific project, custom output dir
unlayer pull --project-id 17 --output-dir ./email-designs

# In CI — JSON output for parsing
unlayer pull --json | jq 'length'   # output is an array of {id, name, path}

unlayer diff <file>​

Compare a local design file against the remote template it came from.

Syntax​

unlayer diff <file> [options]

Description​

Reads a local design JSON file, looks up the matching remote template (auto-detected from the file's metadata, or explicit via --remote), and prints the differences.

The diff is human-readable by default. Pass --json for a structured diff suitable for scripting — typically a CI gate that fails when the local file has drifted from the remote source of truth.

Arguments​

ArgumentDescription
<file>Path to a local design JSON file

Options​

FlagDescription
--remote <id>Remote template ID (auto-detected from file if omitted)
--project-id <id>Project ID to scope the lookup
--jsonOutput diff as structured JSON

Examples​

# Compare a local file against its remote counterpart
unlayer diff ./templates/welcome-email-42.json

# Force a specific remote ID (when the file's metadata is stale)
unlayer diff ./welcome.json --remote 42

# Use in CI to fail when a checked-in template is out of sync
if ! unlayer diff ./templates/welcome.json --json | jq -e '.totalChanges == 0'; then
  echo "Template has drifted from remote"
  exit 1
fi

Common Patterns​

Git-based template workflow​

Treat the templates dir as part of your repo, pull regularly, commit:

unlayer pull --design-only
git add templates
git commit -m "Sync templates from Unlayer"

Keep templates in sync with a CI gate​

Run on every PR to catch drift between local files and the remote source of truth:

unlayer pull --design-only --output-dir ./templates.remote
diff -r ./templates ./templates.remote || exit 1

See Examples for full end-to-end workflows.

See Also​