Local to production
Build it locally, then push the structure up
Sync deploys schemas, templates and collection settings between a local Total CMS install and a production one. Your editors' content stays exactly where they left it.
Sync is a mirror with a direction. It moves the parts of a site you develop — custom schemas, templates, and every collection's settings — between a local install and a production server, so you can build and test on your laptop and deploy structural changes without touching live content or media.
Setup is once per pair of sites. On production, create an API key under Utilities → API Keys with GET and POST permissions and the Sync Manager endpoint ticked. Locally, enter that server's API URL and the key under Settings → Sync. From then on the tcms push and tcms pull commands and the Utilities → Sync Manager page all read the same settings.
A bare tcms push is a full mirror: every custom schema, every template, every object in the five feature-flagged collections, and every collection's settings. Name a filter and everything you did not mention is excluded — tcms push --schemas=blog pushes the blog schema and nothing else. Objects from your own collections never travel unless you name them explicitly with push --objects, which seeds rather than mirrors: an object the target already has by that id is left untouched.
Run --dry-run first, every time. It compares both sides and marks each item: ~ for a difference (with a hint from the updated timestamps about which side holds the newer edit), + for something new on the remote, = for identical, and · for items that exist only on the remote and are left alone. It warns explicitly when a sync would land an older copy on top of a newer one.
The everyday case: you add a price property to a products schema, rework the product template, and dry-run against production. Two items differ, so you push those two. The products your client edited last week are untouched, because objects in a custom collection are not part of a push at all.
Some things never travel, by design:
- Media files and images, and any image, gallery, file or depot field on any object
- System settings, API keys, and reserved (built-in) schemas
- Objects in your own collections, unless named with
--objects
What you get
Dry run before you deploy
Both push and pull support --dry-run, which compares the two sides and shows what would actually change rather than what would travel. It warns when a sync would overwrite the newer copy.
Structure moves, content stays
Schemas, templates and collection settings mirror. Media, system settings, API keys and reserved schemas never sync at all.
Seeding, not clobbering
push --objects=blog lands starter content on a fresh production site but skips any id the target already has. Overwriting requires both --overwrite and --force.
Automatic backups on the receiving side
Before an overwrite replaces a schema, object or collection, the receiving instance snapshots the current version under tcms-data/.system/backups/. The ten most recent are kept per item.
Dashboard or command line
Utilities → Sync Manager shows the same comparison as the CLI dry run, with a Select Changed button that ticks exactly the items that differ or are missing on the remote.
In practice
One snippet
# Preview what a push would change — never sends anything
tcms push --dry-run
# Push one schema and one template; nothing else travels
tcms push --schemas=products --templates=product-detail
# Seed starter posts onto a fresh production site (existing ids are skipped)
tcms push --objects=blog
# Pull a schema back down from production
tcms pull --schemas=productsFilters are exclusive: the moment you name one, every category you did not mention is left out of the payload.
FAQ
Common questions
Does a push overwrite my client's content?
No. Objects in your own collections are not part of a push unless you name them with --objects, and that mode skips any object the target already has. The five site-machinery collections — pages, data views, mailer, MCP prompts and automations — do mirror, so push with those in mind if they are edited in production.
What if production has the newer version?
The dry run tells you. Items that differ are compared by content hash, and the updated timestamps say which side holds the later edit; the preview warns explicitly before a sync lands an older copy on top of a newer one. Pull it down first, then push.
Can I use git instead?
Yes. Schemas live in tcms-data/.schemas/ and templates in tcms-data/builder/, both plain text that diffs cleanly, so a git-based pipeline works well — run tcms cache:clear on production after deploying. Sync exists for the case where you have no file access to the server, and the two happily coexist.
Is anything recoverable if a sync goes wrong?
The receiving instance snapshots each schema, object and collection it is about to overwrite into tcms-data/.system/backups/, keeping the ten most recent per item. Restoring is a manual copy back over the live file followed by a cache clear — it is a safety net, not a substitute for real backups.
Related features
- JumpStart export/import Export schemas, collections, objects and templates to one JSON file and import it anywhere. Faker-backed factory blocks generate sample content on the way in.
- Import from anywhere Import from CSV, JSON, RSS feeds, WordPress, Alloy or Total CMS 1. Images and files come in by path, and large jobs run in the background.
- Custom schemas Define your own object shapes as JSON files. The admin form, the list view, validation and the query surface are all generated from the schema.
Want the details? Read the Push & pull sync documentation →
Or keep browsing: every Total CMS feature →
Start Your Free 45-Day Trial