Push and Pull

Sync between local files and a hosted Primo server.

primo push and primo pull move content and code between your local workspace and an already-deployed Primo server. Use them to keep production in sync with Git, or to grab a copy of a remote site for local development.

Authenticate First

Before pushing or pulling against a hosted server, log in:

primo login https://cms.example.com
primo login https://cms.example.com -e [e-mail]

The CLI stores credentials per server and reuses them on subsequent commands.

primo pull — Hosted → Local

Pull an entire server (every site plus the shared library) into local files:

primo pull https://cms.example.com
primo pull https://cms.example.com ./my-workspace

Arguments and options:

• [dir] — Output directory (defaults to ./<server-hostname>)
• -s, --server <url> — Server URL (alternative to the positional argument)
• -t, --token <token> — Auth token (overrides stored credentials)

The result is a complete workspace ready for primo dev. Image files in uploads/ are pulled as real binaries — the directory is self-contained.

Each pull also records which server revision your files came from (in .primo/sync-state.json). The next push uses it to check that nobody has changed the site in the meantime. See Push safety.

primo push — Local → Hosted

Push local changes to a hosted server:

primo push https://cms.example.com
primo push https://cms.example.com --site abc123
primo push --only my-site         # Push just one site folder
primo push --preview              # Preview changes without applying
primo push --dry-run              # Show what would be sent
primo push --force                # Overwrite server changes (asks first, backs up first)

Options:

• -s, --server <url> — Server URL
• --site <id> — Push to a specific site ID
• --only <slug> — Only push the named folder under sites/ (skips library/)
• -d, --dir <dir> — Workspace directory (default: .)
• -t, --token <token> — Auth token
• --force — Overwrite changes made on the server since your last sync, after confirmation. A backup is saved first.
• --yes — Confirm --force without the interactive prompt (for scripts and CI)
• --preview — Ask the server for an import diff without applying changes. Also reports conflicts that would block a normal push; skips library uploads.
• --dry-run — Show planned operations without sending requests
• --publish — Publish the hosted sites after all selected pushes succeed; requires a compatible server
• --json — Return machine-readable push and publication results

Run primo push --dry-run to inspect planned operations. For an authenticated server-side import diff, use primo push --preview; review its output before applying changes. Neither option publishes the public site.

By default, a push updates the hosted CMS draft without publishing. Review it in the hosted editor and choose Publish, or use primo publish or primo push --publish with a compatible server.

Push Safety

A push replaces the server’s copy of a site with your local files. To keep it from silently erasing edits a client made in the CMS, Primo checks first: if the site changed on the server since your last pull or push, the push is refused before anything is uploaded:

Push stopped before any uploads:
  my-site: changed on the server since the last sync (or was deleted).
Nothing was changed. Save your local work before pulling. An intentional overwrite requires --force.

The check covers sites and the shared library (additions, deletions, field edits and reordering). It runs again on the server while the push is applied, so an edit made in the middle of a push still stops it.

Recover from a refused push

1. Save your local work

   Commit it, or copy the changed files somewhere outside sites/. A pull overwrites your local files with the server’s version.

2. Pull

   primo pull https://cms.example.com .
   
3. Redo your change and push

   Re-apply your edits on top of the pulled files (with Git, git diff shows what the client changed), then push again.

Watch: Recover from a refused CLI push

This local demonstration uses an isolated server and an explicit token. A hosted workflow can use the credentials saved by primo login. The final push updates the CMS; publish separately in the hosted editor.

Download video · Download captions

Read the walkthrough

1. Pull from the server to record a baseline. Here PRIMO_SERVER points to an isolated local demo.
2. After a local code edit and a server edit, push refuses to overwrite the newer server version.
3. Save the edited file outside sites/, then pull the latest server copy.
4. Reapply the saved code edit and push again. The server change is preserved.
5. The pushed headline appears in the CMS. On a hosted server, review and Publish to update the public site.

Overwrite on purpose with --force

If you’re sure your local files should win:

primo push https://cms.example.com --force

Primo lists what will be replaced and asks for confirmation. Before overwriting, the server saves a backup of its version and the CLI downloads a copy:

  Server backup: https://cms.example.com/api/primo/push-backups/<site-id>/backup-<id>.zip
  Local backup: .primo/backups/<site-id>/backup-<id>.zip

In a script or CI job, where there’s no prompt, pass --force --yes.

”No saved baseline”

my-site: has no saved baseline for this server. Pull first, or explicitly overwrite with --force.

Your workspace has never synced this site with this server, for example because it was copied from another machine or the site was created on the server separately. Pull first, or use --force if your files should replace the server’s. Pushing a site that doesn’t exist on the server yet needs no baseline.

Duplicate folders after a site rename

Pull names site folders from the site name. If a rename changes that folder name, a later pull can leave the previous folder alongside the new one. Both copies have the same site_id, so the CLI refuses to push them.

Save any edits you need, then move the older copy outside sites/ (for example, into _backups/). Keep one folder per site_id before pushing again. To create a separate site from a copy, remove its site_id and register it with primo add.

Version requirements

Push safety needs primo-cli 0.2.0 or later and Primo server 3.3.0 or later:

• An older CLI pushing to an existing site on a 3.3.0+ server gets 428 Push requires a sync baseline. Update the CLI and pull first, or explicitly force an overwrite with a backup. Update with npm i -g primo-cli@latest, then pull.
• CLI 0.2.0 refuses to push to an older server: Server does not support safe pushes. Update the CMS first; no upload was attempted.

Library-Only Sync

To move just the shared block library between workspaces and servers:

# Pull library into a workspace
primo library pull https://cms.example.com
primo library pull https://cms.example.com ./my-workspace

# Push library to a server
primo library push https://cms.example.com
primo library push https://cms.example.com -d ./my-workspace

primo library push has the same push safety check, --force, and --yes options as primo push.

This is useful when curating a block library independently of any particular site.

What Gets Synced

Synced	Not synced
Blocks (code, fields, content)	The deployed host for a site
Pages and page types	Authentication users and sessions
Site fields and head/foot code	Server admin settings (set in PocketBase)
Uploads in uploads/	Local-only .env files
library/ (with library push/pull)	Database backups

site.yaml metadata (name, group) round-trips. host is treated as per-environment routing config and is never overwritten by file sync.

Common Workflows

Edit in production, snapshot to Git

primo pull https://cms.example.com ./prod-backup
cd prod-backup
git init
git add . && git commit -m "Snapshot $(date)"

Edit locally, push to production

primo dev                                # Build and edit locally
primo push --dry-run https://cms.example.com         # Preview the push
primo push https://cms.example.com       # Apply

Move a site between servers

primo pull https://old-server.com ./workspace
primo push https://new-server.com -d ./workspace

Next Steps

Deploy

Deploy a workspace as an editable CMS or static site

Local Development

Run the local CMS with file/CMS sync