InstaWP CLI Command Reference

Every InstaWP CLI command, with its options and examples. New to the CLI? Start with the Overview.

Two global options apply everywhere:

Option	Description
--json	Output the result as JSON instead of formatted text
-V, --version	Print the CLI version

Run instawp <command> --help at any time for the built-in help.

Auth

instawp login

Authenticate with InstaWP. With no options it opens your browser to complete the handshake.

Option	Description
--token <token>	Authenticate with an API token instead of the browser (for CI and headless servers)
--api-url <url>	Override the API base URL

instawp login
instawp login --token $INSTAWP_TOKEN

instawp whoami

Show the current session — which account and team your commands run against.

Sites

instawp create

Create a new WordPress site. (Alias for sites create.)

Option	Description
--name <name>	Site name
--wp <version>	WordPress version (e.g. 6.8)
--php <version>	PHP version (e.g. 8.3)
--config <id>	Create from a Configuration
--temporary	Create as a temporary site (default is permanent)
--no-wait	Return immediately instead of waiting for the site to become active

instawp create --name my-site --php 8.3
instawp create --name my-site --php 8.4 --json
instawp create --name demo --config 1234 --temporary

instawp sites list

List your sites.

Option	Description
--status <status>	Filter by status
--page <page>	Page number (default 1)
--per-page <count>	Results per page (default 50)
--all	Fetch every page

instawp sites list --all --json

instawp sites creds <site>

Show the WP admin username, password, and Magic Login URL for a site.

instawp sites php <site>

View or update a site's PHP version and settings.

Option	Description
--version <version>	PHP version (7.4, 8.0, 8.1, 8.2, 8.3)
--memory-limit <mb>	memory_limit in MB (64–1024)
--max-execution-time <sec>	max_execution_time in seconds (30–300)
--upload-max-filesize <mb>	upload_max_filesize in MB (64–512)
--post-max-size <mb>	post_max_size in MB (64–512)
--max-input-vars <n>	max_input_vars (1000–10000)
--max-input-time <sec>	max_input_time in seconds (60–120)

instawp sites php my-site                                   # view current settings
instawp sites php my-site --version 8.3 --memory-limit 512

instawp sites delete <site>

Delete a site permanently.

instawp sites delete my-site --force

instawp open <site>

Open a site in your default browser.

Option	Description
--admin	Open /wp-admin instead of the homepage
--magic	Open the magic login URL (an auto-logged-in admin session)
-p, --print	Print the URL to stdout instead of opening it

instawp open my-site --magic
instawp open my-site --admin --print

Versions

Versions are restorable point-in-time copies of a site — take one before anything risky.

instawp versions create <site>

Option	Description
--name <name>	Label for the version (max 25 characters)
--no-wait	Return immediately instead of waiting for the version to finish

instawp versions create my-site --name "before plugin update"

instawp versions list <site>

List a site's versions.

instawp versions restore <site>

Roll a site back to a version.

instawp versions delete <site>

Delete versions you no longer need.

Remote access

instawp wp <site> <args...>

Run WP-CLI on a hosted site. This is the primary remote-access command — it connects over SSH and manages the key for you.

Option	Description
--api	Use the API transport instead of SSH
--timeout <seconds>	Command timeout, API mode only (default 30)
--ssh-host <host>	Override the SSH host (for CDN-fronted sites; also INSTAWP_SSH_HOST)
--refresh	Re-resolve SSH access, ignoring the cached host
--no-fallback	Do not fall back to --api when SSH is unreachable

instawp wp my-site plugin list
instawp wp my-site theme activate twentytwentyfour
instawp wp my-site -- post list --post_type=page      # use -- to pass raw WP-CLI args
instawp wp my-site eval '\MyClass::init(["force" => true]);'

TIP

Wrap PHP/eval payloads in single quotes — arguments are shell-escaped automatically before being sent to the remote shell.

--api runs the command over HTTPS instead of SSH, so it still works from networks where outbound SSH is blocked — locked-down VPNs, corporate networks, and some CI runners. The CLI falls back to --api on its own when SSH is unreachable; pass --no-fallback if you would rather the command fail than switch transport.

instawp wp my-site plugin list --api
instawp wp my-site user list --api --json | jq '.data'

instawp ssh <site>

Open an interactive SSH shell on a site. The CLI generates, uploads, and caches the SSH key the first time, so there is nothing to set up.

Option	Description
--ssh-host <host>	Override the SSH host
--refresh	Re-resolve SSH access, ignoring the cached host

instawp exec <site> <args...>

Escape hatch: run arbitrary shell commands on a site. For WordPress work use wp instead.

Option	Description
--api	Use the API transport instead of SSH
--shell	Run the arguments as one shell command line on the remote (enables pipes, ;, >, globs)
--stdin	Stream local stdin to the remote command (SSH only)
--timeout <seconds>	Command timeout, API mode only (default 30)
--no-fallback	Do not fall back to --api when SSH is unreachable

instawp exec my-site ls -la
instawp exec my-site -- tail -n 50 wp-content/debug.log
instawp exec my-site --shell 'ps aux | grep php'
printf 'data' | instawp exec my-site --stdin --shell 'cat > /tmp/f'

