AutoGineer
Generated banner for Wp Wpcli And Ops
Generated logo for Wp Wpcli And Ops

Wp Wpcli And Ops

WordPressOfficialPublished by WordPress

  • Skill
  • Tool integration
  • Software development
  • GPL-2.0-or-later
  • Low risk
  • Has scripts
Download ZIP

From the author

Use when working with WP-CLI (wp) for WordPress operations: safe search-replace, db export/import, plugin/theme/user/content management, cron, cache flushing, multisite, and scripting/automation with wp-cli.yml.
— the description by WordPress

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to performing WordPress administrative tasks via WP-CLI. It emphasizes safety, environment verification, and precise targeting to prevent accidental data loss or site misconfiguration. It covers common operational workflows including database management, plugin and theme lifecycle, multisite handling, and the creation of repeatable automation scripts.

What it does

  • Performs safe database search-replace operations for domain migrations
  • Manages plugin and theme installations, activations, and updates
  • Executes and debugs WordPress cron events and background tasks
  • Handles cache and rewrite rule flushing for troubleshooting
  • Supports multisite-specific commands and network-wide operations
  • Provides patterns for creating repeatable CI jobs and shell scripts using wp-cli.yml

When to use it

  • When performing site migrations or domain changes
  • When automating WordPress maintenance tasks in CI/CD pipelines
  • When debugging site issues related to caches, rewrites, or cron jobs
  • When managing large-scale plugin or theme updates across multisite installations
  • When you need to perform database exports or imports safely

Advantages

  • Reduces risk of destructive operations through mandatory environment verification
  • Standardizes operational procedures across different environments
  • Enables repeatable and version-controlled site management
  • Provides clear guardrails for sensitive tasks like search-replace
  • Facilitates efficient debugging of background processes

Usage examples

“I need to change the site URL from example.com to new-site.com. How do I do this safely?”
The agent will guide you to perform a database backup, run a dry-run search-replace to verify changes, execute the actual replacement, and flush caches.
“How can I update all plugins on my WordPress multisite network?”
The agent will provide the command to list plugins and perform updates using the --network flag to ensure all sites are covered.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/wordpress/wp-wpcli-and-ops/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip wp-wpcli-and-ops.zip -d .agents/skills

Documentation by WordPress

WP-CLI and Ops

When to use

Use this skill when the task involves WordPress operational work via WP-CLI, including:

  • wp search-replace (URL changes, domain migrations, protocol switch)

  • DB export/import, resets, and inspections (wp db *)

  • plugin/theme install/activate/update, language packs

  • cron event listing/running

  • cache/rewrite flushing

  • multisite operations (wp site *, --url, --network)

  • building repeatable scripts (wp-cli.yml, shell scripts, CI jobs)

Inputs required

  • Where WP-CLI will run (local dev, staging, production) and whether it’s safe to run.

  • How to target the correct site root:

    • --path=<wordpress-root> and (multisite) --url=<site-url>

  • Whether this is multisite and whether commands should run network-wide.

  • Any constraints (no downtime, no DB writes, maintenance window).

Procedure

0) Guardrails: confirm environment and blast radius

WP-CLI commands can be destructive. Before running anything that writes:

  1. Confirm environment (dev/staging/prod).

  2. Confirm targeting (path/url) so you don’t hit the wrong site.

  3. Make a backup when performing risky operations.

Read:

  • references/safety.md

1) Inspect WP-CLI and site targeting (deterministic)

Run the inspector:

  • node skills/wp-wpcli-and-ops/scripts/wpcli_inspect.mjs --path=<path> [--url=<url>]

If WP-CLI isn’t available, fall back to installing it via the project’s documented tooling (Composer, container, or system package), or ask for the expected execution environment.

2) Choose the right workflow
A) Safe URL/domain migration (search-replace)

Follow a safe sequence:

  1. wp db export (backup)

  2. wp search-replace --dry-run (review impact)

  3. Run the real replace with appropriate flags

  4. Flush caches/rewrite if needed

Read:

  • references/search-replace.md

B) Plugin/theme operations

Use wp plugin * / wp theme * and confirm you’re acting on the intended site (and network) first.

Read:

  • references/packages-and-updates.md

C) Cron and queues

Inspect cron state and run individual events for debugging rather than “run everything blindly”.

Read:

  • references/cron-and-cache.md

D) Multisite operations

Multisite changes can affect many sites. Always decide whether you’re operating:

  • on a single site (--url=), or

  • network-wide (--network / iterating sites)

