PBJ Studio Sync — User Guide

PBJ Studio Sync — Install & Usage Guide

Version 2.6.1

What this plugin does

PBJ Studio Sync pushes content one way, from a local WordPress Studio site (SQLite) to a live production site (MySQL). The same plugin installs on both sides and auto-detects which environment it is in:

• Studio side — "Push to live" button, backup importer, settings, log viewer.
• Live side — receiving REST endpoints, "Generate backup" button, "Check / fix REST API" button.

Content moves over the WordPress REST API as native WP objects (posts, terms, meta, files), so the SQLite/MySQL differences are handled by WordPress itself — there is no raw SQL translation.

Requirements

• A live WordPress site (6.3+, PHP 7.4+) with an admin account.
• The same site running locally in WordPress Studio.
• HTTPS on the live site — WordPress Application Passwords require it by default.

Installation

1. Install and activate pbj-studio-sync.zip on both the Studio site and the live site (Plugins → Add New → Upload Plugin → Activate).
2. If a Studio install refuses to replace an existing copy ("destination directory already exists"), use the pbj-installer helper plugin or remove the old pbj-studio-sync folder first.

First-time setup

1. Verify the REST API on Live

On the live site, open Studio Sync → Dashboard and click Check / fix REST API. It rebuilds rewrite rules, sets permalinks to /%postname%/ if they were on "Plain" (which blocks REST routes), and self-tests /wp-json/. Wait for the green confirmation. If it still fails, the cause is outside the plugin — usually a security plugin blocking REST, or a server-config issue.

2. Create an Application Password on Live

On the live site: Users → Profile → Application Passwords. Add one named "Studio Sync" and copy the 24-character password (keep the spaces).

3. Configure Studio

On the Studio site: Studio Sync → Settings. Enter the live site URL, the live admin username, and the Application Password. Under "What to sync", confirm the content types you want pushed — posts, media, and Navigation menus are on by default; theme, plugin, Users and Settings (wp_options + theme mods) sync are optional. Save.

Users / Settings sync (2.0). These two clone the live site beyond content — settings includes theme_mods (footers/headers/customizer) and plugin configuration; users includes roles, profile meta, and password hashes. The plugin always protects the live site's site/home URL, active-plugins list, theme selection, and the operator's own login from being overwritten. Even so, test these directions against a staging copy before running them onto real production.

4. Test the connection

Studio Sync → Dashboard → Test connection. You should see a green panel showing the live site's URL, WP version, PHP version, and database engine.

Daily usage

Pushing to live

Studio Sync → Dashboard → Push to live now. The progress UI shows each stage in order: terms → uploads → posts → menus → theme → plugins → plugin states → settings → users → prune → deletions → commit.

• The first push is automatically a full sync.
• Every push after that is incremental — only items modified since the last successful push are sent.
• To re-send everything, tick Force full sync this time before pushing.

Deletions

When you trash a post or delete a media file on Studio, the plugin records a "tombstone". The next push removes the same item from live by slug (including the underlying file for attachments). Untrashing a post before the next push cancels its tombstone.

Backups

• On live — "Generate backup" produces a .zip (MySQL dump + per-table JSON snapshot + uploads folder), downloadable via a one-time link.
• On Studio — "Import backup" restores that .zip into Studio. The importer reads the JSON snapshot, so it works across the SQLite/MySQL boundary. Use "wipe first" to clear content tables before restoring.

Compare & Sync (2.0)

Studio Sync → Compare & Sync (Studio only). Click Load comparison to see a per-section count of Studio vs. Live — posts, media, terms, theme, plugins, settings, users, menus — with a "≠" marker on anything that differs.

1. Tick the sections you want to move (rows that differ start checked).
2. Choose a direction:

• Upload — overwrite Live with Studio. Runs the push engine on just the ticked sections.
• Download — overwrite this local Studio with Live. Pulls a live backup and imports only the ticked sections. Affects your local site only.

1. Click Run sync and confirm.

Theme and plugin files aren't included in backups, so they're disabled in the Download direction — use Upload for those. Both sites must be on 2.0.0 for the comparison to load (the /summary endpoint is new in 2.0).

Auto-updates (optional)

Studio Sync → Settings → Auto-updates. Point at a GitHub repo (user/repo) or a JSON manifest URL. New versions then appear under Plugins → Installed Plugins with the normal "Update Now" button.

Troubleshooting

• 404 at /wp-json/ — run "Check / fix REST API" on live; check for a security plugin blocking REST.
• staged_file_missing during a push — a stage-order problem; uploads must run before posts (fixed in 1.5.1+).
• Media deletions not syncing — make sure you are on 1.5.4+, which adds the delete_attachment tombstone hook.
• Application Passwords unavailable — the live site needs HTTPS.
• HTTP 401 Authentication required on the final commit (push transferred but didn't finalize) — fixed in 2.5.1. A full push could write a setting mid-run that disabled Application Passwords on live, so the last call was rejected while your browser login stayed fine. 2.5.1 force-keeps Application Passwords available for the sync's own endpoints, so this can't recur. If you saw it on an older build: update both sites to 2.5.1, regenerate the Application Password on live, re-enter it in Studio, and re-run.
• Plugins didn't sync from Compare & Sync — the dashboard "Plugins to exclude" list does not apply to the Compare & Sync page (2.5.0+): it pushes ALL plugins except the syncer itself. Tick the Plugins section deliberately, and remember pushing caching/security plugins whose config differs between Studio and Live can break the live site.
• Per-item errors — listed in the Dashboard "Errors" section and in Studio Sync → Logs on both sides.

Where things live

• Canonical source + build zip — Jake's local ~/Documents/Claude/Projects/Wordpress Plugins/, mirrored to the WordPress Plugins/pbj-studio-sync/ folder in Google Drive.
• Staging area on each site — wp-content/uploads/pbj-sync/ (removed automatically on uninstall).