Local Development with the InstaWP CLI

The InstaWP CLI runs WordPress on your own machine using WordPress Playground — PHP compiled to WebAssembly, with SQLite as the database. There is no Docker, no MySQL, and no local server stack to install: if you have Node.js 18+, you can start a WordPress site. Local sites are free and unlimited.

The point is that local and cloud are the same tool. You can build locally, push to a hosted InstaWP site when you want to share it, and pull a cloud site back down when you need to debug it.

This CLI Just Changed My WordPress Workflow

Create a local site

instawp local create --name my-plugin-dev --php 8.3

Option	Description
--name <name>	Instance name (auto-generated if omitted)
--wp <version>	WordPress version (default latest)
--php <version>	PHP version, 7.4–8.5 (default 8.3)
--port <port>	Server port
--blueprint <path>	Blueprint JSON file to preinstall plugins/themes and set state
--no-open	Do not open the browser
--background	Run the server in the background and return immediately

The site starts and opens in your browser on a local address such as http://127.0.0.1:9400. Use --background when you are scripting, and --no-open to leave the browser alone.

Blueprints

A Playground blueprint is a JSON file describing the WordPress state you want — plugins to install, theme to activate, options to set. Pass one to get a reproducible starting point every time:

instawp local create --name testbed --blueprint ./blueprint.json

Manage local sites

instawp local list                          # see every local site
instawp local start my-plugin-dev           # start one that is stopped
instawp local stop my-plugin-dev            # stop a background site
instawp local delete my-plugin-dev --force  # remove it and its data

local start takes the same --blueprint, --no-open, and --background options as local create. local delete takes --force to skip the confirmation prompt.

Clone a cloud site to local

Pull a complete hosted site — files and database — onto your machine to debug it or work offline:

instawp local clone my-site

Option	Description
--name <name>	Local instance name (defaults to the cloud site's name)
--no-start	Do not start the local site after cloning
--force	Overwrite an existing local instance with the same name
--include <pattern...>	Extra rsync include patterns (e.g. .git)

Move work between local and cloud

Once a local site exists, local push and local pull move wp-content in each direction:

instawp local push my-plugin-dev              # local wp-content → the cloud site it was cloned from
instawp local push my-plugin-dev my-cloud-site # → an explicit cloud site
instawp local pull my-plugin-dev my-cloud-site # cloud wp-content → local site

local pull <local-name> <cloud-site> always needs both arguments. On local push <local-name> [cloud-site] the cloud site is optional, and what happens when you omit it depends on whether the CLI knows where the local site belongs:

1. You name a cloud site → it pushes there. If the local site had no remembered target yet, this one is recorded for next time.
2. You omit it and the local site was created by local clone → it pushes back to the site it was cloned from.
3. You omit it and there is no remembered target → the CLI creates a new cloud site named after your local instance and pushes into that.

That third case is the one to watch: a bare local push on a site you built with local create provisions real hosted infrastructure. Run --dry-run first if you are not sure which case you are in — it tells you the target (or that it would create a site) and never provisions anything.

Option	Description
--dry-run	Show what would be transferred, without transferring it
--include <pattern...>	Extra rsync include patterns (e.g. .git)
--exclude <pattern...>	Additional exclude patterns

local push can also carry the database along with the files:

Option	Description
--with-db	Also push the local database, overwriting the cloud database (a backup is taken first)
--no-backup	With --with-db: skip the pre-overwrite backup (dangerous)
--force	With --with-db: skip the overwrite confirmation prompt

instawp local push my-plugin-dev --dry-run             # always check first
instawp local push my-plugin-dev --with-db             # files + database

WARNING

--with-db replaces the cloud site's database with your local one. Run --dry-run first, and do not pass --no-backup unless you are certain you will not need to roll back.

Promote a local install to a hosted site

If you already have a WordPress install on disk — not created by local create — migrate push mirrors it (files and database) to a brand-new hosted InstaWP site:

instawp migrate push ./my-wordpress --name client-preview --dry-run   # check the plan first
instawp migrate push ./my-wordpress --name client-preview

The CLI auto-detects the local site URL and WordPress version from wp-cli or wp-config.php, creates the new site, uploads the files, imports the database, and rewrites URLs for you.

A typical loop

# 1. Build locally
instawp local create --name feature-x --php 8.3

# 2. Work on your plugin/theme in ./wp-content

# 3. Share it — push to a hosted site the client can open
instawp create --name feature-x-preview --php 8.3
instawp sync push feature-x-preview --path ./wp-content/ --dry-run
instawp sync push feature-x-preview --path ./wp-content/
instawp open feature-x-preview --magic

# 4. Clean up
instawp sites delete feature-x-preview --force
instawp local delete feature-x

Next

• Command Reference — every flag on every command
• CI/CD and AI Agents — automate this loop