Skip to main content

WordPress

The wordpress skill reads, writes and administers WordPress sites over the core REST API. It works against an ordinary install and an ordinary account: nothing has to be installed on the site. It covers posts, pages and custom post types (discovered at runtime, including types outside wp/v2), ACF or Secure Custom Fields values, terms, media, users, site settings, plugins, any other REST route, and the Abilities API on WordPress 6.9 and later. An optional companion plugin adds ACF options pages and a multisite network's site list. One user can have several installs, and several sites of one multisite network.

The skill is a menu skill with a CLI (istota-skill wordpress). The model reads its instructions when a request needs it.

What the operator sets​

Nothing is required. Two optional settings in config.toml:

[wordpress]
max_upload_mb = 25 # largest file one media upload may send

[private_hosts]
"dev.example.internal" = ["wordpress"] # a host allowed to resolve to a private or loopback address

The skill runs host-side, in the daemon's network namespace, so every site address is checked before anything is sent. A host that resolves to a private, loopback or reserved address is refused unless [private_hosts] grants it to wordpress. That covers a local development site and a backend on the internal network, including a public name that internal DNS answers with a private address from the istota host. It is never a general switch. The table is operator-only, since it is the rule that stops a user-chosen URL from reaching the daemon's own network.

Each entry is a bare host name or IP address, compared exactly (case and a trailing dot aside) with the host in the site's URL: no scheme, port, path or wildcard. The config loader logs a warning for an entry that is not, since it would lift the refusal for no site. If the host is already in the table for another consumer, add "wordpress" to its existing list: a second line for the same host is a TOML error. An internationalised domain is written in its ASCII (punycode) form, in the entry and in the site's URL alike.

Both are ordinary config.toml keys. On an install managed by a config manager, set them in its plan rather than in the file, which the next istota apply rewrites.

istota_security_network_extra_hosts is not the setting for this. It is the sandbox's egress allowlist, which the skill never passes through, so listing the WordPress host there reaches nothing the skill uses and opens a route from the model's own shell.

TLS uses the system trust store. For a site with a locally signed certificate, point SSL_CERT_FILE in the daemon's environment at a bundle that carries the local CA.

What each user sets​

One vault entry per install, in the user's credential vault (see Credentials), under the istota group. Nothing else: there is no site file.

The entry's name is wordpress_ followed by the site's name, which is what --site takes: an entry wordpress_blog is --site blog. A user with one such entry never needs --site; with several, every call names one. Site names are lowercase letters, digits and underscores, starting with a letter.

Vault fieldHolds
URLthe site's HTTPS address, such as https://blog.example.com, with a path if WordPress lives in a subdirectory
Usernamethe WordPress login
Passwordan application password, made in wp-admin under Users, Profile, Application Passwords

The URL field also binds the entry to its host. The skill sends the password only to a host the entry is bound to, so a site name or --blog the model chooses cannot send it anywhere else. On a subdomain multisite network, list each subsite host in the entry's istota_hosts attribute.

The site's entry counts once against the task's vault budget ([security] vault_fetch_limit_per_task), however many calls read it. The vault's own rules apply: it is withheld on a guest's turn and on a task nobody asked in a shared room, and with the credential broker on, a scheduled job needs its grant's scheduled use switched on.

istota-skill wordpress sites lists the wordpress_* entries by site name, without reading a password or making a request.

Asking before anything public​

