Pull Content

Once your project is set up, you'll regularly synchronise data from your LeadCMS instance. The pull commands download content into your local directories and use incremental sync tokens so only changed items are transferred, making pulls fast and efficient.

All‑in‑one pull

Run the pull command to synchronise everything in one step:

npx leadcms pull

This command performs a full synchronisation for all supported entities: settings, content, media, comments and email templates. On the first run it downloads everything available to your current access level. On subsequent runs the SDK compares your local sync token(s) with the server and only fetches changes.

The downloaded files are stored in directories configured by LEADCMS_CONTENT_DIR, LEADCMS_MEDIA_DIR, LEADCMS_COMMENTS_DIR, LEADCMS_EMAIL_TEMPLATES_DIR and LEADCMS_SETTINGS_DIR. By default these are .leadcms/content, public/media, .leadcms/comments, .leadcms/email-templates and .leadcms/settings.

Selective pulls

Sometimes you only need to refresh certain types of data. The CLI provides specialised commands for these cases:

• pull-content – Downloads only content files (MDX/JSON). Use this when you have updated pages or posts but no new assets.
• pull-media – Downloads only media files to your mediaDir. Useful when editors upload new images or update assets in the CMS.
• pull-comments – Downloads only comments. Use this when you need to update user feedback without touching content or media.
• pull-email-templates – Downloads email templates only (requires API key).
• pull-settings – Downloads tracked CMS settings only (requires API key).

For example, to fetch only new images:

npx leadcms pull-media

These commands also use incremental sync tokens, so they will only download changed items.

Targeting a specific remote

If you have multiple CMS instances configured (see Multi‑Remote Environments), use the --remote / -r flag to target a specific one:

npx leadcms pull -r dev
npx leadcms pull-content -r prod

When omitted, the SDK uses the default remote from your config. The active remote is always shown at the start of the output.

In multi‑remote mode, each remote also keeps its own sync tokens and metadata.json state under .leadcms/remotes/<name>/.

Merge and reset behavior

• Three-way merge (default) – During incremental content pulls, the SDK merges remote changes with local edits where possible.
• Force overwrite – Use --force (or -f) on pull/pull-content to skip merge logic and always overwrite local content files.
• Fresh sync – Use --reset to clear local files for the selected pull scope and fetch a clean copy from the server.

How it works

Under the hood the SDK stores sync tokens per entity (content, media, comments, email templates). When you run a pull command it sends the token and requests items changed since the last sync. The server returns only the delta, and the SDK updates your local store accordingly.

After the files are downloaded, the SDK merges remote metadata into your local files. For content this means updating frontmatter fields like id, createdAt and updatedAt, and rewriting media URLs from /api/media/... to local /media/... paths (see the Media article for details). The reverse transformation happens when you push changes back to LeadCMS.

In multi‑remote mode there is one important rule: local content files always keep the default remote's id, createdAt, and updatedAt. If you pull from a non-default remote, that remote's own IDs and timestamps are stored in .leadcms/remotes/<name>/metadata.json instead of replacing the local default-remote values.

Best practices

• Pull before you push. Always run npx leadcms pull before pushing changes to make sure you have the latest remote updates. This avoids conflicts and ensures your status output is accurate.
• Use selective pulls for efficiency. If only one area has changed, run the scoped command (pull-media, pull-comments, pull-email-templates, or pull-settings) instead of a full pull.
• Automate pulls in CI/CD. In your build pipeline, run pull to fetch the latest content before generating your static site. The incremental sync mechanism makes this operation quick even on cold CI runners.
• Do not edit downloaded media. Media files pulled from LeadCMS should be treated as read‑only. To update images or videos, upload new versions via the CMS Admin UI and pull again.
• Use --reset when local state is stale. If local files or tokens got out of sync, leadcms pull --reset (or a scoped pull-*-command --reset) gives you a clean baseline.

By understanding how pulls work and following these practices, you'll maintain a fast and reliable sync between your local project and LeadCMS.

Next steps

With content synchronized locally, learn about monitoring changes and pushing updates: