Settings Sync

LeadCMS includes dedicated commands for syncing tracked settings between your local repository and your CMS instance.

By default, settings are stored in .leadcms/settings unless overridden with LEADCMS_SETTINGS_DIR.

Commands overview

• pull-settings – Pull tracked settings from LeadCMS.
• status-settings – Compare local and remote tracked settings.
• push-settings – Push local tracked settings to LeadCMS.

Pull settings

pnpm exec leadcms pull-settings

Options:

• --name <key> – Pull only one setting key.
• --reset – Clear local settings directory before pull.

If no API key is configured, settings sync is skipped.

Targeting a specific remote

Settings commands support --remote / -r in multi‑remote setups:

npx leadcms pull-settings -r dev
npx leadcms status-settings -r prod
npx leadcms push-settings -r dev

Check settings status

pnpm exec leadcms status-settings

Option:

• --name <key> – Show status for one setting key.

Status output groups settings by states like in-sync, modified, local-only, and remote-only.

Push settings

pnpm exec leadcms push-settings

Options:

• --name <key> – Push one setting key.
• --dry-run – Preview what would be pushed.
• --force – Push all tracked settings, including unchanged ones.

Recommended workflow

1. Pull current settings: leadcms pull-settings
2. Edit local setting files.
3. Review diff: leadcms status-settings
4. Validate safely: leadcms push-settings --dry-run
5. Push: leadcms push-settings

Best practices

• Keep settings in version control for auditability.
• Use --name while iterating on one setting key.
• Run status-settings before every push.
• Use --force only when you intentionally want to re-apply unchanged values.

Next steps