---
name: wordpress-manager
description: Manage WordPress remotely via local wp-cli over SSH. In this CodeAgents Mobile repo, primary use is selfhosted-ninja-prod — keep https://selfhosted.ninja/projects/codeagents-mobile/ in sync when product features, links, screenshots, or public copy change. Also supports updates, backups, restores, content, and custom plugins for configured sites.
---

# WordPress Manager

## This repository (CodeAgents Mobile)

See also `.agents/skills/skills.md` for when agents **must** use this skill.

- **Site key:** `selfhosted-ninja-prod` only in the committed template (`sites.selfhosted.yaml`).
- **Project pages (parent Projects **196**):** CodeAgents Mobile **203** — https://selfhosted.ninja/projects/codeagents-mobile/ ; MCP Bundler **224** — https://selfhosted.ninja/projects/mcp-bundler/ (links out to https://mcp-bundler.com/ — **never** 302 the product domain here).
- **Blog:** posts page **225** — https://selfhosted.ninja/blog/ ; categories `videos`, `codeagents-mobile`, `mcp-bundler`, `projects`. Prefer short posts with `core/embed` (YouTube) + project category for updates/videos so the blog is used often; project pages only link to categories.
- **Config:** `.skills-data/wordpress-manager/sites.yaml` (copy from `sites.selfhosted.yaml` in this skill folder if missing).
- **When product info changes** (features, App Store / TestFlight / GitHub links, screenshots, FAQ, iOS requirements, README highlights): update page **203** (and the Projects index blurb on **196** if needed) before considering the task done. Prefer core blocks (see `references/wp-7-block-themes.md`); use **`core/gallery`** for screenshots.
- Legacy `codeagentsmobile.maketry.xyz` is a **302** to the project page — do not maintain that static site as the source of truth.

## Quick start
- Install wp-cli locally (see "wp-cli installation").
- Ensure wp-cli is installed and on PATH for the remote SSH user (see "wp-cli installation (remote)").
- Initialize or copy the site registry to `.skills-data/wordpress-manager/sites.yaml` (this repo: start from `sites.selfhosted.yaml` in this skill directory).
- Pick the target site key (`selfhosted-ninja-prod` here), load its config, and build a base `wp` command.
- Run a read-only command first to validate connectivity.
- Apply the task-specific workflow below.

## wp-cli installation (local)
Requirements:
- Unix-like environment (macOS, Linux, FreeBSD, Cygwin).
- PHP 5.6 or later available on PATH.
- Remote WordPress 3.7 or later (older versions may have degraded functionality).

Install to the skill-local bin directory.

Preferred (scripted):
```
scripts/install_wp_cli.sh --base-dir .skills-data/wordpress-manager
```

Manual steps:
```
mkdir -p .skills-data/wordpress-manager/bin
curl -o .skills-data/wordpress-manager/bin/wp-cli.phar https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php .skills-data/wordpress-manager/bin/wp-cli.phar --info
chmod +x .skills-data/wordpress-manager/bin/wp-cli.phar
mv .skills-data/wordpress-manager/bin/wp-cli.phar .skills-data/wordpress-manager/bin/wp
```

Usage options:
- Call directly: `.skills-data/wordpress-manager/bin/wp --info`
- Or add to PATH for the session:
  `export PATH="$PWD/.skills-data/wordpress-manager/bin:$PATH"`

## wp-cli installation (remote)
When using `--ssh=...`, WP-CLI runs on the remote host, so the remote user must have `wp` on PATH.

Check if wp-cli is present on the remote host:
```
ssh <user@host> 'command -v wp >/dev/null && wp --info'
```

Helper script (uses sites.yaml):
```
scripts/ensure_remote_wp_cli.py --site-key <site_key> --install
```
Notes:
- The helper checks local wp-cli, updates it to the latest release (using git tags) when needed, then compares remote against local.
- It installs `~/bin/wp-cli.phar` and writes a `~/bin/wp` wrapper that uses a PHP CLI with `mysqli` when available.
- If no PHP CLI with `mysqli` is found, it will prompt you to install one.
- Override the local binary path with `--local-wp`, or skip the latest-release check with `--skip-local-update`.

Install to the remote user's home bin directory:
```
ssh <user@host> 'mkdir -p ~/bin && curl -o ~/bin/wp-cli.phar https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && chmod +x ~/bin/wp-cli.phar && mv ~/bin/wp-cli.phar ~/bin/wp'
```

If non-interactive shells do not include `~/bin`, set it explicitly:
- Client-side (per command): `WP_CLI_SSH_PRE_CMD='export PATH=$HOME/bin:$PATH'`
- Server-side: add `PATH="$HOME/bin:$PATH"` in the remote user's shell profile.

## wp-cli references
- Load `references/wp-cli-usage.md` for common command patterns and doc links.
- Load `references/wp-7-block-themes.md` for WordPress **7.0** block themes, template parts/sections, core blocks (Gallery, lightbox, Breadcrumbs, Icon, Navigation overlays), hybrid-theme limits (Blocksy), and safe `post_content` editing for marketing pages.
- Always verify flags with `wp <command> --help` before running writes.

