Pro module60 abilities
Etch
These abilities register when Etch is detected on the site and a Pro licence is active. If either is missing the module stays absent rather than failing at call time.
At a glance
Etch registers 60 abilities: 23 that only read, 21 that write, and 16 marked destructive. That split is the practical answer to how much of this module can run unattended. Reads cost nothing and are safe to repeat, so discovery is the part to be generous with; the writes are where review belongs, and the destructive calls stop for an explicit confirmation every single time regardless of which profile is active.
What this module is for
Coordinate Etch nodes, components, templates, stylesheets, utility styles, fields, post types, loops, queries, and dynamic content from a typed agent workflow.
Before you rely on it: Sequence data-model changes before templates, and validate queries against real staging content.
Typical workflows
- Model a content type and its fields before building the template
- Preview a query before wiring it into a loop
- Create reusable components and styles without duplicating page markup
The Etch integration page covers the same module from the workflow side, with the capability map and the questions worth asking before a first write.
Availability on your site
The Etch module needs three things at once: WPPilot Free as the MCP foundation, an active Pro licence, and the companion plugin detected on the site. Miss any one and the module does not register, which is deliberate: an ability that appears in the tool list but fails at call time is worse than an ability that was never offered. What the connected agent can actually call is then narrowed twice more: by the safety profile active on the site, and by the WordPress capabilities of the user behind the credential. A read that succeeds for an administrator can be absent entirely for an editor.
Every write these abilities perform is recorded in the change ledger, and destructive calls can be routed through the approval queue so a person signs off before anything is applied. A successful tool result means the operation returned, not that the front end, the cache, and every dependent template are correct: that still needs a look.
Reads
Available in every safety profile, including Read Only. Inspection costs nothing and is not rate limited.
| Ability | What it does |
|---|---|
wppilot/etch-check-setupCheck Etch Setup | Reports the Etch environment status: active/inactive, version, PHP compatibility (Etch requires PHP 8.1+), license activation status, the Etch-managed custom post types, and counts of stored Etch libraries (components, global stylesheets, styles, loops, queries, taxonomies). Etch is an HTML-first builder that stores page content as Gutenberg block markup (etch/* blocks) in post_content and its global libraries in wp_options. Run this first to diagnose builder availability. |
wppilot/etch-get-componentGet Etch Component | Returns one Etch component in full: id, name, key, description, properties (its declared props), and tree (the component's element tree in the compact etch/* node format). The tree is read like wppilot/etch-get-content, including the lossy/warnings honesty signal. |
wppilot/etch-get-contentGet Etch Content | Returns the Etch element tree for a post or template, parsed from its block markup (post_content). Each node is { block, attrs?, children?, html? } where block is the Gutenberg block name (e.g. "etch/element", "etch/text", "etch/component"), attrs is the block's attributes (e.g. tag, attributes, styles for etch/element; content for etch/text; ref for etch/component), children is the nested node list, and html holds the inner HTML of leaf blocks that store content outside attrs (core blocks, raw HTML). A node with an empty block string ("") is freeform HTML carried in html. Pure-whitespace between blocks is omitted. Use wppilot/etch-list-elements to learn the block vocabulary, and wppilot/etch-set-content to write a tree back. |
wppilot/etch-get-field-groupGet Etch Field Group | Returns one Etch custom field group in full: { id, label, assigned_to (post_types / post_ids), fields }. Each field is { key, label, type, required?, default? }. |
wppilot/etch-get-field-valuesGet Etch Field Values | Reads the values of the Etch custom fields applied to a post (the per-post data behind {etch.<key>} bindings). Returns a compact list of { key, label, type, group_id, value } for every field whose group is assigned to the post; pass keys to restrict it. Requires Etch 1.5.0+. Use wppilot/etch-get-field-group for the field definitions, this for their stored values. |
wppilot/etch-get-loopGet Etch Loop | Returns one Etch loop in full: id, name, key, global, and config (the query definition { type, args }). |
wppilot/etch-get-post-typeGet Etch Post Type | Returns one Etch custom post type in full: slug and args (the register_post_type configuration, e.g. label, public, show_in_rest, supports, has_archive). |
wppilot/etch-get-queryGet Etch Query | Returns one saved Etch query in full by its key: { key, query } where query is the stored definition object. Use wppilot/etch-list-queries to discover the keys. |
wppilot/etch-get-query-previewPreview Etch Query Results | Runs a source query through Etch's resolver and returns a small sample of real items with their resolved dynamic data, so you can see actual values (not just field names). source is "post" (pick post_type), "term" (give a taxonomy), or "user"; limit caps the items (default 5, max 10). Each item is a flattened { path: value } map of its dynamic fields (values truncated). Pair with wppilot/etch-list-dynamic-fields, which returns the field catalogue without the data. |
wppilot/etch-get-stylesGet Etch Styles | Reads the Etch styles layer (the etch_styles option) — the per-element/class CSS Etch manages. Returns a compact entry per style { id, collection, selector, type, readonly, css_bytes } (the selector identifies the rule; css_bytes is its CSS size, not inlined to keep the response bounded). readonly:true marks Etch built-ins. Author records with wppilot/etch-create-style, wppilot/etch-edit-style and wppilot/etch-delete-style. |
wppilot/etch-get-stylesheetGet Etch Stylesheet | Returns one Etch global stylesheet in full: id, name, css, type. |
wppilot/etch-get-taxonomyGet Etch Taxonomy | Returns one Etch custom taxonomy in full: slug, args (the register_taxonomy configuration), and object_types (the post types it is attached to). |
wppilot/etch-get-templateGet Etch Template | Returns one block template by id: { id, title, slug, theme, status, node_count }. node_count is how many Etch nodes its content currently has. Read the full content tree with wppilot/etch-get-content (same id). |
wppilot/etch-list-componentsList Etch Components | Lists the Etch components (reusable synced patterns stored as wp_block posts). Returns a compact entry per component { id, name, key, description } — fetch the full tree and properties with wppilot/etch-get-component. |
wppilot/etch-list-dynamic-fieldsList Etch Dynamic Fields | Discovers the dynamic data fields available for a source — the {...} expression paths you can bind in etch/dynamic-element, etch/dynamic-image, and loop children. Samples a few real items and returns a compact catalogue of dot-paths with their type and a truncated sample value (e.g. "title", "permalink", "meta.subtitle", "etch.author_bio", "featured_image.url"). source is "post" (default; pick the post_type), "term" (give a taxonomy), or "user". Resolution reuses Etch's own engine, so it includes Etch custom fields and any ACF / JetEngine / Meta Box bridges. Use this before building dynamic content so you bind real paths instead of guessing. Output is capped; create some content of the type first if nothing is returned. |
wppilot/etch-list-elementsList Etch Elements | Lists the Etch block vocabulary used to build pages: the block name (e.g. "etch/element"), a short description, whether it can contain children (container vs leaf), and its top-level attributes. Also returns base_attributes — attributes (hidden, script, options) available on EVERY node. Use this to learn what nodes wppilot/etch-get-content returns and what wppilot/etch-set-content accepts. |
wppilot/etch-list-field-groupsList Etch Field Groups | Lists the custom field groups Etch registers (the etch_cfs option). Returns a compact entry per group { id, label, post_types, field_count }. Fetch the full definition (incl. each field) with wppilot/etch-get-field-group. |
wppilot/etch-list-loopsList Etch Loops | Lists the Etch loops (data sources an etch/loop node repeats over, stored in the etch_loops option). Returns a compact entry per loop { id, name, key, global, config_type } — global:true marks an Etch built-in preset. Fetch the full config with wppilot/etch-get-loop. |
wppilot/etch-list-post-typesList Etch Post Types | Lists the custom post types Etch registers (the etch_cpts option). Returns a compact entry per type { slug, label }. Fetch the full register_post_type args with wppilot/etch-get-post-type. |
wppilot/etch-list-queriesList Etch Queries | Lists the saved queries Etch stores in the etch_queries option (reusable data sources). Returns a compact entry per query { key, name, type }. Fetch the full definition with wppilot/etch-get-query. To discover the dynamic fields a query yields, use wppilot/etch-list-dynamic-fields instead. |
wppilot/etch-list-stylesheetsList Etch Stylesheets | Lists the Etch global stylesheets (named CSS sheets such as "Main", stored in the etch_global_stylesheets option). Returns a compact entry per sheet { id, name, type, css_bytes } — fetch the CSS with wppilot/etch-get-stylesheet. |
wppilot/etch-list-taxonomiesList Etch Taxonomies | Lists the custom taxonomies Etch registers (the etch_taxonomies option). Returns a compact entry per taxonomy { slug, label, object_types }. Fetch the full args with wppilot/etch-get-taxonomy. |
wppilot/etch-list-templatesList Etch Templates | Lists the block templates (wp_template posts) on the site. Returns a compact entry per template { id, title, slug, theme, status }. The slug is the template-hierarchy slot it fills (e.g. "single", "archive", "page", "front-page", "404"). Read or write a template's content with wppilot/etch-get-content / wppilot/etch-set-content using its id. |
Writes
Gated by the active profile and your WordPress capabilities. Rate limited to 120 per minute per credential.
| Ability | What it does |
|---|---|
wppilot/etch-add-fieldAdd Etch Field | Adds a field to an existing Etch field group. Requires group_id, key (the post meta key), label, and type (text, textarea, number, boolean — plus date, time, select on Etch 1.5.0+; a select field also needs options: newline-separated choices); optional required and default. Errors if the key already exists in the group. Returns group_id and key. |
wppilot/etch-add-nodeAdd Etch Node | Inserts one node into an existing container in an Etch page, without re-sending the whole tree. parent_address is the index path of the container to insert into ("" / omitted = the page root, e.g. "0/1" = second child of the first top-level node); node is a compact node { block, attrs?, children?, html? } (same shape as set-content); position is the 0-based index among the parent's children (omitted = append). Addresses match the tree wppilot/etch-get-content returns. Re-serializes the page; refuses a lossy page unless force:true. |
wppilot/etch-create-componentCreate Etch Component | Creates a new Etch component (a published wp_block). Accepts name (required), tree (the component's element tree in the compact etch/* node format, same as etch-set-content), description, properties (an object of declared props), and key (auto-generated if omitted). Returns the new component id, name, and key. Reference it from a page via an etch/component node with attrs.ref = the returned id. |
wppilot/etch-create-field-groupCreate Etch Field Group | Creates a new Etch custom field group. Requires label and assigned_to ({ post_types: [slugs] } and/or { post_ids: [ids] }); fields is an optional initial list of { key, label, type } (type is text, textarea, number, boolean — plus date, time, select on Etch 1.5.0+; a select field also needs options: newline-separated choices). Returns the new group id. Add fields later with wppilot/etch-add-field. |
wppilot/etch-create-loopCreate Etch Loop | Creates a new Etch loop. Requires name and config (the query definition, e.g. { "type": "wp-query", "args": { "post_type": "post", "posts_per_page": 10 } }); key defaults to a slug of the name. Returns the new id, name, and key. Reference it from a page via an etch/loop node with attrs.loopId = the returned id. |
wppilot/etch-create-post-typeCreate Etch Post Type | Registers a new Etch custom post type. Requires slug (1-20 lowercase letters/digits/_/-) and label; args are extra register_post_type options (public and show_in_rest default to true). Errors if the slug already exists. Returns slug and label. |
wppilot/etch-create-styleCreate Etch Style | Creates an editable per-class (or per-element) style record in the Etch styles layer (etch_styles) — the records Etch surfaces when you select a class/element in the editor. Provide selector (e.g. ".hero") and css. css is the rule body: declarations PLUS optional nested rules — states (&:hover, &:focus, &:active), breakpoints (@media), and descendant/child selectors — the same things the Etch editor edits per class (Etch renders "selector { css }"). Do NOT repeat the outer selector. e.g. "color: var(--brand); padding: 24px; &:hover { color: white; }". collection defaults to "default"; type is inferred from the selector (class/id/element/attribute). Use this (not a global stylesheet) for component/button/card/text styling you want editable in Etch, and put the same class on elements via attributes.class. For many records in one call use wppilot/etch-create-styles. Returns { id, selector, type, collection }. |
wppilot/etch-create-stylesCreate Etch Styles (batch) | Creates many editable per-class/element style records in one call — the batch form of wppilot/etch-create-style, for a whole-page design (dozens of records) without one call each. Pass styles: an array of { selector, css, collection? } where css is the rule body (declarations plus optional nested rules: &:hover/&:focus/&:active states, @media breakpoints, descendant selectors; do not repeat the selector). Each record is validated independently: a bad or duplicate one is reported in errors[] (with its index) and the rest still succeed. Returns { created: [{ id, selector, type, collection }], errors: [{ index, selector, error }], created_count }. |
wppilot/etch-create-stylesheetCreate Etch Stylesheet | Creates a new Etch global stylesheet. Requires name and css; type defaults to "default" (use "@custom-media" for custom-media definitions). Returns the new id, name, and type. |
wppilot/etch-create-taxonomyCreate Etch Taxonomy | Registers a new Etch custom taxonomy. Requires slug (1-20 lowercase letters/digits/_/-), label, and object_types (the post type slugs it attaches to). Etch maps taxonomy args through a camelCase allowlist, so any extra args must use camelCase keys (hierarchical, showUi, showInMenu, showInNavMenus, showInRest, showInQuickEdit, showInAdminColumn, description, capabilities) and labels via labels.pluralName / labels.singularName; public and show_in_rest default to true. Errors if the slug already exists. Returns slug and label. |
wppilot/etch-create-templateCreate Etch Template | Creates a new block template (wp_template post). Requires title and slug (the template-hierarchy slot, e.g. "single", "archive", "page", "front-page", "404", "page-about"); theme defaults to the active theme. Optionally pass tree to set the initial content (same node format as wppilot/etch-set-content). Returns the new id and slug. |
wppilot/etch-duplicate-componentDuplicate Etch Component | Clones an existing Etch component (a wp_block) in one call: copies its element tree, description and declared properties verbatim under a fresh, unique html key, so the copy is a faithful starting point you can then edit. Pass component_id (required) and an optional name (defaults to "<source> (copy)"). Returns the new component id, name, and key. |
wppilot/etch-duplicate-templateDuplicate Etch Template | Clones an existing template (a wp_template) in one call: copies its block content verbatim and re-attaches it to the same theme, under a new unique slug. Pass template_id (required), an optional name (defaults to "<source> (copy)") and an optional slug (auto-generated from the source slug if omitted). Returns the new template id, title, and slug. |
wppilot/etch-edit-fieldEdit Etch Field | Edits a field within a group (partial). Provide group_id, field_key (the current key), and any of label, type, required, default, or key (to rename — changes the post meta key). Returns group_id and key (the resulting key). |
wppilot/etch-edit-field-groupEdit Etch Field Group | Edits a field group's label and/or assigned_to (partial). Provide group_id and any of label or assigned_to (assigned_to replaces the whole assignment). To change the fields use wppilot/etch-add-field / etch-edit-field / etch-delete-field. Returns id and label. |
wppilot/etch-edit-nodeEdit Etch Node | Edits one node in place at its index address (e.g. "0/1/2"), without re-sending the whole tree. Partial-merge: attrs (if given) is merged over the node's existing attrs — top-level keys shallow-merge (pass a key as null to drop it), while the HTML attributes sub-object deep-merges so attributes you do not resend (notably class) are kept; set a nested attribute to null to remove just that one. html (if given) replaces a leaf node's html; block (if given) changes the block type. Children are left untouched. Addresses match wppilot/etch-get-content. Re-serializes the page; refuses a lossy page unless force:true. Adding a class that has a per-class Etch style record auto-binds the record's id into the node's styles, so the class stays editable in Etch. |
wppilot/etch-edit-post-typeEdit Etch Post Type | Edits an existing Etch custom post type (partial update of its args). Provide slug and any of label or args (args merge into the stored register_post_type config). Returns slug and label. |
wppilot/etch-edit-taxonomyEdit Etch Taxonomy | Edits an existing Etch custom taxonomy (partial update). Provide slug and any of label, args (merged into the stored config), or object_types (replaces the attached post types). Like create-taxonomy, args use Etch's camelCase allowlist (showInRest, showInAdminColumn, showInMenu, hierarchical, …) with labels via labels.pluralName / labels.singularName — snake_case keys are dropped by Etch's mapper. Returns slug and label. |
wppilot/etch-edit-templateEdit Etch Template | Edits a block template's metadata (partial). Provide template_id and any of title, slug, or theme. To change the template body use wppilot/etch-set-content with the same id. Returns id and slug. |
wppilot/etch-move-nodeMove Etch Node | Moves a node from its current index address to a new parent container, without re-sending the whole tree. new_parent_address is the destination container ("" = root); position is the 0-based index among the destination's children (omitted = append). Both addresses are resolved against the CURRENT tree (as get-content returns it); the source is removed and re-inserted, and the destination index is adjusted for the removal automatically. Cannot move a node into its own subtree. Re-serializes the page; refuses a lossy page unless force:true. |
wppilot/etch-set-field-valuesSet Etch Field Values | Sets the values of Etch custom fields on a post in one call. Provide post_id and values ({ "<field key>": value, ... }). Etch resolves each key against the field groups assigned to the post, validates the value by field type, and writes both the value and the marker meta so {etch.<key>} resolves. A key not in any group assigned to the post is rejected. Requires Etch 1.5.0+. Returns the resulting field list. |
Destructive
Marked destructive in the source, so each call needs an explicit confirmation flag, every time.
| Ability | What it does |
|---|---|
wppilot/etch-delete-componentDelete Etch Component | Permanently deletes an Etch component (wp_block). Pages that reference it via an etch/component node will lose that component. Returns the id and deleted:true. |
wppilot/etch-delete-fieldDelete Etch Field | Removes a field from a group by its key. The field definition is removed; existing post meta values under that key remain in the database. Returns group_id, key, and deleted:true. |
wppilot/etch-delete-field-groupDelete Etch Field Group | Deletes an Etch custom field group by id. The group definition is removed; existing post meta values written for its fields remain in the database. Returns id and deleted:true. |
wppilot/etch-delete-field-valueDelete Etch Field Value | Removes the stored value of one Etch custom field on a post (both the value and the {etch.<key>} marker meta). The field DEFINITION is untouched. Provide post_id and key. Requires Etch 1.5.0+. Returns post_id, key and deleted:true. |
wppilot/etch-delete-loopDelete Etch Loop | Deletes an Etch loop by id. Pages with an etch/loop node referencing it will have nothing to repeat over. NOTE: deleting a built-in preset (global:true) is transient — Etch re-seeds its presets on the next request, so a preset delete does not stick. Returns id and deleted:true. |
wppilot/etch-delete-nodeDelete Etch Node | Removes one node (and its subtree) at its index address (e.g. "0/1/2") without re-sending the whole tree. Addresses match wppilot/etch-get-content. Re-serializes the page; refuses a lossy page unless force:true. |
wppilot/etch-delete-post-typeDelete Etch Post Type | Deletes an Etch custom post type registration by slug. Existing posts of that type remain in the database but the type is no longer registered. Returns slug and deleted:true. |
wppilot/etch-delete-styleDelete Etch Style | Deletes a per-class/element style record from the Etch styles layer by id (from wppilot/etch-get-styles). Etch readonly built-ins cannot be deleted. Returns { id, deleted: true }. |
wppilot/etch-delete-stylesheetDelete Etch Stylesheet | Deletes an Etch global stylesheet by id. Deleting the built-ins is allowed: Etch recreates "custom-media" on the next request, and recreates "default" (Main) only if the whole stylesheet set becomes empty — otherwise "default" stays deleted. Returns id and deleted:true. |
wppilot/etch-delete-taxonomyDelete Etch Taxonomy | Deletes an Etch custom taxonomy registration by slug. Existing terms remain in the database but the taxonomy is no longer registered. Returns slug and deleted:true. |
wppilot/etch-delete-templateDelete Etch Template | Deletes a block template (wp_template post) by id. The site falls back to the theme's template for that slot. Returns id and deleted:true. |
wppilot/etch-edit-componentEdit Etch Component | Edits an existing Etch component in place (partial update). Provide component_id and any of name, tree (replaces the component's element tree), description, properties, key. Returns the component id, name, and key. |
wppilot/etch-edit-loopEdit Etch Loop | Edits an existing Etch loop in place (partial update). Provide loop_id and any of name, key, config. Built-in preset fields (e.g. _preset_hash) are preserved. Returns id, name, and key. |
wppilot/etch-edit-styleEdit Etch Style | Edits an existing per-class/element style record in the Etch styles layer in place (partial update). Provide style_id (from wppilot/etch-get-styles) and any of css (the rule body: declarations plus optional nested rules — states, @media, descendant selectors; do not repeat the selector) or selector. Etch readonly built-ins cannot be edited. Returns { id, selector, type, collection }. |
wppilot/etch-edit-stylesheetEdit Etch Stylesheet | Edits an existing Etch global stylesheet in place (partial update). Provide stylesheet_id and any of name, css, type. Returns the id, name, and type. |
wppilot/etch-set-contentSet Etch Content | Replaces the entire Etch element tree of a post or template with the given tree, serialized to block markup (post_content). The tree is a list of nodes, each { block, attrs?, children?, html? } — the same shape wppilot/etch-get-content returns. block is a "namespace/name" Gutenberg block slug (e.g. "etch/element", "etch/text"); attrs is the block attributes object (keyed, not a list); children is the nested node list (container blocks only); html is the inner HTML for leaf blocks that store content outside attrs. A node with an empty block string ("") plus html is freeform HTML. Safety guard: if the post's current content is lossy (it holds freeform HTML the tree cannot represent, the same condition get-content reports as lossy:true), the write is refused with etch_lossy_overwrite unless you pass force:true. This overwrites all existing content of the post — read it first with wppilot/etch-get-content if you intend to edit rather than replace. Use wppilot/etch-list-elements for the block vocabulary. Style binding is automatic: when an element's attributes.class names a class that has a per-class Etch style record (wppilot/etch-create-style), that record's id is added to the node's styles for you, so the class stays rendered and editable in Etch without setting styles by hand (create the record first; explicit styles are preserved). |