Get started

This is an archived copy of the SandyWP docs. It is kept online as a fallback and may be out of date. The maintained documentation lives at docs.sandywp.com.

Push a local site

Building WordPress on your machine in Cove, LocalWP, MAMP, XAMPP, or any local stack? Run sandywp push from inside the install to mirror it into a public SandyWP sandbox: database, plugins, themes, and uploads, on a magic-login URL you can share.

Before you start

  • A SandyWP account, logged in with the CLI (sandywp auth login).
  • A local WordPress install with its database running the exact stack (Cove, LocalWP, MAMP, XAMPP…) doesn't matter.
  • Either wp (wp-cli) or php available on your PATH (used to export the database).

Install the CLI

# Install globally
npm install -g @sandywp/cli

# …or run without installing
npx @sandywp/cli push

Requires Node.js 18+. See the CLI reference for authentication details.

Your first push

Change into your local site's folder anywhere inside it works, since push walks up to find wp-config.php and run sandywp push:

$ cd ~/Sites/my-local-site
$ sandywp push
Found WordPress install at /Users/you/Sites/my-local-site
Exporting database...
Packaging wp-content...
Built archive (48.2 MB).
Restoring your site...
✓ Pushed to "my-local-site".
  url:    https://my-local-site.sandywp.dev
  login:  https://my-local-site.sandywp.dev/…
  Wrote /Users/you/Sites/my-local-site/.sandywp
  Tip: add `.sandywp` to your .gitignore it links this folder to a SandyWP site.

The first push does three things:

  1. Exports your local database and packages wp-content (skipping caches, VCS folders, and backup-plugin dumps).
  2. Creates a new sandbox and restores your site into it.
  3. Writes a .sandywp link file next to wp-config.php, then prints the public URL and a magic-login link.

Add --open to launch the magic-login link in your browser automatically.

Add .sandywp to your .gitignore. It links this folder to a specific SandyWP site and is specific to your machine not something to commit.

Push again after a change

Made edits locally a new plugin, content, theme tweaks? Run sandywp push again from the same folder. Because a .sandywp file now exists, it syncs into the same sandbox in place: the URL doesn't change and the site stays online. It overwrites the sandbox's database and files, so it asks you to confirm first:

$ sandywp push
Found WordPress install at /Users/you/Sites/my-local-site
This will OVERWRITE my-local-site's database and files. Continue? [y/N] y
Exporting database...
Packaging wp-content...
Syncing into your existing site...
✓ Pushed to "my-local-site".
  url:    https://my-local-site.sandywp.dev

To skip the prompt in scripts or a watch loop, pass --force:

sandywp push --force

A push is atomic if anything fails partway, the existing sandbox is left exactly as it was. And if you deleted the linked sandbox on SandyWP in the meantime, push offers to create a fresh one and re-link the folder.

Good to know

  • One-way sync. push goes local → SandyWP only. Changes you make directly on the sandbox are overwritten by the next push.
  • Unlink a folder. Delete .sandywp to stop repushing to that site the next push creates a new sandbox.
  • Big media. Uploads and existing backup archives can make the first push large; subsequent pushes send the full site again, not a diff.

Troubleshooting

“No wp-config.php found”

You're not inside a WordPress install. cd into your site's folder (the one containing wp-config.php, or a parent of the WordPress root) and try again.

“Neither wp nor php is available”

push needs one of them to export the database. Install wp-cli, or make sure your stack's php binary is on your PATH (LocalWP and MAMP ship their own PHP you may need to add it).

The database export fails or hangs

Your local database has to be running when you push start your local site in Cove / LocalWP / MAMP / XAMPP first. The bundled PHP exporter reads wp-config.php directly, so socket-based stacks like LocalWP work without wp-cli.

“Subdomain multisite is not supported”

Subdomain multisite networks can't be pushed. Single-site installs and subdirectory multisite networks are fine.

Confirmation prompt in a script

When you don't want the interactive overwrite? prompt (CI, a file-watcher, a deploy script), add --force.

Next steps