The model reads text it did not write: other authors' posts, plugin output, the site's error messages. Any of it can carry instructions. So every action that is public or hard to undo refuses without --confirmed, and the answer carries a would line saying exactly what would happen, for example would publish "Weekly update" (post #42) on blog. The model shows that line to the user and passes --confirmed only after the user agrees in the conversation.

Gated:

  • publishing, scheduling, or making a post private, and any edit to a post that is already live;
  • deleting a post for good (moving it to the trash is not gated);
  • creating terms;
  • creating or updating users, changing site settings, and activating, deactivating or installing plugins;
  • any rest call that is not a GET, and running an ability the site does not mark read-only;
  • writing an ACF options page;
  • a fields edit on any post that is not a draft or pending (a live post, or a media item), on an options page, on a post another user has open in the editor, and any fields edit that loses rows, a draft included, since no revision keeps a copy of them: a removed row, or a set after which a repeater or flexible content list holds fewer rows (the would line names the list and the count, blocks/0/items: 4 rows → 1).

Drafts, pending posts and media uploads are not gated, and neither is a fields edit on a draft that loses no rows.

How writes behave​

  • A create, an upload, a user create, a plugin install, a rest call and an ability run are sent once. If the connection drops or the site fails partway, the answer is outcome_unknown, with a lookup command where there is one. Nothing is resent blind.
  • Every post write is read back, and the answer names any field WordPress dropped or changed, such as unregistered meta, markup filtered for an account without unfiltered_html, or a slug that gained -2. Settings writes report a setting the site ignored the same way.
  • update --acf-* and options update write ACF fields whole, in the shape get returns. fields edit changes one row, one sub-field or one list position instead (next section). Anywhere in an ACF value, {"$upload": PATH} uploads a file from the user's own workspace and puts its attachment id there. All uploads happen before the post is written.
  • users create sets no password anybody knows, and WordPress sends no email. The new user signs in after using "Lost your password?" on the login page.
  • Every string the site wrote comes back inside untrusted-content markers.

Multisite​

A network is one vault entry and one credential; a super admin's application password works on every site. --blog SLUG (subdirectory network) or --blog HOST (subdomain network) addresses one site. The skill checks that the site exists before acting on it, so a typo answers unknown_blog rather than acting on the main site.

plugins activate --network asks core REST to network-activate a plugin. If the site refuses, including because it is not a network, the answer is unsupported_on_multisite and the plugin is not activated per site instead; network-activate it in the network admin.

The istota-connector plugin​

Core REST has no route for an ACF options page and none for listing a multisite network's sites, and its ACF write path refuses its own read output in common cases (a field required only under a condition, an empty image read back as false). A small companion plugin fills these gaps. It is optional: everything else works without it, and the verbs that need it answer connector_missing with a pointer here. A site with a plugin older than 0.2.0 answers connector_outdated for the two field verbs; build and upload the zip again.

VerbAbilityNeeds
options get --page SLUGistota/options-getmanage_options, and the options page's own capability
options update --page SLUG --acf-file F --confirmedistota/options-updatethe same
network sitesistota/network-sitesmanage_sites on the main site (a super admin)
fields get (--id N | --page SLUG) [--path P]istota/fields-getedit_post on the post, or the options page rule above
fields edit (--id N | --page SLUG) --token T [ops]istota/fields-editthe same

The plugin registers these as abilities with the WordPress Abilities API, so it needs WordPress 6.9 or later. It adds no REST routes of its own, has no settings and stores nothing. Only fields in a field group with "Show in REST API" switched on can be read or written, the same rule ACF applies to posts. options update replaces each named field's value whole and leaves the others alone. Write image and file fields as attachment ids.

Editing inside a field​

fields get lists a post's or options page's fields with a token each; with --path (blocks/0/items) it returns the value there and the field definition: names, types, choices, which sub-fields are required, and for a flexible content field its layouts. Values come back in one shape the edit accepts unchanged: field names as keys, every defined sub-field present, attachment and post ids rather than objects, null for nothing stored.

fields edit applies --set, --insert, --remove and --move operations, in the order given, to one top-level field, and sends only what changes. Fields and rows it does not name are not sent and cannot be damaged. It needs the token from fields get: when someone has saved the field since, the edit is refused with stale_value and nothing is written, so an index from an old read never lands on the wrong row. A successful edit gives a new token. Only the values the edit writes are validated, so a field elsewhere on the page that is required only under a condition does not block it. A required sub-field left empty is reported in missing_required; the editor asks for it on the next manual save. Flexible content rows keep their disabled flag and custom label through every operation. A custom label is text an editor typed, so it comes back inside the markers like any other.

Text copied from a fields get answer, untrusted-content markers included, is written without the markers. A value that still holds a marker, or the text a marker was replaced with, is refused rather than written. update --acf-* and options update apply the same rule.

The source is integrations/wordpress/istota-connector/ in the istota repository. To install it:

  1. Build the zip from a checkout:

    scripts/build-wordpress-connector.sh

    This writes dist/istota-connector-<version>.zip from the committed files at HEAD. Pass another git ref as the first argument to build that one instead. Uncommitted edits are not included.

  2. In wp-admin, go to Plugins, Add New, Upload Plugin, and upload the zip. On a single site, activate it. On a multisite network, upload it in the network admin and network-activate it, so every site has the options abilities.

  3. Check it with istota-skill wordpress describe --refresh, which should report connector: true, and list istota/fields-get and istota/fields-edit under connector_abilities from version 0.2.0.

To update the plugin, build a new zip and upload it again; WordPress offers to replace the installed copy.

Not offered​

Core updates, creating network sites, network users and super admins, search-replace, database import and export, and editing field group or post type definitions all need WP-CLI or wp-admin. Secure Custom Fields registers abilities that create, update, delete and import those definitions; abilities run refuses every scf/* and acf/* ability that is not read-only, with definition_edit_refused, whatever --confirmed says. Its read abilities still run. Deleting users and plugins, and anything to do with application passwords, are left to wp-admin too.

Testing against a live site​

tests/test_wordpress_integration.py is a smoke test against a real site, marked integration and skipped unless ISTOTA_WP_TEST_URL, ISTOTA_WP_TEST_USER and ISTOTA_WP_TEST_APP_PASSWORD are set. It writes, so point it at a local development copy, never at production, and revoke the application password afterwards. The module docstring lists the optional variables.

uv run pytest -m integration tests/test_wordpress_integration.py -n0 -v