Read:

  • references/multisite.md

3) Automation patterns (scripts + wp-cli.yml)

For repeatable ops, prefer:

  • wp-cli.yml for defaults (path/url, PHP memory limits)

  • shell scripts that log commands and stop on error

  • CI jobs that run read-only checks by default

Read:

  • references/automation.md

Verification

  • Re-run wpcli_inspect after changes that could affect targeting or config.

  • Confirm intended side effects:

    • correct URLs updated

    • plugins/themes in expected state

    • cron/caches flushed where needed

  • If there’s a health check endpoint or smoke test suite, run it after ops changes.

Failure modes / debugging

  • “Error: This does not seem to be a WordPress installation.”

    • wrong --path, wrong container, or missing wp-config.php

  • Multisite commands affecting the wrong site

    • missing --url or wrong URL

  • Search-replace causes unexpected serialization issues

    • wrong flags or changing serialized data unsafely

See:

  • references/debugging.md

Escalation

  • If you cannot confirm environment safety, do not run write operations.

  • If the repo uses containerized tooling (Docker/wp-env) but you can’t access it, ask for the intended command runner or CI job.

Files

scripts/wpcli_inspect.mjs

import { spawnSync } from "node:child_process";

const TOOL_VERSION = "0.1.0";

function parseArgs(argv) {
  const args = { path: null, url: null, allowRoot: false };
  for (const a of argv) {
    if (a === "--allow-root") args.allowRoot = true;
    if (a.startsWith("--path=")) args.path = a.slice("--path=".length);
    if (a.startsWith("--url=")) args.url = a.slice("--url=".length);
  }
  return args;
}

function runWp(cmdArgs, { pathArg, urlArg, allowRoot }) {
  const args = [];
  if (allowRoot) args.push("--allow-root");
  if (pathArg) args.push(`--path=${pathArg}`);
  if (urlArg) args.push(`--url=${urlArg}`);
  args.push(...cmdArgs);

  const out = spawnSync("wp", args, { encoding: "utf8" });
  return {
    ok: out.status === 0,
    status: out.status,
    error: out.error ? { message: out.error.message, code: out.error.code } : null,
    stdout: (out.stdout || "").trim(),
    stderr: (out.stderr || "").trim(),
    args,
  };
}

function main() {
  const opts = parseArgs(process.argv.slice(2));

  const info = runWp(["--info"], { pathArg: null, urlArg: null, allowRoot: opts.allowRoot });
  const report = {
    tool: { name: "wpcli_inspect", version: TOOL_VERSION },
    wpCli: {
      available: info.ok,
      info,
    },
    wordpress: {
      path: opts.path,
      url: opts.url,
      isInstalled: null,
      coreVersion: null,
      isMultisite: null,
      siteurl: null,
      home: null,
    },
    notes: [],
  };

  if (!info.ok) {
    report.notes.push("WP-CLI not available on PATH. Install WP-CLI or run inside the intended container/environment.");
    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
    return;
  }

  const isInstalled = runWp(["core", "is-installed"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
  report.wordpress.isInstalled = isInstalled.ok;

  if (!isInstalled.ok) {
    report.notes.push("WordPress not detected at the given path/url. Check --path/--url (multisite) and that wp-config.php is present.");
    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
    return;
  }

  const coreVersion = runWp(["core", "version"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
  report.wordpress.coreVersion = coreVersion.ok ? coreVersion.stdout : null;

  const isMultisite = runWp(["core", "is-installed", "--network"], {
    pathArg: opts.path,
    urlArg: opts.url,
    allowRoot: opts.allowRoot,
  });
  // If network check passes, we can assume multisite. If it fails, it might still be multisite depending on context.
  report.wordpress.isMultisite = isMultisite.ok;

  const siteurl = runWp(["option", "get", "siteurl"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
  report.wordpress.siteurl = siteurl.ok ? siteurl.stdout : null;

  const home = runWp(["option", "get", "home"], { pathArg: opts.path, urlArg: opts.url, allowRoot: opts.allowRoot });
  report.wordpress.home = home.ok ? home.stdout : null;

  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
}

main();

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

The author says: Targets WordPress 7.0+ (PHP 7.4.0+). Requires WP-CLI in the execution environment.

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
WordPress
Publisher
WordPress (Official)
Source
WordPress/agent-skills · skills/wp-wpcli-and-ops · commit 7374e6f
Licence
GNU General Public License v2.0 or later (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by WordPress.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download wp-wpcli-and-ops.zip