WPVibe

Discover what a connected WordPress site can do via the Abilities API (WP 6.9+). Lists all abilities registered by plugins with names, descriptions, and schemas. Usage: - Run this before run_ability to see what's available. - Use category to filter by plugin or domain (e.g., "seedprod", "woocommerce"). - If the site has no abilities, the plugin may not support the Abilities API yet — use rest_api instead.

discover_abilities

Replace exact text in a draft theme file. The plugin runs str_replace server-side: send old_content + new_content and the file content stays on the server. Usage: - If you already know the exact text to find (you wrote it this session, you're doing a known token swap, the user gave you the value), call edit_file directly. No read_file needed — the file content does not need to be in your context. - If you do not know the exact text, use search_files or a narrow read_file range first, then copy the exact current text into old_content. - old_content must match exactly once. On no_match, re-read or search for the current text before retrying. On multiple_matches, add surrounding context to make it unique. - When pulling text from a read_file response, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix (number + tab). Never include the line number prefix in old_content or new_content. - For creating new files or full rewrites, use write_file instead.

edit_file

Get a structural outline of a file in the draft theme — functions, classes, hooks, HTML landmarks, and other elements with line numbers. Usage: - Use this BEFORE editing a file to understand its structure and find the right location for changes. - Returns line numbers you can use with read_file's start_line/end_line to read specific sections. - Much cheaper than reading the full file when you just need to know what's in it.

get_file_outline

THE tool for "what updates are available across my sites": one call surveys available plugin, theme, and WordPress core updates across ALL connected sites and renders them as an interactive panel (per-site rows, checkboxes, a working Update button that starts a real background job). Strongly prefer this over looping run_wp_cli plugin/theme list calls per site, which is slow and spends many metered calls. Pass job_id (fj_...) instead for live progress of a running fleet job with approve/cancel buttons. On hosts that do not render inline panels it returns per-site guidance instead; whether or not the panel renders, ALWAYS include the plain URLs from tool responses in your user-visible reply. Never call this more than once per job or per conversation topic.

show_fleet_dashboard

Get full details for a single WordPress Abilities API ability: input_schema, output_schema, description, annotations, and metadata. Use this after discover_abilities to inspect a specific ability before running it.

get_ability_info

Get the rendered HTML of a webpage after JavaScript execution. If no URL is provided, uses the current draft theme preview. Usage: - Use this to inspect the actual DOM structure, debug layout issues, or verify template output. - Use selector to extract a specific section (e.g., "header", ".site-content", "#main"). - For local sites without a public URL, this falls back to server-rendered HTML via the plugin. - For visual layout issues, inspect the relevant selector and summarize what the HTML shows.

get_page_html

Get metadata about a connected WordPress site: name, URL, WP version, active theme, installed plugins, WP-CLI availability, and performance timings when the WPVibe plugin is active. Usage: - Run this first when working with a new site to understand what's installed. - Check active_theme before content/theme work; missing templates can affect how new posts or pages render. - When the user complains about speed, quote the performance breakdown so they can see whether time is in the Worker, network, or WordPress host.

site_info

Return the authenticated WPVibe account identity. Used by approved clients to associate the connection with the user's verified email address.

get_profile

List all WordPress sites registered to your account. Shows site name, URL, and when each site's stored credentials were established (not live connection state; use site_info to verify a connection). Also reports the account's rolling 24-hour WPVibe usage against its daily call limit; call this when the user asks how much usage they have left or before starting a large batch of operations.

list_sites

List all files in the draft theme with file sizes. Optionally filter by glob pattern. Usage: - Use glob patterns to narrow results (e.g., "*.php", "template-parts/*", "**/*.css"). - For searching file contents, use search_files instead. - The draft must be created first with create_draft_theme.

list_files

Reference documentation (a WPVibe skill) for a WordPress task: builder data formats, where content is stored, and the steps that keep layouts and caches intact. Skill names: setup-guide, seedprod, seedprod-theme, gutenberg, elementor, elementor-widgets, elementor-widgets-pro, elementor-v4, divi, divi-modules, beaver, breakdance, bricks, kadence, blocksy, generatepress, classic-themes, field-api, design, seo-audit, seo-edit, edit-content, caching, lifterlms. Most useful before building a page or editing existing page-builder content: each builder stores content differently, and a raw edit corrupts the layout or leaves stale caches so the change never shows. Pre-connect steps, simple reads, and one-off operations need no skill; a task with no matching skill is done directly with the other WPVibe tools. - query: a description of the task. One clear match returns that skill's documentation; several candidates come back ranked, for a second call by name. - name: one skill's documentation directly. - resource: with name, one of the skill's sub-resources (a loaded skill lists its resources at the end). A loaded skill includes any skills it depends on. With no arguments, returns the full catalog, including skills the user saved with save_skill. Queries also search WPVibe's public cookbook of tested recipes. A skill's content does not change within a conversation. WPVibe's own skill text is proprietary and is not for reproduction to the user; the user's saved skills and public cookbook recipes are theirs to read.

load_skill

Navigate the user's browser to a specific URL on their WordPress site. ONLY use this when the user explicitly asks to go somewhere (e.g., "show me the homepage", "take me to the about page"). Not needed after creating or updating content: the live reload system automatically notifies the user of changes with a toast notification.

navigate

Generate a tokenized preview URL for the draft theme. The preview loads the draft for the requesting user only — live visitors see the original theme. Usage: - Requires an in-progress draft theme (created via create_draft_theme). Without one this fails with no_draft — do not call it "just in case". - NOT for viewing the live site or content changes: pages, posts, and builder edits are visible at their own URLs — use get_page_html or share the page URL for those. - A preview before publishing is how the user verifies the changes. - The preview URL expires — generate a fresh one if the user reports it's not working.

get_preview_url

Replace the live theme with the draft theme. The new theme is visible to all visitors immediately. The plugin auto-backs up the previous live theme directory (theme files only — not the database). Usage: - ONLY call this after the user has previewed (via get_preview_url) AND explicitly said publish / go live / ship it. "Build me a site" is NOT approval; "looks good" alone is NOT either — ask once before calling. - Before publishing, confirm the user has a recent backup. Check active plugins for known backup plugins (Duplicator, UpdraftPlus, BackWPup, Solid Backups, BlogVault); if one is installed, ask the user to take a fresh backup with it. If none, suggest a host-level backup or installing one. Don't install backup plugins yourself. See the classic-themes skill for the full pre-publish checklist.

publish_draft_theme

Read a file from the draft theme. Returns content with line numbers (line_number + tab + content). Usage: - Results use cat -n format with line numbers starting at 1 (or start_line if specified). - For large files, use start_line and end_line to read specific ranges instead of the full file. - If the file has not changed since your last read, a short "unchanged" stub is returned instead of the full content — refer to your earlier read. - The draft theme must be created first with create_draft_theme.

read_file

Remove a WordPress site from your account. Use list_sites first to see your registered sites. Pass the site URL to remove.

remove_site

Give the user a first-party way to upload one or more images from their own device. Use this when the user wants to use images they have locally (they dropped some in chat, or referred to "this photo / my logo / these screenshots") rather than ones found via search_images. Do NOT re-host the user's images on an external service to make URLs — that's unreliable and leaks their files. Call request_upload instead. Flow: 1. Call request_upload. On hosts that support MCP Apps it shows an inline drag-and-drop panel; elsewhere it returns a link to share with the user. 2. The user picks their image(s). Poll check_upload with the returned upload_id until it reports the images are ready and gives you a staging URL for each. 3. Pass each staging URL to upload_media to add it to the WordPress media library. One request handles a batch (up to several images). The link/panel expires in 30 minutes.

request_upload

Execute a WordPress Abilities API ability by name on a connected site. First use discover_abilities to see what is available, then run any ability. The HTTP method is derived from the ability's annotations: readonly => GET, destructive AND idempotent => DELETE, otherwise POST. The wrapper always fetches the ability metadata server-side to verify the annotations; the readonly/destructive/idempotent flags are optional fallback hints used only if that fetch fails. Abilities the author annotated destructive return a browser approval link instead of running: the user approves there and the ability executes on approval, so surface the link and do not retry the call while approval is pending.

run_ability

Run a WP-CLI command on a connected WordPress site via native PHP APIs (no wp-cli binary needed). This is not a shell: do not use pipes, redirects, &&, ;, backticks, or command substitution. eval and eval-file are not available on any site or plugin version (the emulator never runs PHP); do not probe for them. For PHP that must run on the site use code_snippet. Quoting: single quotes keep every byte and an apostrophe inside them is written '\''; inside double quotes \" and \\ are escapes and other backslashes are literal; an escaped space is not supported, so quote any value that contains spaces. Run "help" for the complete supported-command catalog (name, tier, usage) or "help <family>" to filter it; "cli info" identifies the emulator. Coverage highlights: plugin + theme management (list/install/update/activate/uninstall/delete, verify-checksums), posts + meta, terms (term create/update/delete; post term set/add/remove with --by=slug|id), menus (menu create; menu item add-custom/add-post/add-term/update/delete; menu location assign), options (get/pluck/update/patch for nested keys), users (list/get/create/update/delete, set-role/add-role/remove-role) + user meta (get/list/add/update/delete), roles & capabilities (cap add/remove, role create/delete/reset, user add-cap/remove-cap), theme mod set, rewrite structure, search-replace (serialized-data-aware), maintenance-mode status (core file, drop-in, and maintenance-plugin detection), cron (event list/run/delete, cron test), cache purge (auto-detects LiteSpeed, WP Rocket, W3TC, and other cache plugins), config get, core verify-checksums, db query. db query: SELECT runs immediately (use {prefix} for the table prefix and --limit=N, default 100, max 1000). Mutating SQL (UPDATE/DELETE/INSERT/etc.) is also supported but requires approval and previews the affected-row count first; it is single-statement only and bypasses WordPress hooks, caches, and the owning plugin's business logic (validation, timezone conversion, cache invalidation), so prefer the WP commands above (e.g. post update). Before writing data whose writes should run a plugin's own code, whether in its custom tables ({prefix}edd_* etc.) or in core tables (a plugin's CPTs, their meta, its options), call discover_abilities first: if the plugin exposes a matching ability, run_ability is the correct write path because it runs that logic. Reach for raw mutating SQL only when no WP command and no ability fits, such as unmanaged plugin tables or bulk cross-table cleanup. Bulk ops: post update, post delete, user delete, plugin uninstall, plugin update, theme delete, and cron event run/delete accept multiple IDs/slugs in one command (e.g. "post delete 12 15 33"); get IDs first with "post list --format=ids". plugin update also takes --all [--exclude=<slugs>] [--dry-run] to update everything with a pending update in one confirmed call (requires plugin 1.9.1+). Approval is gated on irreversibility, not count: reversible ops run freely at any scale (post delete = trash/restorable, post update = keeps a revision), while permanent or security-boundary ops confirm first — post delete --force, user delete, term delete, plugin uninstall, theme delete, option delete (except wpvibe_task_* temp options and transients), mutating db query, live search-replace, role & capability edits, user password/email/admin-role changes, and cron event run/delete. When such an op names several targets the approval screen enumerates them and offers a session bypass for repeated ops. All output is JSON. Two confirmation shapes: (1) plugin/theme install and update return requires_confirmation — retry the same command with confirm_write=true after the user agrees; (2) irreversible ops return a browser approval link — the user approves there, and confirm_write does not bypass it. search-replace --dry-run is a free read and needs no approval. Reference: https://developer.wordpress.org/cli/commands/

run_wp_cli

Search file contents across the draft theme (grep-like). Returns matching lines with line numbers and surrounding context. Usage: - Pattern is a substring match (not regex). Use case_sensitive: false (default) for broader matches. - Results show 1 line of context above and below each match for orientation. - Use max_results to limit output when pattern is broad. - For finding files by name/path, use list_files with a glob pattern instead.

search_files

Search Unsplash for high-quality stock photos. Returns hotlinkable image URLs with photographer attribution. Usage: - Use descriptive, specific queries for better results (e.g., "modern office workspace" not just "office"). - Images are hotlinked from Unsplash — use upload_media to add them permanently to the WordPress media library. - Photographer attribution accompanies every displayed image (Unsplash's licence terms).

search_images

THE tool for updating plugins, themes, or WordPress core across one or many connected sites, AND for large bulk deletions (more than ~25 users, posts, or comments) that would time out inline, AND for clearing all spam, trashed, or pending comments on one or many sites: it starts a background fleet job that runs server-side after this call returns (nothing blocks the chat). Strongly prefer this over looping run_wp_cli plugin/theme update per site, and over a single huge run_wp_cli user/post/comment delete - the job chunks the work, survives the relay timeout, and survives the conversation ending. Each site is processed one step at a time with a dry-run recheck before every update, a version verification after it, and per-site halt on failure so one broken site never stops the rest. Comment cleanup: {"kind":"bulk_cli","family":"comment_delete","status":"spam"} deletes every spam comment on each listed site (the job counts them itself with comment count, deletes oldest first, and shows the per-site count on the approval page); no ids needed, works across many sites in one job. Do not enumerate spam ids with comment list for this. Long mechanical write lists (meta updates, term assignments, option writes, flag-only post updates, product field updates; anything you have already fully authored): {"kind":"command_list","commands":["post meta update 12 _yoast_wpseo_title \"...\"", "..."]} runs them server-side one call each, survives the daily-cap pause and the conversation ending, and returns per-command receipts with the failed commands listed so you can retry those inline. One site per job, up to 2000 commands. Approval-gated commands (deletes with --force, mutating SQL, live search-replace, role changes) fail individually with needs_approval; run those inline instead, and never put five or more of them in a row: after 5 consecutive gated commands the rest of the list is skipped unrun. The same happens after 5 consecutive commands failing with the same error (including protected-meta refusals for different keys): fix the shape, then re-run the remainder. Lists also stop after 10 consecutive unsuccessful commands or 15 unsuccessful commands among the last 20 completed commands. Completed changes and receipts are preserved; review failures and verify unknown outcomes before submitting the remaining work as a new job. Not for authoring content one post at a time: write the content first, then list the commands. Two-phase: call once to get the plan + estimated call cost (each background step spends from the account's normal daily call allowance), then repeat with confirm=true to start. Jobs containing core_update steps pause for a browser approval before touching core; the job's status URL is where the user approves. Poll progress with check_approval_status({ op_id: "<fleet job id starting with fj_>" }), and the returned status URL belongs in the user-visible reply: it is the live progress page and works on every client. Sites already covered by an active fleet job are refused (per-site lock). Steps default to everything with an available update; pass explicit target slugs to update only those.

start_fleet_job

Upload an image from a URL to the WordPress media library. Downloads the image server-side and adds it as a media attachment. Usage: - Use this after search_images to permanently add images to WordPress (hotlinks may break). - Returns the attachment ID and local URL for use in posts, pages, or theme templates. - Set alt_text for accessibility — it's used in the img alt attribute. - post_id sets the image as that post's featured image, works for any post type, and is verified before this tool reports success. It replaces whatever featured image the post had. Omit it for gallery or in-content images: passing the same post_id across several uploads leaves only the last one featured. - If the source URL refuses the download (403, 404, 429, hotlink protection), use request_upload so the user uploads the file from their device. If the host itself blocks or caps outbound downloads, use the original image URL temporarily or ask the user to upload the image in wp-admin.

upload_media

Call any WordPress REST API endpoint on a connected site. Supports GET, POST, PUT, and DELETE. For GET list endpoints, content is excluded by default to save context. Set fields="all" to get the full response, or fields="id,title,content" to pick specific fields. TIP: If unsure which endpoints exist, first GET / to see available namespaces, then GET /wp/v2/types to see registered post types. Safety: DELETE always moves to trash (force=true is stripped). New posts/pages default to draft unless status is explicitly set. WooCommerce product and variation updates (PUT /wc/v3/products/{id}, variations, and batch update[] items) replace the whole attributes, categories, tags and images lists with whatever you send, so GET the product first and send the full list with your change merged in; a body that would drop existing entries is refused unless it carries "wpvibe_replace": true. Reference: https://developer.wordpress.org/rest-api/reference/ EDITING LARGE TEXT FIELDS: do NOT GET the whole field, edit it in your context, and PUT it all back; that round-trips the entire value through the conversation twice. Patch it server-side instead. POST /wpvibe/v1/content/edit with body {"target_type":"post"|"meta"|"option", ...locator, "old_content":"<exact snippet>","new_content":"<replacement>"}. The plugin runs a match-once str_replace and the value never enters your context. Locators. Post body: {"target_type":"post","post_id":123,"field":"post_content"} (or post_excerpt/post_title). Meta: {"target_type":"meta","post_id":123,"meta_key":"_key"}. Option: {"target_type":"option","option_name":"name"}. PAGE-BUILDER CONTENT: where a builder stores a page dictates the edit path. Elementor: visible text lives in postmeta _elementor_data (a JSON blob), not post_content — the meta locator works on it ({"target_type":"meta","post_id":123,"meta_key":"_elementor_data"}): Elementor authorizes its own keys for anyone who can edit the post, and on WPVibe plugin 1.17.3+ an Administrator account can read and edit any protected (underscore-prefixed) key this way. A meta_forbidden on an Administrator connection means the site runs an older plugin (update it) or the owning plugin refused the key through its auth callback (use that plugin's own write path); neither is a reason for raw SQL. Divi: layouts live in post_content (Divi 4 shortcodes or Divi 5 wp:divi/* blocks) — use the post locator for text edits; write NEW Divi content as Divi 4 shortcodes, never hand-authored wp:divi/* block JSON (Divi 5 converts shortcodes itself). Beaver Builder, Bricks, Breakdance: serialized/enveloped data with their own save routes (/wpvibe/v1/<builder>/save-page) — load that builder's skill; generic edits corrupt them. Search first: content/search snippets arrive correctly JSON-escaped, paste them verbatim as old_content and keep new_content escaped the same way (\" for quotes, \/ for slashes) or the layout will corrupt. Builder content edited via run_wp_cli db query REPLACE or search-replace bypasses the builder's validation and every SQL statement needs a separate user approval; content/edit needs none. To find the exact old_content without reading the whole field, POST /wpvibe/v1/content/search with the same locator + {"pattern":"..."}; it returns only matching snippets. Snippets are prefixes cut at 400 chars (context lines at 200): paste them VERBATIM as old_content; never extend one from memory or stitch old_content from context lines. Search matches byte-literally (no curly-quote leniency), so a zero-result search may just mean quote-style mismatch: retry with a shorter fragment avoiding quotes/apostrophes. By default old_content must match exactly once (match-once safety). To change a string that appears many times, do NOT fall back to a full GET+PUT rewrite: add "replace_all":true to swap every occurrence in one call (the response reports how many were replaced), and add "whole_word":true to avoid substring hits (e.g. replace_all "blue" without touching "bluer"). On multiple_matches you therefore have two options: add surrounding context to target one, or set replace_all=true. On no_match, search again and paste a snippet verbatim; do not rebuild the text from memory or from rendered HTML. Requires the content_edit feature flag in site_info; if absent (older plugin) or the route returns rest_no_route, fall back to GET+edit+PUT and tell the user to update the WPVibe plugin. Serialized PHP values are refused; JSON and plain text are fine.

rest_api

Create a new file or fully overwrite an existing file in the draft theme. For surgical edits to existing files, use edit_file instead — it is more token-efficient and less error-prone. Usage: - Allowed extensions: .php, .css, .js, .json, .html, .txt, .svg - SVG files are sanitized before saving (scripts, event handlers, external references and embedded HTML are removed, and the response says what was removed). An SVG that cannot be cleaned is refused; use PNG or WebP via upload_media instead. - PHP files are syntax-checked before saving — if syntax is invalid the write is rejected. - Overwriting an existing file replaces its whole content, so a read_file of the current content comes first; edit_file is the smaller change for small edits.

write_file