ENDE
Back to home

WPAgently documentation

Run your first workflows safely

Use this short test to check the connection and draft creation. The commands require the Paid CLI to be set up first. With Free, use the chat tasks in Getting started.

Step 5: smoke test (about 6 minutes)

This CLI smoke test belongs to Paid. With Free, run the read-only check and small test draft from the quickstart directly in your assistant instead.

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.

You can also run an external connection diagnosis under WPAgently > Connect agent. Without sending credentials, WordPress checks the normal public path through your website address. This can reveal a block by a CDN, firewall, or security plugin that an internal check cannot see. The page shows hints rather than guessing at a cause.

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 creates only a small article. Later, you can use the included wp-article skill for a complete post with an image. For SEO, you need Rank Math, Yoast, AIOSEO, or SEOPress. WPAgently checks SEO details but deliberately does not save them itself: set-seo-meta returns HTTP 409 with manual_only before any provider mutation. Make SEO changes in the SEO plugin, then read the result again with get-seo-meta.

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

wp-agent doctor shows a clear hint for every check. If one fails, solve that exact hint first. This overview helps you understand what each check asks:

  1. Reachability: Is your website reachable? Check the permalinks first. On a new site that is not yet public, you can select “Post name” under Settings > Permalinks and save. If your website is already public, do not change its permalink structure without a redirect plan. Ask the person responsible for your website or your hosting provider for help.
  2. Sign-in: Can the stored connection sign in as your Editor? If access was revoked, run wp-agent logout --site "$WP_AGENT_SITE" --force, then wp-agent login --site "$WP_AGENT_SITE".
  3. Bot role: Does the bot have the Editor role rather than Administrator? Administrator rights are deliberately a hard stop.
  4. Licence: Is your licence valid?
  5. Control: Is WPAgently correctly activated on this website?
  6. Abilities: are all abilities enabled by the control center registered? If any are missing, check the feature profile and Companion switch in the WPAgently control center.
  7. Connection: Are your assistant's tools reachable? If this fails while the plugin is active, run the external connection diagnosis under WPAgently > Connect agent and check its hints about a firewall, CDN, or security plugin.

For an individual check, use wp-agent preflight for the bot role and wp-agent abilities for the tool list. wp-agent login connects the CLI. wp-agent init writes connection files or registers Claude Code or Codex with --scope user --i-approve. It does not replace sign-in or the connection check with doctor.

The overall architecture is described in the architecture documentation.