Wordpress Manager

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.