## Local tooling (required)
- Keep all tool environments in `.skills-data/wordpress-manager/`.
- Create a Python venv at `.skills-data/wordpress-manager/venv` when a script needs dependencies.
- Create a PHP deps directory at `.skills-data/wordpress-manager/php-env` and install composer dependencies there when needed.
- Current scripts use Python standard library only; no pip installs required.
- Never install requirements globally.

## Site registry
- Use `.skills-data/wordpress-manager/sites.yaml` for multi-site configuration.
- Load `references/site-config.md` for the full schema.
- Prefer `ssh.host_alias` with `~/.ssh/config` for nonstandard ports or keys.
- Avoid storing passwords in YAML; use SSH keys and config.

## Build the base wp command
- Use the local binary: `.skills-data/wordpress-manager/bin/wp`.
- Remote execution: `wp --ssh=<user@host>:<wp_path>` and append `--url=<site_url>` when needed.
- If `host_alias` is set, use `wp --ssh=<host_alias>:<wp_path>`.
- Include `--allow-root` by default; omit it only when using a non-root SSH user.
- If remote wp-cli is installed in `~/bin`, set `WP_CLI_SSH_PRE_CMD='export PATH=$HOME/bin:$PATH'` for remote discovery.
- Validate with a read-only command such as `wp core version` or `wp option get siteurl`.

## Updates workflow
- If `update.pre_backup` is true, run the backup workflow first.
- If `update.maintenance_mode` is true, run `wp maintenance-mode activate` before updates and deactivate afterward.
- If `update.dry_run` is true, use `--dry-run` where supported or list pending updates.
- Update order: plugins, themes, then core unless the user specifies otherwise.
- Confirm with the user before core updates or major version jumps.

## Backups
- Respect `backups.include_db` and `backups.include_files`.
- For DB backups: run `wp db export` to `backups.remote_tmp_dir`, then `scp` to local.
- For file backups: use `rsync -az` for the `files_subdir` (default `wp-content`).
- Store backups in `.skills-data/wordpress-manager/backups/<site_key>/<timestamp>/`.
- Remove remote temp files after download and prune local backups when asked.

## Restores
- Recommend maintenance mode before restoring.
- For DB restores: upload the dump to `backups.remote_tmp_dir` and run `wp db import`.
- For file restores: `rsync -az` the backup `wp-content` to the remote `wp-content`.
- Confirm target site and backup timestamp before any restore.

## Content operations
- Ask for title, status, author, and slug when creating posts.
- Use `wp post create`, `wp post update`, `wp media import`, and `wp term` as needed.
- For multisite, pass `--url` from the site config.
- **Block markup (WordPress 7.0):** prefer core blocks in `post_content` over freeform HTML when a block exists. Load `references/wp-7-block-themes.md` for:
  - Block theme layers (templates, template parts / “sections”, patterns, global styles vs post content)
  - Hybrid themes (e.g. Blocksy on selfhosted.ninja): page title/hero is theme-owned; body is `post_content`
  - WP 7.0 additions: `core/breadcrumbs`, `core/icon`, `core/navigation-overlay-close`, gallery lightbox navigation, per-image lightbox, responsive visibility, pattern `contentOnly`
  - Recommended **Gallery** markup for product screenshots (`core/gallery` + nested `core/image` + `lightbox`)
  - Core block inventory and WP-CLI patterns for serialized content
- For screenshots / image grids on marketing pages, use a **`core/gallery`** block (not a bare list of `<img>` tags). Enable lightbox when enlarge-on-click is desired.
- Round-trip the **full** `post_content` when editing so block comment delimiters stay valid.

## Code changes (functions/plugins)
- Always ask whether the change should be a new plugin, a mu-plugin, or theme `functions.php`.
- Prefer a custom plugin for reusable logic; start from `assets/plugin-template.php`.
- For theme functions, confirm the active theme and whether a child theme exists before editing.
- Upload changes with `rsync` or `scp`; avoid editing directly on the server.
- Reactivate plugins or clear caches if needed.

## Validation and safety
- Confirm site key and target environment (prod/staging) before any write.
- Run a read-only command at the start of each session.
- Ensure local `ssh`, `scp`, and `rsync` are available; remote host must have PHP for `wp --ssh`.
- If `chrome-web-tools` is available and UI verification is needed, use it to spot-check admin pages.

## Example prompts
- "Update all plugins and themes on site marketing-prod with maintenance mode."
- "Backup database only for store staging."
- "Restore files and database from last night's backup on store staging."
- "Create a custom plugin that adds a [site_year] shortcode on client-a."
- "Add a function to disable comments in the active theme on blog-prod."
- "Create a draft post from markdown on docs site."
- "Put CodeAgents screenshots in a WP 7 gallery block with lightbox on selfhosted-ninja-prod."
- "Add the app logo before the page title on the CodeAgents Mobile project page."