ENDE
Back to home

WPAgently documentation

Run your first workflows safely

Start with a small draft. This lets you confirm that the connection, Editor role, and verification layer work together.

Step 5: smoke test (about 6 minutes)

Now the big moment: we run one full check to see whether everything works together. "Smoke test" is just a common term for "switch it on briefly and see if it smokes," in other words a quick sanity check.

First, run the all-around check:

wp-agent doctor

The command performs seven checks: reachability, authentication, bot role, license, central Companion control, core abilities, and MCP. The connection is ready only when all seven report OK. If a prerequisite fails, wp-agent doctor marks dependent checks as not run. An unreachable control endpoint can therefore never appear green as an empty but supposedly complete ability or MCP list.

For a targeted individual check, wp-agent preflight (bot role only) and wp-agent abilities (ability list only, each marked readonly [R] = read-only or write [W]) are also available.

Finally, you create a first test draft from a tiny text file. Create it, for example, with printf (a command that simply writes text into a file):

printf '## Smoke test\n\nA paragraph with **bold** text and a list:\n\n- one\n- two\n' > test.md

Generate the test article from it:

wp-agent article --markdown-file test.md --title "Smoke Test" --slug smoke-test

The result must report freeform: 0 in English CLI output. If you kept the default German CLI output, the same marker appears as Freiform: 0, with Freiform=0 in the render line. This means the formatting was cleanly converted into real WordPress blocks and nothing ended up in the old, broken editor view. The post automatically stays a draft, so you won't accidentally publish anything.

This smoke test deliberately produces a minimal article. A complete first post with a featured image and a subsequent SEO read is created via the wp-article skill (Claude Code) or the matching flags (--image, --alt, --seo-title, --seo-description, see wp-agent article --help). With Companion 0.4.30 or newer, the article pipeline automatically streams local featured images through the short-lived direct upload. With older Companion versions, it keeps using the previous Core REST upload as a compatible fallback. Public image URLs are downloaded after every redirect target has passed the SSRF checks again. Rank Math, Yoast, AIOSEO, or SEOPress must be active for SEO fields. set-seo-meta validates the input, reads the state freshly, and currently returns HTTP 409 with manual_only across providers before any mutation. Make desired changes in the SEO plugin manually and read them again through get-seo-meta.

The article and landing pipelines also require the flat remote_create and manual_only_update write semantics from tools/list, together with the general manual_only annotation. Companion versions that do not provide these metadata fields are not treated as compatible for combined pipelines: the CLI fails closed before the first remote mutation because it cannot safely detect a later manual-only 409 writer. This affects existing Markdown updates as well as SEO and status steps. Individual Abilities remain usable according to the schema installed with them. For pipelines, the CLI and Companion must therefore come from a semantically compatible release line.

Done when: wp-agent doctor reports OK seven times and the test article lands as a draft with freeform: 0 or Freiform: 0 in your WordPress. A --publish invocation currently does not change status automatically because set-post-status fails closed with manual_only. Publish or change status manually in WordPress after review. From here on, the connection is up.

Diagnostics

You can also run an external connection diagnosis under WPAgently > Connect agent. Without sending credentials, WordPress requests its public REST API, MCP endpoint, and OAuth metadata through the normal website address. This reveals many CDN, firewall, and security-plugin blocks that a purely internal check cannot see. Detected intermediaries and known active security plugins are shown as hints, not automatically blamed as the cause. If a connection that was used successfully later loses authentication, WPAgently also warns administrators and links directly to this diagnosis.

The seven checks of wp-agent doctor (see step 5) in detail. The command runs through them in order and reports OK or ERROR per check with a plain-text hint. If one comes back red, here's the cause:

  1. Reachability: is the site reachable at WP_AGENT_SITE, and does the technical interface at /wp-json respond with the expected data (JSON)? Most common beginner mistake: with "Plain" permalinks, /wp-json/ returns the homepage as HTML instead of the expected data. This check detects that and gives you a permalink hint instead of falsely showing green. Fix: enable pretty permalinks (Settings > Permalinks).
  2. Auth: does the stored OAuth grant sign in the selected Editor correctly? The CLI refreshes a token before it expires. A failure usually means the server grant was revoked. Run wp-agent logout --site "$WP_AGENT_SITE" --force, then wp-agent login --site "$WP_AGENT_SITE". With the password fallback, check the username and Application Password instead.
  3. Bot role: does the bot carry the Editor role and not Administrator? This is the same check as wp-agent preflight; admin rights are a hard stop, and that's deliberate.
  4. License: is the local license proof valid and within the permitted offline grace period?
  5. Control: are the master switch, domain lock, and ability profile valid, with no failed server-side diagnostics?
  6. Abilities: are all abilities enabled by the control center registered? If any are missing, inspect the profile and master switch under WPAgently > Overview.
  7. MCP: does the server at <site>/wp-json/wp-agent/mcp respond cleanly, and does tools/list contain the tools for every ability enabled by the control center? If the server is missing despite the plugin being active, the plugin was shipped incompletely and needs to be rebuilt.

For a targeted individual check, wp-agent preflight (check 3) and wp-agent abilities (check 6) repeat the same aspect in isolation. wp-agent login establishes CLI access but is not one of the seven Doctor checks. wp-agent init also tests nothing. It only writes optional static connection files (see step 4).

The overall architecture is described in the architecture documentation.