| name | wordpress-cli |
| description | Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. Execute wordpress operations using the `wordpress` CLI tool. CLI interface for WordPress API -- manage posts, pages, media, categories, and tags. Triggers: wordpress, wordpress cli, wordpress posts, wordpress pages, wordpress page, update wordpress page, edit wordpress page, wordpress media, create wordpress post, upload wordpress image, wordpress categories, wordpress tags, publish blog post, wordpress blog, wordpress site |
Execute wordpress operations using the `wordpress` CLI. All wordpress interactions should use this CLI.
<quick_start>
The wordpress CLI follows this pattern:
wordpress <command-group> <action> [arguments] [options]
| Task | Command |
|---|
| List posts | wordpress posts list --table |
| Get a post | wordpress posts get POST_ID |
| Create from Markdown | wordpress posts create --from-markdown file.md |
| Create from DOCX | wordpress posts create --from-docx file.docx |
| Publish a draft | wordpress posts update POST_ID --status publish |
| List pages | wordpress pages list --table |
| Get a page (raw HTML) | wordpress pages get PAGE_ID --raw |
| Find page by slug | wordpress pages list --filter slug:eq:my-slug |
| Update page content | wordpress pages update PAGE_ID --content-file page.html |
| Upload media | wordpress media upload image.png |
| List categories | wordpress categories list --table |
| List tags | wordpress tags list --table |
| List plugins | wordpress admin plugins list --table |
| Upgrade plugin | wordpress admin plugins upgrade PLUGIN |
| List themes | wordpress admin themes list --table |
| Preview theme file push | wordpress admin themes file-push THEME LOCAL_FILE REMOTE_FILE --remote-root /path/to/wp --host host --dry-run |
| Push theme file | wordpress admin themes file-push THEME LOCAL_FILE REMOTE_FILE --remote-root /path/to/wp --host host --backup --yes |
| Save WordPress.com OAuth credentials | wordpress org token save-credential --client-id ... --client-secret ... --username ... --password ... --site ... |
| Refresh WordPress.com token | wordpress org token |
| </quick_start> | |
<essential_principles>
MANDATORY: Consult the adjacent usage.json at <cli-tools-root>/_repo/skills/<tool>-cli/usage.json before executing ANY wordpress command.
This file contains complete command syntax, all arguments, all options, and usage instructions for every command. Never guess at command syntax.
- **auth** -- Authentication commands and nested `auth profiles` management
- **auth** — Authentication: login, logout, status, refresh, test
- **posts** — Full post lifecycle: list, get, create (from DOCX/Markdown), update, delete
- **pages** — Page lifecycle: list, get, create (from DOCX/Markdown), update (supports --content-file), delete. Pages support `parent`, `menu_order`, `template` (no tags/categories/format).
- **media** — Media library: list, get, upload, delete
- **categories** — Category management: list, get, create, update, delete
- **tags** — Tag management: list, get, create, update, delete
- **admin** — WordPress admin maintenance, including plugin list/get/activate/deactivate/delete/install/upgrade and theme list/get/file-push through explicit SSH settings
- **org** — WordPress.com OAuth token commands used by Jetpack plugin updates
If a diagnostic task must import WordPress CLI internals directly, use the live
`wordpress` launcher shebang interpreter and the actual source module paths.
There is no `wordpress_cli.auth` module; auth commands are mounted from shared
CLI tooling, and the WordPress API client factory lives in `wordpress_cli.client`.
For task-workspace scripts that intentionally import `wordpress_cli.client`, do
not add local `sys.path` bootstraps to satisfy Pyright; run the script with the
launcher-derived interpreter and, if Hermes reports `reportMissingImports`, add a
line-local suppression such as
`from wordpress_cli.client import get_client # pyright: ignore[reportMissingImports]`.
launcher="$(command -v wordpress)"
interpreter="$(head -1 "$launcher" | sed 's/^#!//')"
"$interpreter" - <<'PY'
from wordpress_cli.client import get_client
client = get_client()
PY
ACF options can be read from the site's ACF to REST API endpoint, for example
`GET /wp-json/acf/v3/options/options/site_ad_settings`, but do not use that
endpoint for ATA sitewide option writes. On the ATA Blog, ACF to REST API 3.3.4
advertises editable options routes, but authenticated administrator no-op POST,
PUT, and PATCH probes to `/acf/v3/options/options/site_ad_settings`,
`/acf/v3/options/options/site_ad_settings_logo`, `/acf/v3/options/option`, and
`/acf/v3/options/options` all return `500 Cannot update item`, including the
documented `fields[...]` body shape. Treat this as an unavailable REST write
capability, not a payload-shape typo.
For ATA sitewide ACF option changes, use a server-side WordPress execution path
that loads ACF, such as WP-CLI on the WordPress host, and update the ACF option
fields with update_field(..., 'option') after backing up the REST GET response.
Example method for the sitewide ad settings:
wp eval 'update_field("site_ad_settings_logo", 26999, "option"); update_field("site_ad_settings_link", "https://specopssoft.com/product/specops-password-auditor/?utm_source=adamtheautomator&utm_medium=referral&utm_campaign=adamtheautomator_referral_na&utm_content=display", "option"); update_field("site_ad_settings_text", "<p>Audit your Active Directory for weak passwords and risky accounts. <strong><a href=\"https://specopssoft.com/product/specops-password-auditor/?utm_source=adamtheautomator&utm_medium=referral&utm_campaign=adamtheautomator_referral_na&utm_content=display\">Run your free Specops scan</a> now!</strong></p>\n", "option");'
Preserve valid HTML and use & inside HTML attributes when updating the copy
field. Verify with GET /wp-json/acf/v3/options/options/site_ad_settings.
Many themes wrap page content in a narrow typography container (Tailwind `prose`
+ `max-w-[NNch]`, a constrained `entry-content`, etc.). Rendering a rich
landing/About page as plain blocks inside such a container looks broken: it is
too narrow for multi-column layouts, and the typography styles restyle headings
and underline button links. The fix is NOT a full-page custom shell that hides
the theme's header/nav or forces full-bleed -- that fights the theme.
When a page needs a custom landing layout, build it as ONE self-contained
<!-- wp:html --> block instead of plain blocks:
- First DISCOVER the wrapper: load the live page and inspect the content
ancestor chain (DevTools or
playwright-cli eval) to find the class and the
max-width that constrains content.
- Namespace all styles under a wrapper class and give every styled element a
class. If the theme uses Tailwind Typography, its rules use
:where() (zero
specificity), so class-based rules override them without !important.
- Widen only that page's column with a page-scoped selector
(
body.page-id-<ID> .<content-wrapper>{max-width:100%}) -- never a global
override.
- Keep the theme header, nav, and footer; do not hide chrome.
- Drive component colors from CSS variables and SUPPORT the theme's dark mode:
detect its strategy first (a
.dark/.theme-dark class toggled on <html>
or <body>, vs. @media (prefers-color-scheme: dark)), then redefine the
variables under that selector so the page re-skins to match the dark chrome
instead of sitting as a light island. Verify both modes with screenshots.
Always visually verify the live page after the update (screenshot desktop and
mobile) and iterate against the target design before calling it done.
</essential_principles>
<reference_index>
usage.json — Complete command tree with arguments, options, defaults, and usage instructions for every command.
</reference_index>
<success_criteria>
- Command executes without error
- Output is displayed in requested format
- Correct command and flags used (verified against usage.json)
</success_criteria>
