Status

Before pushing local changes back to LeadCMS, it's important to understand what will be created, updated or conflicted. The status commands provide a dry‑run view of synchronisation state without making changes.

Running the command

To view the overall status of your project, run:

npx leadcms status

This command provides a unified status across content, media, email templates and settings. For content, output is grouped into sections similar to git status:

• New file – Local files that do not exist in LeadCMS. These will be created when you push.
• Modified – Local files with changes compared to the remote version. These will be updated on push.
• Renamed – Local files whose slug has changed since the last push. The remote content will be renamed accordingly.
• Type change – Local files whose type frontmatter value has changed. The remote content will be updated to the new type.
• Conflict – Remote content that has been updated after your last pull (e.g. someone edited the same content in the CMS). Conflicts must be resolved before pushing unless you use --force.

If the command outputs No changes detected, your local repository is in sync with LeadCMS.

Scoped status commands

Use scoped commands when you want status for one entity type:

• npx leadcms status-content
• npx leadcms status-media
• npx leadcms status-email-templates
• npx leadcms status-settings

Targeting a specific remote

In multi‑remote setups, status commands accept --remote / -r:

npx leadcms status -r prod
npx leadcms status-content -r dev
npx leadcms status-email-templates -r prod

Status compares your local files against the selected remote using that remote's own sync state and metadata baseline.

Filtering the status

You can check status for a single content item by specifying an ID or slug on status-content:

# Check status for a content item by slug
npx leadcms status-content --slug about-us

# Check status for a content item by ID
npx leadcms status-content --id 42

When filtering, the command shows a detailed diff preview for the targeted file.

Detailed previews

You can display a diff of content changes by adding the --preview flag to status-content:

npx leadcms status-content --preview

This shows a line‑by‑line comparison of your local file against the remote version for each modified, renamed or type‑changed item. Use this to review changes before deciding to push.

Best practices

• Run status before every push. Checking status ensures you understand what will happen when you push and helps you avoid unexpected changes.
• Pull first. Always run npx leadcms pull before status to ensure your local repository is up to date. This reduces the chance of conflicts.
• Use scoped status for clarity. For detailed content diffs, prefer status-content --preview.
• Resolve conflicts locally. When conflicts are reported, merge the changes manually in your editor. Only use --force if you are certain you want to override remote updates.
• Use filters for targeted updates. If you are working on a single page or post, filter by slug or ID to see exactly what will change.

The status command is a lightweight way to audit your content changes and maintain a clean, conflict‑free workflow.

Next steps

With status checks mastered, learn about pushing changes and content modeling: