Status

Before pushing your local changes back to LeadCMS, it's important to understand what will be created, updated or conflicted. The status command provides a dry‑run view of the synchronisation state. It compares your local MDX/JSON files with the remote CMS and categorises the results without making any changes.

Running the command

To view the overall status of your project, run:

npx leadcms status

This reads all local content files and fetches the latest remote content. The 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.

Filtering the status

You can check the status for a single piece of content by specifying an ID or slug. This is useful when you only want to sync a particular file:

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

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

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

Detailed previews

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

npx leadcms status --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.
• 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: