Pull, push & upgrading

Deploy a site once. After that, npm run pull brings the live site onto your computer, npm run push puts your changes live, and npm run upgrade updates the CMS. It works the same on every host.

Two kinds of files

• Your site: the theme (how it looks) and the content (pages, menus, redirects, site settings and images). Editors change content in the admin, and you change the theme on your computer.
• The CMS: the program that runs your site, in vhost/. You never edit it; npm run upgrade updates it.

Your site’s files live on the host’s permanent disk, so they survive restarts and upgrades. The CMS comes from your deploy.

Getting the live site onto your computer: npm run pull

npm run pull

Live site address: my-site.example
Access token for https://my-site.example (hidden):

What do you want to pull?
  [x] Content  (pages, menus, redirects, images, site settings)
  [x] Theme    (templates, styles, scripts)

• What it does: makes your local copy match the live site for whatever you chose, downloading any images you don’t have. Local files the live site doesn’t have are removed, and it lists them.
• What it never does: commit anything. Check the result with git diff.
• When it refuses: if the parts it would overwrite have uncommitted changes. Commit them first.

The token is the site’s access token, the same one the admin uses. It’s never shown as you type it, and never saved. For scripts, pass the address as npm run pull -- my-site.example, set CMS_TOKEN, and choose with --content / --theme.

Putting your changes live: npm run push

npm run push

What do you want to push?
  [x] Content  (3 pages changed)
  [x] Theme    (2 files changed)

This will change the LIVE site at https://my-site.example:

  update     content/pages/about.json
  new page   content/pages/tasting-notes.json
  update     theme/sections/hero.liquid
  upload     media/still-3f0e6b0a4d2c.jpg

WARNING: this overwrites the live website, straight away.

Type my-site.example to push, or anything else to cancel:

Push only sends what you changed since your last pull, and protects what other people changed on the live site:

• If someone changed the same file on the live site since your last pull, nothing is pushed. Push lists the file instead of overwriting their work. To keep both, commit your work, pull, reapply your change, and push again.
• It only deletes what you deleted. A page an editor created on the live site is never removed.
• All or nothing. Content goes in one batch and one commit, or not at all; the theme likewise, switching over with no restart.
• Everything can be rolled back. Each push is saved in the live site’s history, like an edit in the admin.

Push goes back to the site you last pulled from or pushed to, remembering its address in vhost/data/ (never committed). Run npm run push -- --dry-run to see what would change without changing anything.

Upgrading the CMS

1. Upgrade on your computer: npm run upgrade (or npm run upgrade -- 0.9.1 for a particular version). It shows what’s new, asks before changing anything, installs it, refreshes the CMS’s own files in vhost/ (keeping any scripts of your own), updates your content to the new format if it changed, and checks your site. Nothing is committed; review it with git diff.
2. Test it: npm run dev, and look at your site.
3. Put it live: npm run push. Because your CMS is now newer than the live site’s, push offers one more choice:
   JSON

     [x] CMS upgrade  (live site: 0.9.0, here: 0.9.1)

   Push upgrades the live site first, waits for it to come back on the new version, then sends anything else you chose. The site is unavailable for a moment while the host restarts it.

Push knows how to redeploy on Railway and Fly.io. For any other host, tell it the command once, in vhost/deploy.json:

{ "command": "git push" }

That suits Render, Coolify, and any host that deploys when you push to GitHub. With no command set, push pauses and asks you to deploy the way you usually do, then carries on once you press Enter. If the live site doesn’t come back on the new version within ten minutes, push stops without sending anything else and says what it saw.

Working on a site locally