WARNING

Shell metacharacters (|, ;, >, globs) are not interpreted by default — each argument is sent as a single literal token. Use --shell when you need a pipeline or a compound command.

instawp sql <site> <query>

Run a SQL query against the site's database via WP-CLI. It hits MySQL directly, so it bypasses the object cache.

instawp sql my-site "SELECT option_value FROM wp_options WHERE option_name='siteurl'"
instawp sql my-site "SELECT COUNT(*) FROM wp_posts WHERE post_status='publish'"

instawp logs <site>

Tail a site's logs.

Option	Description
--wp	WordPress debug.log (default)
--php	PHP-FPM error log
--nginx	nginx error log
-f, --follow	Follow the output (tail -f)
-n, --lines <n>	Number of lines to show (default 100)

instawp logs my-site --php -n 200
instawp logs my-site -f

instawp cache purge <site>

Purge the site's CDN cache.

Option	Description
--object	Also clear the server object cache (Redis), where the plan includes it

instawp plugin install <site> <path>

Install a plugin from a local .zip file or directory — useful for plugins that are not on wordpress.org.

Option	Description
--activate	Activate the plugin after installing it

instawp plugin install my-site ./dist/my-plugin.zip --activate

Sync

instawp sync push <site> / instawp sync pull <site>

Sync wp-content/ between your machine and a hosted site, using rsync under the hood.

Option	Description
--path <path>	Local source path (default ./wp-content/)
--remote-path <path>	Remote target path (absolute, or relative to public_html/)
--webroot	Target the site webroot (public_html/) instead of wp-content/
--exclude <pattern...>	Additional exclude patterns
--include <pattern...>	Include patterns
--delete	Delete remote files that are absent locally (makes the remote mirror local)
--yes	Skip the --delete confirmation prompt
--dry-run	Show what would be transferred, without transferring it

instawp sync push my-site --path ./wp-content/ --dry-run
instawp sync push my-site --path ./wp-content/
instawp sync pull my-site

TIP

Run with --dry-run first, especially before using --delete.

instawp db push <site> <file> / instawp db pull <site>

Push a local SQL dump to a site's database, or pull the remote database down. A remote backup is taken automatically before an overwrite.

Option	Description
--force	Skip the confirmation prompt
--no-backup	Skip the pre-overwrite backup (dangerous)
--rewrite-prefix	Rewrite the dump's table prefix to match the remote site's prefix (e.g. wp_ → iwpa4c7_)
--search-replace <from> <to>	After import, run a serialization-safe wp search-replace across all tables
--sr-tables <table...>	Scope --search-replace to specific tables — faster on large databases
--verify	After import, poll the site URL until it responds
--incremental	Push only the row-level delta since the last push
--full	Force a full push and refresh the incremental baseline
--api	Use the API transport instead of SSH (for CDN-fronted sites)

instawp db push my-site ./dump.sql --search-replace http://localhost:8080 https://my-site.instawp.xyz --verify

WARNING

db push overwrites the remote database. It backs the remote up first unless you pass --no-backup — do not pass --no-backup unless you are certain.

Local development

Covered in detail in Local Development with the CLI.

Local sites run on WordPress Playground (WebAssembly PHP + SQLite) — no Docker or MySQL required.

Command	Description
local create	Create and start a local WordPress site
local clone <cloud-site>	Clone an InstaWP cloud site to your machine
local start [name] / local stop [name]	Start or stop an existing local site
local push <local-name> [cloud-site]	Push local wp-content to a cloud site. Omit cloud-site and it pushes to the site the instance was cloned from — or creates a new one if there is none. Add --with-db to push the database too, --dry-run to preview
local pull <local-name> <cloud-site>	Pull wp-content from a cloud site down to a local site
local list	List your local sites
local delete <name>	Delete a local site and its data (--force to skip the prompt)

Migration

instawp migrate push [path]

Mirror an existing local WordPress install (files and database) to a brand-new hosted InstaWP site.

Option	Description
--path <dir>	Path to the local WordPress install
--name <name>	Name for the new hosted site (defaults to the WP directory name)
--source-url <url>	Local site URL (auto-detected from wp-cli / wp-config.php if omitted)
--wp <version>	WordPress version for the new site (defaults to the detected local version)
--php <version>	PHP version for the new site
--keep-archives	Keep the temporary zip/SQL archives instead of deleting them
--dry-run	Print the migration plan without creating a site or uploading anything

instawp migrate push ./my-wordpress --name staging-copy --dry-run
instawp migrate push ./my-wordpress --name staging-copy

Teams

Command	Description
teams list	List the teams you belong to
teams switch	Switch the active team that commands run against
teams members	List the members of the active team

Updating

instawp upgrade

Update the CLI to the latest version. The CLI checks once a day and prints a hint when an update is available; set INSTAWP_NO_UPDATE_NOTIFIER=1 to turn that off.

Environment variables

Variable	Purpose
INSTAWP_TOKEN	API token — authenticates without a browser (CI, containers, agents)
INSTAWP_SSH_HOST	Override the SSH host for CDN-fronted sites
INSTAWP_NO_UPDATE_NOTIFIER	Set to 1 to silence the daily update check