teejeer/wpcli-wpe repository overview

⁠WP-CLI + WP Engine

Manage WP Engine WordPress environments from the command line with WP-CLI⁠, run entirely in a Docker container — nothing needs to be installed on the host besides Docker.

⁠Requirements

• Docker
• An SSH key (ed25519) whose public half is added to your WP Engine User Portal → SSH Keys (SSH Gateway)
• SSH Gateway enabled on the target environment (per-environment setting in the portal)

⁠Quick start

# 1. Get the container image (Alpine + PHP + WP-CLI + ssh + mysql client)
docker pull teejeer/wpcli-wpe           # prebuilt image on Docker Hub
# ...or build it yourself:
docker build -t wpcli-wpe .

# 2. Run any WP-CLI command against an environment
./wp mysite plugin list
./wp mysite option get siteurl
./wp mysite core version

# 3. Or get an interactive shell on the WP Engine server
./wp mysite shell

<env> is the environment name from the User Portal (the same name used in <env>.wpengine.com). The wrapper connects as <env>@<env>.ssh.wpengine.net and runs WP Engine's on-server wp from /sites/<env>, the WordPress root.

⁠Configuration

No secrets belong in this repo. The private key stays in ~/.ssh/ and is mounted into the container read-only at runtime; it is copied inside the throwaway container with safe permissions and destroyed when the container exits.

⁠Docker image

The wp wrapper looks for an image named wpcli-wpe by default. If you pulled it from Docker Hub instead of building it, either retag it once:

docker tag teejeer/wpcli-wpe wpcli-wpe

or point the wrapper at the full image name:

export WPE_IMAGE=teejeer/wpcli-wpe

The image contains no secrets — your SSH key is mounted read-only at runtime and never baked in.

⁠Use it with OpenCode (or any AI agent)

This repo doubles as an agent-friendly toolbox: the wp wrapper is a plain non-interactive CLI, so an OpenCode⁠ agent (or Claude Code, Copilot, etc.) can run WP-CLI commands on your WP Engine environments while you work.

Just clone the repo and open it in OpenCode, then ask things like:

> check which plugins are out of date on staging
> list admin users on production
> what's the largest database table on staging?

Tips to make it work well:

• AGENTS.md (in this repo) tells the agent the syntax (./wp <env> <command>) and the gotchas before it tries anything.
• Keep environment names in NOTES.md § 5 — the agent reads them to know which environments exist.
• The agent runs inside your shell, so it uses the same SSH key and Docker image; no extra credentials are exposed to it.

⁠Why not wp --ssh=...?

WP-CLI's built-in SSH transport malforms the ssh invocation against WP Engine's gateway (it drops the user@host), so it always fails with Cannot connect over SSH using provided configuration. This wrapper instead ssh's directly and runs the remote wp binary that WP Engine ships. See NOTES.md for more gotchas (remote WP root path, older remote wp feature set, ssh key permission quirks).

⁠Files