Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

86.0 KB
Raw Blame

CLI API Use Cases

Link/configure one project

Commands:

  • webstudio init --link --json

Notes:

  • Writes local project id and global origin/token config.

Import synced project bundle into another project

Commands:

  • webstudio sync
  • webstudio import --to
  • MCP tool: import {"to":""}

Notes:

  • Imports local .webstudio/data.json into the destination project.
  • Destination share link must allow build/import access.
  • Use --skip-assets only when asset rows and files should not be imported.

Identify current token

Commands:

  • MCP tool: whoami {}

Check token permissions

Commands:

  • webstudio permissions --json

Inspect project/build/version

Commands:

  • MCP tool: inspect {}
  • MCP tool: snapshot {"include":["pages","instances","styles"]}

Discover CLI/API capabilities

Commands:

  • webstudio schema api
  • webstudio schema mcp
  • webstudio man --json
  • webstudio man llm --json
  • MCP tool: meta.index {}
  • MCP tool: meta.guide {"brief":"Create a pricing page"}
  • MCP tool: meta.get-more-tools {"brief":"update-styles"}
  • webstudio mcp list-resources
  • webstudio mcp read-resource webstudio://project/guide
  • webstudio mcp read-resource webstudio://project/expressions

Notes:

  • Use webstudio schema mcp for a compact machine-readable MCP tool overview. Add --verbose or use focused meta.get-more-tools calls only when exact input schemas are needed.
  • Use focused MCP tools for discovery first: meta.index, meta.guide, meta.get-more-tools, components.list, components.summary, components.search, components.get, templates.list, and templates.get. Protocol clients can use resources/list and resources/read; shell agents can use webstudio mcp list-resources and webstudio mcp read-resource <uri>. Read longer resources such as webstudio://project/tools and webstudio://project/components only when focused tools are insufficient.
  • components.summary returns counts by default; request {"detail":"components","limit":20} for paginated entries. Registry list tools return compact metadata, while components.get and templates.get return focused full details.
  • Read webstudio://project/expressions before authoring unfamiliar computed text, prop bindings, resource expressions, actions, or Collection item bindings.
  • From a shell, call one MCP tool with the shortcut form webstudio <tool> '<json>', for example webstudio components.summary. The explicit equivalent is webstudio mcp single-op-call <tool> '<json>'. Use --input-file for large payloads.

Inspect external shadcn registry items

Commands:

Notes:

  • Reads a local or remote registry item without installing files or changing the configured Webstudio project.
  • Returns the item name, description, package and registry dependencies, file paths/targets, available docs, and a read-only compatibility report.
  • The report explicitly says whether installation or editable-component conversion is supported, lists declared requirements and manual steps, and says when arbitrary source code was not analyzed.
  • This is an inspection step only. It does not install files or change the configured project.

Understand what MCP can do

Commands:

  • webstudio man mcp
  • MCP tool: meta.index {}
  • MCP tool: meta.guide {"brief":"What can Webstudio MCP do?"}

MCP lets agents work on one configured Webstudio project. Agents can:

  • Inspect the linked project, token permissions, and latest editable build.
  • Read selected project data for audits, migrations, and repair.
  • Search values and ids across every Builder namespace without sending full project data to the model.
  • Audit accessibility, security, SEO, performance settings, unused assets, ineffective Collection styles, and unused or duplicate style data.
  • Create and edit pages, folders, redirects, breakpoints, and page templates.
  • Create pages from reusable templates.
  • Update page metadata, SEO fields, auth settings, and marketplace metadata.
  • Insert components and styled JSX sections.
  • Create data-driven lists, grids, cards, and similar repeated UI from array or object data in one Collection operation.
  • Move, copy, wrap, unwrap, convert, rename, retag, and delete elements.
  • Update text, rich text, props, bindings, and actions.
  • Create and update local styles, design tokens, style sources, and CSS variables.
  • Create static data variables and JSON variables.
  • Create HTTP, GraphQL, and system resources.
  • Use system resources for sitemap, current date, and assets.
  • Bind resources to rendered data or form/action props.
  • Manage nested asset folders and upload, inspect, move, duplicate, download, replace, delete, and inspect usage for assets.
  • Publish, unpublish, inspect publish jobs, and manage custom domains.
  • Start preview, capture screenshots, compare screenshot diffs, and use OCR when installed.

Inspect and refresh MCP session cache

Commands:

  • MCP tool: status {}
  • MCP tool: status {"verbose":true}
  • MCP tool: refresh {"namespaces":["pages","instances","styles"]}
  • MCP tool: reset-session {}

Notes:

  • Use status before a task to understand the cached ProjectSession state.
  • Use status with {"verbose":true} only when debugging full namespaces, freshness, compatibility, or diagnostics.
  • Use refresh when project data may have changed outside the current MCP session.
  • Use reset-session when local cached state is corrupt or incompatible.

Visually verify rendered work with AI vision

Commands:

  • MCP tool: preview.start {}
  • MCP tool: preview.status {}
  • MCP tool: preview.stop {}
  • MCP tool: screenshot {"path":"/","output":".webstudio/screenshots/home-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}
  • MCP tool: screenshot {"path":"/pricing","output":".webstudio/screenshots/pricing-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}
  • MCP tool: screenshot {"baseUrl":"http://127.0.0.1:5177","path":"/pricing","output":".webstudio/screenshots/pricing-current.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}
  • MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff"}
  • MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff","expectedText":["Pricing","Start free"]}
  • MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/home-before.png","currentPath":".webstudio/screenshots/home-current.png","outputDir":".webstudio/screenshots/diff","expectedVisual":{"maxMismatchPercentage":2,"maxChangedRegions":3,"dominantColorChange":{"channel":"luminance","direction":"increase","minMagnitude":10}}}
  • MCP tool: screenshot.diff {"baselinePath":".webstudio/screenshots/pricing-before.png","currentPath":".webstudio/screenshots/pricing-current.png","outputDir":".webstudio/screenshots/diff"}
  • MCP tool: vision.install-ocr {"confirm":true}

Notes:

  • Enter this workflow only when the user explicitly requests visual verification or opts in after being asked. Do not start preview, screenshots, diffs, OCR, or rendered audits automatically after a mutation.

  • preview.status reports whether generated output is stale. When no preview is running, url, pid, and mode are omitted. When present, renderedProjectVersion is the last project version materialized into the preview.

  • MCP preview and path-based screenshot tools select an available loopback port and return the preview URL. Do not pass host or port.

  • A managed screenshot or another preview.start refreshes stale generated output before capture.

  • After opt-in, use this so a vision-capable AI can see the generated site from the current MCP session. Use path; never pass a Webstudio Builder/share URL or capture Builder chrome.

  • For multi-page work, capture every changed page by path through the same preview server; no click navigation is required.

  • Iterative mode is the default: after MCP mutations, path screenshots ensure generated project files are current, wait for the exact session version, and perform an ordinary page reload without Vite HMR. The preview server and browser stay alive. Use {"mode":"production"} only for release-like verification; rendered audit does this automatically.

  • Calling preview.start after a committed mutation restarts a stale iterative server so external browsers and HTTP clients receive the newly generated project.

  • Do not call preview.start through one-shot webstudio mcp single-op-call: it is long-lived. From a shell, use webstudio mcp run with preview.start, screenshot, and preview.stop in one shared process, or use a real long-running MCP client.

  • From one-shot shell calls or another process, pass baseUrl with path to capture an already-running preview/site without generating, building, starting, or restarting preview.

  • Use preview.stop only in the same long-running MCP server or webstudio mcp run process that started preview. A separate one-shot single-op-call process does not own another process's preview controller.

  • Use waitForSelector when the rendered app has a reliable ready marker, waitUntil:"networkidle" for network-heavy pages, and waitForTimeout only for final visual settling.

  • The screenshot timeout bounds browser capture after the preview is ready. A timeout returns SCREENSHOT_TIMEOUT, resets the reusable browser session, and releases the shared preview lifecycle for cleanup.

  • Preview installs generated app dependencies under .webstudio/preview and reuses them across regenerations.

  • Do not add generated-preview dependencies to the repository root package.json or pnpm-lock.yaml.

  • When launcher metadata is available, Preview reuses a supported npm or pnpm launcher. Without launcher metadata, it uses npm when available and otherwise falls back to pnpm.

  • Unless npm_config_cache is already configured, npm uses the writable .webstudio/preview/.npm-cache directory.

  • For npm cache permission errors, unset npm_config_cache to use the preview-local cache, then retry. No cache deletion is required.

  • If dependency installation fails, check the reported package-manager path and network configuration, then reinstall or update the Webstudio CLI if the problem persists.

  • When a baseline exists, use screenshot.diff once per baseline/current page or viewport pair to get changed regions, OCR textAnalysis, and diff artifact paths before deciding whether the result matches. Pass expectedText for explicit pass/fail current-screen text assertions with found and missing text. Pass expectedVisual for pass/fail limits on pixel mismatch percentage, changed-region count, or the overall dominant color/brightness direction.

  • If screenshot.diff reports OCR unavailable and the user agrees to install it, call vision.install-ocr {"confirm":true}; otherwise continue with pixel diff and visual inspection.

  • Compare the PNG, OCR text evidence, and diff artifacts against the user's intent for layout, typography, colors, spacing, imagery, and responsive framing; then iterate with focused mutations.

  • Root CLI equivalent: webstudio screenshot --path /pricing --output pricing.png generates a temporary production preview, captures that route, and stops the server. For repeated captures, keep webstudio preview running and pass its absolute URL to webstudio screenshot.

List pages

Commands:

  • MCP tool: list-pages {}
  • MCP tool: list-folders {}

Read page by id

Commands:

  • MCP tool: get-page {"pageId":""}

Read page by path

Commands:

  • MCP tool: get-page-by-path {"path":"/pricing"}

Create page

Commands:

  • MCP tool: create-page {"name":"Pricing","path":"/pricing"}
  • MCP tool: create-page {"name":"Pricing","path":"/pricing","title":""Pricing"","meta":{"description":""Plans for teams""}}

Notes:

  • name and path are plain values. Page title and metadata text fields contain expression source; quote fixed text as a JavaScript string literal inside the JSON string.
  • For computed page titles or metadata, send JavaScript expression code such as pageTitle ?? "Pricing". An unquoted word is a variable reference.
  • CLI flags such as --title treat values as fixed text. Add --expressions to webstudio create-page when passing expression source through these flags; quote any fixed text in the same call as a JavaScript string expression.

Update page settings/metadata

Commands:

  • MCP tool: update-page {"pageId":"","values":{"title":""Pricing"","meta":{"description":""Plans"","status":200}}}
  • MCP tool: update-page {"pageId":"","values":{"meta":{"auth":{"method":"basic","login":"","password":""}}}}

Notes:

  • For fixed page title and metadata text, quote the text as a JavaScript string literal inside the JSON string.
  • For computed page titles or metadata, send JavaScript expression code such as pageTitle ?? "Pricing". An unquoted word is a variable reference.
  • Page status accepts a fixed HTTP status code as a number from 200 through 599 or a JavaScript expression string for a dynamic status.
  • For webstudio update-page, add --expressions when page title or metadata flags contain expression source. Without it, those flags are fixed text.

Read project settings

Commands:

  • MCP tool: get-project-settings {}

Notes:

  • Read meta.agentInstructions before making project changes. It contains the project's own guidance for AI agents.
  • Agent instructions are shared project guidance. Do not store credentials or other secrets there.

Update project settings

Commands:

  • MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}
  • MCP tool: update-project-settings {"meta":{"agentInstructions":"Use existing design tokens and keep product copy concise."}}

Read marketplace product

Commands:

  • MCP tool: get-marketplace-product {}

Update marketplace product

Commands:

Submit marketplace product

Commands:

  • MCP tool: upload-asset {"asset":{"name":"marketplace-thumbnail.png","type":"image","format":"png","meta":{"width":1200,"height":630}},"assetsDir":".webstudio/assets"}
  • MCP tool: update-marketplace-product {"category":"pageTemplates","name":"Acme Template","thumbnailAssetId":"","author":"Acme Studio","email":"[email protected]","website":"https://example.com","issues":"","description":"Reusable template project for Acme landing pages."}
  • MCP tool: publish {"target":"production"}
  • MCP tool: submit-marketplace-product {"acknowledgePublicSubmission":true}

Notes:

  • Wait for the production publish to complete before submitting the product for review.
  • Submission requires complete, valid marketplace metadata.

List redirects

Commands:

  • MCP tool: list-redirects {}

Create redirect

Commands:

  • MCP tool: create-redirect {"old":"/old","new":"/new","status":301}

Update redirect

Commands:

  • MCP tool: update-redirect {"old":"/old","values":{"new":"/newer","status":302}}
  • MCP tool: update-redirect {"old":"/old","values":{"status":null}}

Delete redirect

Commands:

  • MCP tool: delete-redirect {"old":"/old"}

Set redirects

Commands:

  • MCP tool: set-redirects {"redirects":[{"old":"/old","new":"/new","status":"301"}]}

List breakpoints

Commands:

  • MCP tool: list-breakpoints {}

Create breakpoint

Commands:

  • MCP tool: create-breakpoint {"label":"Tablet","maxWidth":991}

Update breakpoint

Commands:

  • MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"label":"Tablet","maxWidth":1023}}
  • MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"condition":null,"minWidth":768}}
  • MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"minWidth":null,"maxWidth":null,"condition":"(hover: hover)"}}

Delete breakpoint

Commands:

  • MCP tool: delete-breakpoint {"breakpointId":"tablet"}

Duplicate page

Commands:

  • MCP tool: duplicate-page {"pageId":"","name":"Pricing Copy","path":"/pricing-copy"}
  • MCP tool: duplicate-page {"pageId":"","name":"Paris","path":"/paris","substitutions":{"text":{"London":"Paris"},"variables":{"city":{"type":"string","value":"Paris"}}}}
  • webstudio duplicate-page --page --name Paris --path /paris --substitutions '{"text":{"London":"Paris"},"variables":{"city":{"type":"string","value":"Paris"}}}' --json

Notes:

  • Text substitutions replace exact fixed text only in the duplicated page's text children, string props, title, and metadata.
  • Variable substitutions are keyed by copied source-variable name and use typed variable values. The operation rejects missing or ambiguous names without committing a partial duplicate.
  • Existing expressions and cloned variable/resource references keep their remapped ids.

List page templates

Commands:

  • MCP tool: list-page-templates {}

Create page template

Commands:

  • MCP tool: create-page-template {"name":"Landing Template","title":""Landing""}

CLI create-page-template and update-page-template use fixed text flags by default. Add --expressions when passing expression source through title or metadata flags.

Update page template

Commands:

  • MCP tool: update-page-template {"templateId":"","values":{"name":"Article Template","meta":{"description":"Reusable article layout"}}}

Delete page template

Commands:

  • MCP tool: delete-page-template {"templateId":""}

Duplicate page template

Commands:

  • MCP tool: duplicate-page-template {"templateId":""}

Reorder page template

Commands:

  • MCP tool: reorder-page-template {"sourceTemplateId":"","targetTemplateId":"","position":"before"}

Create page from template

Commands:

  • MCP tool: create-page-from-template {"templateId":"","name":"Landing","path":"/landing"}

Delete page

Commands:

  • MCP tool: delete-page {"pageId":""}

List folders

Commands:

  • MCP tool: list-folders {}
  • MCP tool: list-pages {}

Create folder

Commands:

  • MCP tool: create-folder {"name":"Blog","slug":"blog"}

Update folder

Commands:

  • MCP tool: update-folder {"folderId":"","values":{"name":"Blog","slug":"blog"}}

Delete folder

Commands:

  • MCP tool: delete-folder {"folderId":""}

List element instances

Commands:

  • MCP tool: list-instances {"pagePath":"/","maxDepth":3}

Inspect one element instance

Commands:

  • MCP tool: inspect-instance {"instanceId":"","include":["props","styles","children"]}

Insert authored JSX or one component template

Commands:

  • MCP tool: insert-fragment {"parentInstanceId":"","fragment":"<section ws:style={csspadding: 32px;}>

    Product OS

    "}
  • MCP tool: insert-component {"parentInstanceId":"","component":"@webstudio-is/sdk-components-react-radix:Switch"}
  • MCP tool: insert-component {"parentInstanceId":"","component":"ResourceForm"}

Notes:

  • Use MCP insert-fragment as the default way to author styled component trees. It converts JSX to a structured fragment before mutation.
  • Use only exact component ids returned by components.search, components.get, or templates.get. Never derive or guess component ids.
  • Use lowercase HTML JSX such as <div> and <form>. The internal ws: namespace is not HTML-tag shorthand.
  • For Webstudio's complete form structure, discover the Form component and insert its automatic template with insert-component using component "ResourceForm".
  • MCP receives JSX as a JSON string because MCP arguments are JSON. The CLI converts it locally before the runtime mutation, so the project session receives structured Webstudio data, not JSX source.
  • In insert-fragment JSX, use ws:style={css`...`} for Webstudio-native CSS, or use React-style object syntax such as style={{ padding: 24 }} when that is simpler. Both forms create editable Webstudio style data.
  • Do not access host globals or dynamic code APIs in JSX fragments, including process, globalThis, eval, Function, or constructor.
  • Use Webstudio prop names such as class and for; do not use React aliases className or htmlFor.
  • Use Webstudio actions for event/action props, for example onClick={new ActionValue(["event"], expression\console.log(event)`)}. Do not pass JavaScript functions such as onClick={() => ...}`.
  • Plain prop values must be JSON-compatible: null, strings, booleans, finite numbers, arrays, and plain objects. Do not pass undefined, Symbol, BigInt, NaN, Infinity, Date, Map, Set, class instances, or circular objects; omit the prop, use plain data, or use expression/ActionValue when the value is dynamic.
  • Template-backed components used in JSX must include required child/part components explicitly under the same parent structure as the template, for example <Switch><SwitchThumb /></Switch>.
  • Webstudio applies a registered template automatically when using insert-component, so composed components such as Switch include required child parts and styles.
  • Use components.list, components.summary, components.search, components.get, templates.list, and templates.get to discover known registry items, component ids, props, templates, insertability, and content model. Read webstudio://project/components only when those focused tools are insufficient.
  • Component/template registry items use a shadcn-compatible top-level shape plus Webstudio-specific superset metadata in meta. They are for Builder/MCP discovery, not a published shadcn install registry yet.
  • Known components with contentModel.category: "none" are not standalone-insertable; insert their root component template instead so required providers/parents are included.
  • Unknown custom component ids are a low-level extension mechanism, not a discovery fallback. Agents must not synthesize them.

Make a region editable in Content mode

Commands:

  • MCP tool: insert-component {"parentInstanceId":"","component":"ws:block"}
  • MCP tool: inspect-instance {"instanceId":"","include":["children"]}

Notes:

  • When a page will be handed to a Content-mode editor, wrap every region they should be able to edit in a Content Block (ws:block). Content-mode editors can edit text and supported props only in Content Block descendants. Content outside those blocks remains read-only, even when it looks like ordinary editable text.
  • Put reusable insertable options inside exactly one direct ws:block-template child. A missing or second template container makes the Content Block invalid. A template is source material, not editor content: editors cannot edit or delete it directly. When an editor inserts a template, its copy becomes a direct child of the Content Block and is editable.
  • Before implementation, inventory every editor-owned field and its intended control and write destination, whether or not the block uses MDX. Check that templates contain the required styling, but do not treat containment or a successful text edit as proof that the whole block is editable. Test every field through Content mode, inspect its saved project data or source file, reload, and restore the original value. Report passed, failed, or not tested for each field; missing or read-only required controls are unfinished requirements.
  • Use controls that match the content: a calendar for dates and an image picker for image replacement. Keep fixed punctuation and units out of directly bound value elements. Preserve stored types and wording: when reading time is already a complete string such as 4 min read, bind that string directly rather than assuming it is a number.
  • For MDX-backed blocks, containment alone is not enough: the MDX body is editable through its source mapping, but the designed shell needs writable document-frontmatter bindings. Follow the binding recipe below rather than binding editable article fields to query results.

Store Content Block content in MDX

Commands:

  • MCP tool: list-assets {"type":"file"}
  • MCP tool: upload-asset {"asset":{"name":"article.mdx","type":"file","format":"mdx","meta":{}},"assetsDir":".webstudio/assets"}
  • MCP tool: connect-content-block-source {"blockInstanceId":"","renderScope":"page:/articles/example","source":{"type":"asset","assetId":""}}
  • MCP tool: switch-content-block-source {"blockInstanceId":"","renderScope":"page:/articles/example","source":{"type":"asset","assetId":""}}
  • MCP tool: inspect-content-block-source {"blockInstanceId":"","renderScope":"page:/articles/example"}
  • MCP tool: edit-content-block-source {"blockInstanceId":"","renderScope":"page:/articles/example","source":"# Article title\n\nArticle body."}
  • MCP tool: update-content-block-frontmatter {"blockInstanceId":"","renderScope":"page:/articles/example","properties":{"title":"Article title","draft":false}}
  • MCP tool: reload-content-block-source {"blockInstanceId":"","renderScope":"page:/articles/example"}
  • MCP tool: migrate-content-block-template-references {"assetIds":[""],"migration":{"type":"rename","from":"Old template name","to":"New template name"}}
  • MCP tool: disconnect-content-block-source {"blockInstanceId":"","renderScope":"page:/articles/example"}

Notes:

  • Create the local .mdx file under .webstudio/assets before calling upload-asset. Use the returned Asset ID when connecting it.
  • Use the Content Block source operations for connecting, switching, inspecting, editing, reloading, and disconnecting. Do not create or delete the src prop with generic prop tools; the source operations preserve the Body outlet and Content Block lifecycle.
  • renderScope accepts any non-empty stable key for one rendered occurrence. Use a page-based key for a direct Content Block and a distinct key for each repeated Collection occurrence. It does not load a page, route parameters, or resource results. Supply the concrete scoped values needed to resolve an expression through variables.
  • For a result-one Assets resource, preview the concrete query, then connect its persisted expression with the previewed item supplied as variables, for example source:{"type":"expression","value":"post.data.id"} and variables:{"post":{"data":{"id":"<mdxAssetId>"}}}.
  • Connecting replaces existing Body content. If the result returns requiresConfirmation:true, report that replacement to the user and repeat the same call with confirmReplacement:true only after approval.
  • Prefer Markdown for standard document content; it automatically uses a unique matching semantic template when one exists. Use lowercase JSX such as <section> or <svg> for HTML or SVG with authored properties that Markdown cannot express.
  • Verify that the Content Block has exactly one direct Templates container before connecting or editing MDX. Zero or multiple containers block materialization and publication.
  • Read the Content Block's Templates children before writing a custom reference. Use capitalized JSX such as <PromotionCard /> for its stable Name, which is independent from the display label. A matching template wins over a built-in MDX adapter. Other registered components are unavailable until added to this Content Block's Templates. JSX attributes accept quoted static values and bare booleans; expressions such as {false} are unsupported. Legacy ws.element and ws:name forms are compatibility input only. Component namespaces such as $.*, radix.*, and animation.* are unsupported.
  • When explicit JSX children match the designed template structure, their text and supported props overlay the cloned descendants and retain template styles. A mismatched child structure replaces the root defaults, while each authored child still resolves through a matching template when possible. An explicit empty pair clears defaults, and a self-closing reference keeps them. Editing inherited default content writes it back as explicit JSX children. Template resolution is live, so adding a matching semantic or named template later updates existing MDX. Preserve unresolved names and report their diagnostics instead of deleting them.
  • When a template is renamed or deleted, use migrate-content-block-template-references to update a selected set of affected MDX files. The first call returns a plan. Report its changed-file, update, omission, and diagnostic counts, then repeat the exact request with its confirmationToken only after approval. Renames and removals update named JSX and legacy ws:name references, including names such as Image and CodeText when they identify templates. Rename targets must be valid PascalCase JSX identifiers. Removing a paired reference unwraps and preserves its authored children; removing a self-closing reference removes the node because it has no authored children. Invalid files remain unchanged and are reported in diagnostics.
  • edit-content-block-source replaces the complete MDX source. Preserve frontmatter and unrelated source when making a bounded edit.
  • update-content-block-frontmatter replaces the complete frontmatter mapping. Inspect the current source first and include every property that must remain.
  • Store frontmatter images as exact $ref objects. Bind an editable Image source to the resolved .src with explicit binding.mode:"readwrite"; use mode:"read" for its alt binding to .description. Omitting the source mode leaves the image visible but not replaceable in Content mode.
  • Use update-content-block-frontmatter for MCP frontmatter edits. MDX-rendered elements are not persistent instance targets for generic bind-props or update-text calls. Preserve existing mode:"readwrite" bindings when encountered; they are valid only for exact direct paths into the connected document's frontmatter. Direct bindings through a loaded Markdown or MDX $ref ending in #frontmatter save to the referenced file, with its write permissions enforced. Shared-record edits affect every document using that record. Computed expressions and JSON/body references remain read-only. Image replacement is supported: a direct Image source binding with mode:"readwrite" lets the picker replace the frontmatter $ref, while shared Asset metadata is edited in Asset settings.
  • Inspect every returned diagnostic. Invalid MDX is saved rather than silently repaired; preserve the source, report the source range, and fix only the requested or invalid part.
  • If an edit in a long-lived MCP session reports a conflict after another client saved the Asset, call reload-content-block-source, inspect the latest source, reapply the requested change, and retry. One-shot CLI calls refresh before each operation and normally cannot reproduce a stale session. Never overwrite the newer revision blindly.

Make an MDX article header editable

Use the resource only to select the connected source, for example post.data.id. Bind article values inside the Content Block to its document parameter instead of post.data.properties.*. Inspect the block's variables first; document is the default name, not a name to assume.

These commands target persistent designed instances inside the connected block.

Commands:

  • MCP tool: update-text {"instanceId":"","childIndex":0,"text":"document.frontmatter.title","mode":"expression","expressionBindingMode":"readwrite"}
  • MCP tool: update-text {"instanceId":"","childIndex":0,"text":"document.frontmatter.readingTime","mode":"expression","expressionBindingMode":"readwrite"}
  • MCP tool: bind-props {"bindings":[{"instanceId":"","name":"datetime","binding":{"type":"expression","value":"document.frontmatter.publishedAt","mode":"readwrite"}}]}

Notes:

  • Create writable bindings explicitly; the default is read-only. Merely moving a heading or Link inside the Content Block does not make its query-bound text editable.
  • The MDX body uses its source mapping. Static designed content outside that body remains protected unless its text or supported props bind to writable frontmatter fields. Do not apply these generic instance tools to MDX-generated instances.
  • Use direct static paths. Property access is already safe. Fallbacks and formatted expressions, such as document.frontmatter.title ?? "Untitled", remain read-only.
  • Keep every intended editable value in its own text element with a single direct read-write binding. For reading time, use three inline siblings: static — , the bound reading-time value, and static min read. Preserve whitespace and the stored field type. Do not combine them into a template literal or concatenate strings, and do not put literal siblings inside the value element itself. Keep fixed wording protected in the designed shell.
  • Prefer component formatting controls, such as Date Time formatting with a directly bound date prop, over transforming the expression. Do not silently sacrifice editability for formatting or a fallback; explain unsupported cases and ask before making an intended editable field read-only.
  • A direct writable binding such as document.frontmatter.author.name can edit a shared author loaded through ../authors/acme.md#frontmatter. The edit saves to the author file and affects every article using it; preserve the article's $ref marker.
  • Before handoff, inventory every article-owned field, including header text, author details, dates, reading time, categories, hero and inline image sources, alternative text, captions, links, and custom-component content. For each field, inspect its binding and source, edit it through the Content-mode UI, verify the saved MDX or referenced file, reload, and restore the test value. Record passed, failed, or not tested for each field. A correct preview, a successful MCP write, and one representative text edit do not prove the whole article is editable. Do not claim completion while required fields fail or remain untested.
  • Bind the Image source directly to document.frontmatter.featureImage.src with binding.mode:"readwrite" using bind-props. Content mode's Choose source replaces the article's frontmatter image $ref; the resolved URL stays read-only. Verify selection, the saved reference, and reload instead of treating a missing write mode as a platform limitation. For alternative text bound to .description, use Choose source → asset actions → Settings → Description to edit shared Asset metadata. This affects every use of the Asset and is separate from replacing an article's image.

Make an article image replaceable in Content mode

Use this for a persistent designed Image inside a connected Content Block, with featureImage: { $ref: "./images/hero.png" } in its MDX frontmatter. Read the instance ID and document variable name before adapting the example.

Commands:

  • MCP tool: bind-props {"bindings":[{"instanceId":"","name":"src","binding":{"type":"expression","value":"document.frontmatter.featureImage.src","mode":"readwrite"}},{"instanceId":"","name":"alt","binding":{"type":"expression","value":"document.frontmatter.featureImage.description","mode":"read"}}]}

Notes:

  • The source mode must be explicit: the default read mode displays the image but prevents Content-mode replacement. Do not bind to query-result properties or add a fallback expression.
  • Choose source replaces the article's featureImage.$ref; the disabled resolved-URL input is expected. Do not store a resolved URL string or replace the shared Asset itself.
  • Shared alternative text is a separate action: Choose source → asset actions → Settings → Description. Its read-only binding does not require the image source binding to be read-only.
  • If the picker is missing or disabled, inspect the source mode, document scope, loaded reference, and permissions before claiming a product limitation.
  • Verify through Content mode with an approved temporary replacement. Check the saved $ref, unchanged unrelated MDX and original shared Asset, reload persistence, and restoration. If that test is not authorized, report it as not tested, not passed.

Move elements

Commands:

  • MCP tool: move-instance {"moves":"moves.json contents"}

Notes:

  • Use position: "end" to append an instance. Repeating this for A and then B preserves the final order A, B.
  • A numeric insertIndex addresses the target parent's children before the moved instance is removed. Use it for exact placement; do not calculate the last index to append.
  • Moves in one moves array are applied sequentially in array order.

Clone element subtree

Commands:

  • MCP tool: clone-instance {"sourceInstanceId":"","targetParentInstanceId":""}

Delete element subtree

Commands:

  • MCP tool: delete-instance {"instanceIds":[""]}

List text/expression children

Commands:

  • MCP tool: list-texts {"pagePath":"/"}

Update text child

Commands:

  • MCP tool: update-text {"instanceId":"","childIndex":0,"text":"Launch faster"}

Replace bounded literal text

Commands:

  • MCP tool: replace-text {"find":"Start free","replace":"Get started","match":"exact","pagePath":"/pricing","limit":20}

Notes:

  • This changes only literal text children, never expression children. Scope it to pagePath or pageId and set a limit before a broad replacement.

Replace bounded static prop text

Commands:

Notes:

  • This changes only static string props such as href, alt, aria-label, title, and HTML embed code. It never changes expressions, resources, actions, assets, or other dynamic bindings. Use names or instanceIds and a limit to narrow the change.

Replace bounded resource text

Commands:

  • MCP tool: replace-resource-text {"find":"api.old.example.com","replace":"api.example.com","fields":["url"],"limit":20}

Notes:

  • This changes resource names and fixed URL literals only. It skips dynamic URL expressions, headers, search parameters, request bodies, and GraphQL query code.

Update props

Commands:

  • MCP tool: update-props {"updates":"props.json contents"}
  • MCP tool: replace-prop-text {"find":"Old label","replace":"New label","names":["aria-label","title"],"limit":20}

Notes:

  • Use this for fixed prop values such as aria-label, alt, id, static href, and other direct string/number/boolean/json prop values.

Add JSON-LD structured data

Commands:

Notes:

  • Prefer placing JsonLd inside HeadSlot.
  • For fixed structured data, store code as a JSON object or array encoded as a compact string. The Builder formats it for editing.
  • For structured data containing runtime values, use bind-props with an expression that evaluates directly to an object or array. Do not call JSON.stringify or assemble JSON with string concatenation. Webstudio stores the expression as source text, evaluates it at runtime, and the JsonLd component validates and serializes the resulting value.
  • The semantic prop update rejects malformed JSON and structurally invalid fixed JSON-LD with a precise JSON path.
  • The SEO audit also warns about a missing top-level @context, unknown or superseded Schema.org terms, properties unsupported by the supplied type, and incompatible primitive value types.
  • Schema.org vocabulary findings are warnings because custom vocabularies and extensions remain valid. Dynamic JSON-LD is marked as skipped for rendered validation.
  • Do not use bindings just to set static text.

Delete props

Commands:

  • MCP tool: delete-props {"deletions":"props.json contents"}

Bind props to expressions/resources/actions

Commands:

  • MCP tool: bind-props {"bindings":"bindings.json contents"}

Notes:

  • Use this only when the prop should remain dynamic: expression, resource, action, or an existing scoped runtime context value such as system.
  • For a fixed string value, use update-props with type:"string" and a direct value instead.

Read styles

Commands:

  • MCP tool: get-styles {"instanceIds":[""],"includeTokens":true}

Update local styles

Commands:

  • MCP tool: update-styles {"updates":"styles.json contents"}

Delete local styles

Commands:

  • MCP tool: delete-styles {"deletions":"styles.json contents"}

Replace matching style values

Commands:

  • MCP tool: replace-styles {"property":"color","fromValue":{"type":"keyword","value":"red"},"toValue":{"type":"keyword","value":"blue"}}

List design tokens

Commands:

  • MCP tool: list-design-tokens {}
  • MCP tool: list-design-tokens {"withUsage":true}
  • MCP tool: list-design-tokens {"verbose":true}

Notes:

  • The default response is compact and includes token id, name, declaration count, and optional usage count.
  • Use verbose:true only when you need the full inline style declarations.

Create design tokens

Commands:

  • MCP tool: create-design-token {"tokens":"tokens.json contents"}

Update design token styles

Commands:

  • MCP tool: update-design-token-styles {"designTokenId":"","updates":"styles.json contents"}

Delete design token styles

Commands:

  • MCP tool: delete-design-token-styles {"designTokenId":"","deletions":"styles.json contents"}

Attach design token to instances

Commands:

  • MCP tool: attach-design-token {"designTokenId":"","instanceIds":"instances.json contents"}

Detach design token from instances

Commands:

  • MCP tool: detach-design-token {"designTokenId":"","instanceIds":"instances.json contents"}

Extract design token from local styles

Commands:

  • MCP tool: extract-design-token {"instanceIds":[""],"name":"Brand Primary","removeLocalProps":["color"]}

List CSS variables

Commands:

  • MCP tool: list-css-variables {"withUsage":true}

Define CSS variables

Commands:

  • MCP tool: define-css-variable {"vars":{"--color-primary":"#2d3748","--color-accent":"#e53e3e","--space-card":"1.5rem"},"overwrite":true}

Notes:

  • Define or overwrite multiple CSS variables atomically by including every name and value in one vars object.
  • Pass colors as CSS strings. Structured hex color components use normalized values from 0 to 1, not 0 to 255.

Delete CSS variables

Commands:

  • MCP tool: delete-css-variable {"names":["--color-primary","--color-accent","--space-card"],"force":true}

Notes:

  • Delete multiple CSS variables atomically by including every name in one names array. Destructive MCP calls still require the returned confirmation token before they commit.

Rewrite CSS variable references

Commands:

  • MCP tool: rewrite-css-variable-refs {"map":"variables.json contents"}

List data variables

Commands:

  • MCP tool: list-variables {}
  • MCP tool: list-variables {"scopeInstanceId":""}

Notes:

  • Data variables live in the internal dataSources namespace.
  • For raw snapshot, request the public variables namespace rather than the internal dataSources name. Raw patch payloads still use dataSources when applying direct changes.
  • Scope variables to the instance where they should become available. Descendants can use them in expressions, and nested variables with the same name mask outer variables.

Create data variable

Commands:

  • MCP tool: create-variable {"scopeInstanceId":"","name":"title","value":{"type":"string","value":"Hello"}}
  • MCP tool: create-variable {"scopeInstanceId":"","name":"count","value":{"type":"number","value":3}}
  • MCP tool: create-variable {"scopeInstanceId":"","name":"featured","value":{"type":"boolean","value":true}}
  • MCP tool: create-variable {"scopeInstanceId":"","name":"tags","value":{"type":"json","value":["news","product"]}}
  • MCP tool: create-variable {"scopeInstanceId":"","name":"filters","value":{"type":"json","value":{"tag":"news"}}}

Notes:

  • Data variable values support string, number, boolean, and json. Use json for all arrays and objects.
  • Parameters are internal scoped runtime values provided by pages, collections, or components. They are not a public authoring surface: do not create, update, or delete parameter records. Use data variables/resources for user-authored data, and reference documented context values such as system only where they are already in scope.

Update data variable

Commands:

  • MCP tool: update-variable {"dataSourceId":"","values":{"value":{"type":"json","value":{"count":1}}}}

Delete data variable

Commands:

  • MCP tool: delete-variable {"dataSourceId":""}

List resources

Commands:

  • MCP tool: list-resources {}
  • MCP tool: list-resources {"scopeInstanceId":""}

Create resource

Commands:

Notes:

  • Resource url accepts plain fixed URLs and paths such as https://api.example.com/posts and /$resources/current-date.
  • Resource url can also be a JavaScript expression when it is computed, such as "https://api.example.com/posts?tag=" + filters.tag.
  • Header values, search parameter values, and body accept expressions for dynamic values. For fixed text, use {"type":"literal","value":"application/json"}; Webstudio stores the required string expression for you.
  • Search parameter values, header values, and body expressions can read scoped variables and documented runtime context values such as system when they are available at the resource scope.
  • Add scopeInstanceId and dataSourceName when the resource result should be exposed as a scoped read data variable. Scoped resources are generated into the page resource data map and may be loaded during page rendering. Use this for read-oriented resources such as GET CMS/API data.
  • For submit/write/action resources, create the resource without scopeInstanceId, then bind a component prop such as a Form action with bind-props and binding.type: "resource". Prop-bound resources are generated into the page resource action map instead of the read data map. Use this for POST, PUT, DELETE, webhooks, GraphQL submissions, and other explicit action flows.
  • Resource method can be get, post, put, or delete. Use GET for read data, POST for creates/GraphQL/webhooks/form submissions, PUT for full updates or replacements, and DELETE for deletion actions.
  • Optional control values are graphql and system. Use graphql for GraphQL-style requests, usually POST with a query body. Use system for built-in resources such as "/$resources/sitemap.xml", "/$resources/current-date", and "/$resources/assets" and when the resource should use the built-in system parameter. System fields are system.origin, system.pathname, system.params, and system.search. A query key with one value is a string; repeated values are an ordered array. For ?tag=red&tag=blue, system.search.tag is ["red", "blue"].

Update resource

Commands:

  • MCP tool: update-resource {"resourceId":"","values":{"url":"https://api.example.com/posts"}}
  • MCP tool: replace-resource-text {"find":"api.old.example.com","replace":"api.example.com","fields":["url"],"limit":20}

Configure Form (Beta) through MCP

Use the exact component id returned by components.search for Form (Beta). After inserting its registered template, use the Form instance id for the Form-scoped Resource and Action settings.

The new Form's canonical component id is ResourceForm. The deprecated Webhook Form remains available in Builder for existing projects until the next release, but is omitted from MCP component discovery. RemixForm is deprecated compatibility and should not be used for new projects. Always use registry discovery instead of assuming the display label is its component id.

The new Form has two modes derived from its Action array:

  • One or more connected Resources: the rendered action is ?__webstudio__=resources and submission runs the Resource actions.
  • No connected Resources (action: []): the rendered action is ?__webstudio__=navigate and submission updates URL query parameters through client-side navigation. Use this for search and filters with page Resources bound to system.search. Removing the last Action switches to Navigation mode.
  • For ordinary browser submission, insert an Element with tag: "form". It has no managed action marker and retains native browser behavior.

Do not write the __webstudio__ marker as a project Action value: that prop holds Resource selections, and the runtime derives the HTML action URL from it. Verify both modes through MCP in a real project: add Resource actions, remove all actions for a search/filter form, then reconnect them. Check the rendered action, query navigation without a full reload, and Resource execution. Also verify a plain form Element remains native. A saved project snapshot alone does not prove these runtime behaviors.

Commands:

  • MCP tool: insert-component {"parentInstanceId":"","component":""}
  • MCP tool: create-resource {"resource":{"name":"Send submission","method":"post","url":"https://api.example.com/submit","headers":[],"body":"formData"},"scopeInstanceId":"","dataSourceName":"Send submission","exposeAsDataSource":true}
  • MCP tool: update-props {"updates":[{"instanceId":"","name":"action","type":"json","value":[{"dataSourceId":""}]}]}
  • MCP tool: update-resource {"resourceId":"","values":{"email":{"recipientMode":"visitor","visitorEmailField":"email","includeAttachments":true}}}
  • MCP tool: update-project-settings {"meta":{"emailSender":"Acme [email protected]"}}

Notes:

  • Use update-props with a JSON Action array to add, order, or remove destinations. The Action entries use { "dataSourceId": "..." } and support up to ten Resources, matching the Builder control. Each connected Action runs in its configured order. An extra enabled key in older saved settings is ignored.
  • Create each destination Resource in the Form's scope so it can use formData and browserInfo. Set exposeAsDataSource:true to receive the data-source id used by the Action array. When a Resource uses Form-only parameters, it is kept out of page-load requests and runs with the Form submission.
  • update-resource accepts the same Email settings as the Builder: project, custom, or visitor recipients; sender; subject; body; and submitted-file attachments. Use expressions in string fields for dynamic values.
  • update-project-settings edits the project-wide Email recipients and Reply to. update-props also sets Form fields and Success redirect, while bind-props supplies dynamic expressions. insert-component uses the registered Form template, including its default contact fields and Email Actions. Set subject and body on each Email Resource.
  • MCP mutations update saved project configuration. To test real delivery, submit the Form in Preview or on a published test site and inspect the configured destinations.

Query Markdown assets

Commands:

  • MCP tool: get-asset-field-catalog {}
  • MCP tool: validate-asset-query {"query":{"where":{"all":[{"field":["extension"],"operator":"eq","value":"md"},{"field":["properties","draft"],"operator":"ne","value":true}]},"limit":20}}
  • MCP tool: create-assets-resource {"name":"All assets","scopeInstanceId":"","dataSourceName":"assets"}
  • MCP tool: create-assets-resource {"name":"Published posts","scopeInstanceId":"","dataSourceName":"posts","query":{"result":"many","where":{"all":[{"field":["extension"],"operator":"eq","value":{"type":"literal","value":"md"}},{"field":["properties","draft"],"operator":"ne","value":{"type":"literal","value":true}}]},"sort":[{"field":["properties","publishedAt"],"direction":"desc"}],"limit":{"type":"literal","value":20},"output":{"mode":"fields","includeMetadata":false,"fields":[["properties","title"],["properties","slug"],["properties","publishedAt"],["properties","excerpt"]]},"content":{"mode":"none"}}}
  • MCP tool: create-assets-resource {"name":"Post by slug or ID","scopeInstanceId":"","dataSourceName":"post","query":{"result":"one","where":{"all":[{"field":["extension"],"operator":"eq","value":{"type":"literal","value":"md"}},{"field":["properties","slug"],"operator":"eq","value":"system.params.slug"}]},"output":{"mode":"fields","includeMetadata":false,"fields":[["properties","title"],["properties","publishedAt"]]},"content":{"mode":"markdown-body-ref"}}}
  • MCP tool: list-assets-resources {}
  • MCP tool: get-assets-resource {"resourceId":""}
  • MCP tool: update-assets-resource {"resourceId":"","values":{"query":null}}
  • MCP tool: preview-asset-query {"query":{"result":"one","where":{"all":[{"field":["extension"],"operator":"eq","value":"md"},{"field":["properties","slug"],"operator":"eq","value":"hello-world"}]},"output":{"mode":"fields","includeMetadata":false,"fields":[["properties","title"]]},"content":{"mode":"markdown-body-ref"}}}

Notes:

  • Choose .mdx connected to a Content Block when editors must edit article bodies visually in Content mode. Publishing downloads and compiles every reachable MDX article, so more articles can slow publishing. Choose .md with Markdown Embed when editing the source in Assets is enough; Content mode editors can still edit the Markdown file there, but not its body on the canvas. .md needs no per-article MDX compilation, though the publish runner still synchronizes Asset files for both formats and static generation may read Markdown bodies.
  • Read the field catalog before authoring unfamiliar queries. It includes dynamic schema-less frontmatter paths such as properties.author.name, observed types, optionality, and mixed-type state without downloading the source files.
  • Minimize the deployed content database by using output.mode:"fields" and selecting only fields the rendered page needs. Keep includeMetadata:false unless the rendered value needs file metadata such as name, path, MIME type, or creation date, and avoid output.mode:"all" as a convenience default. Query diagnostics are returned separately and do not require metadata output. Filters and sorting may still require their referenced fields in the database.
  • Every reachable Assets data source contributes to the shared published database. Keep one final resource per rendered query. Update an existing scoped resource rather than creating a placeholder, preview copy, or repair replacement, and remove obsolete duplicates.
  • Keep bounded overview filters, limits, and offsets literal and add a deterministic ID tie-breaker to the sort. With content.mode:"none", compilation can materialize the small overview result instead of retaining its output fields across every candidate document. Use runtime expressions only for genuinely dynamic values such as the detail slug.
  • Combine filters with where.all (AND) and where.any (OR), including nested groups. Filter values, limit, and offset on a saved resource may be Webstudio expressions evaluated at render time. Preview queries use concrete JSON values.
  • Query Markdown or MDX files directly and use content.mode:"markdown-body-ref" when rendering their bodies. The published database retains metadata and a document reference, then fetches only the selected files from Asset storage at runtime; it does not embed their bodies. Filter and paginate before content is loaded.
  • full and bounded range continue to request embedded file bytes. Use them only when the caller requires the complete source or a byte range.
  • In Markdown or MDX, reference sibling Assets with conventional relative URLs such as ../images/hero.png. Deferred markdown-body-ref content resolves matching files against the document's folder and emits the correct Builder or published Asset URL. Keep external URLs absolute.
  • Markdown Embed renders sanitized authored HTML for figures, captions, audio, video, and iframes. Scripts, inline event handlers, srcdoc, and unsafe URL protocols are removed. It does not render Webstudio MDX elements; connect the .mdx file to a Content Block for that workflow.
  • Preview each query with concrete values before saving it. Inspect __diagnostics__.query for the temporary query-only footprint and __diagnostics__.database for the merged database built from all reachable Assets queries. Only database.usedBytes counts toward database.maxBytes; query sizes must not be summed and are not separate allowances. Compare usedBytes, unboundedBytes, and truncated within both scopes. A completed Markdown blog should include every source document without truncation, contain no embedded Markdown bodies, and retain only its intended materialized overview query. When merged usage approaches the limit, remove duplicate reachable resources first, then unused output fields, then narrow candidate files.
  • Use result:"many" for listings. It returns the ID-keyed map at <dataSourceName>.data, with totalCount and hasMore at <dataSourceName>.meta, and remains the default for existing queries. Bind a listing Collection to posts.data.
  • Use result:"one" for a unique detail route. It returns the selected item or null directly at post.data, always includes its id, and omits pagination. Bind components and page settings directly with expressions such as post.data.properties.title, post.data.content.text, and post.data ? 200 : 404. result:"first" and result:"last" also return a direct item or null but require explicit sorting.
  • Assets always executes a structured query. Omit query to use the default many-result query, which selects URL and optional image dimensions. Set values.query:null to restore it.
  • create-assets-resource and update-assets-resource are the semantic authoring path. Do not construct the internal query URL, headers, or body expression manually.
  • The shared metadata index is maintained automatically and is emitted only when a configured Assets resource is reachable.

Delete resource

Commands:

  • MCP tool: delete-resource {"resourceId":""}

List assets

Commands:

  • MCP tool: list-assets {"withUsage":true}
  • MCP tool: list-assets {"verbose":true}

Notes:

  • Compact results include each asset's folder id. Use verbose:true to include complete records for a page of assets, or get-asset to read one complete record including description, folder, creation time, and image/font metadata.
  • Image asset descriptions are the default alt text for asset-backed Image components.
  • To generate missing descriptions, inspect the image in its rendered page or asset source, write a concise description of its purpose, and save it on the asset rather than duplicating it on each Image instance.

Get asset

Commands:

  • MCP tool: get-asset {"assetId":""}

List asset folders

Commands:

  • MCP tool: list-asset-folders {}

Create asset folder

Commands:

  • MCP tool: create-asset-folder {"name":"Marketing"}
  • MCP tool: create-asset-folder {"name":"Photos","parentId":""}

Update asset folder

Commands:

  • MCP tool: update-asset-folder {"folderId":"","values":{"name":"Brand"}}
  • MCP tool: update-asset-folder {"folderId":"","values":{"parentId":""}}
  • MCP tool: update-asset-folder {"folderId":"","values":{"parentId":null}}

Notes:

  • Updating parentId is the folder equivalent of cut and paste. Use null to move a folder to Root.

Duplicate asset folder

Commands:

  • MCP tool: duplicate-asset-folder {"folderId":""}
  • MCP tool: duplicate-asset-folder {"folderId":"","parentId":""}

Notes:

  • Duplication recursively copies descendant folders and assets. This is the folder equivalent of copy and paste.

Delete asset folder

Commands:

  • MCP tool: delete-asset-folder {"folderId":""}

Notes:

  • Deleting a folder recursively deletes its descendant folders and assets.

Update asset metadata

Commands:

  • MCP tool: update-asset {"assetId":"","values":{"description":"Team collaborating around a whiteboard"}}
  • MCP tool: update-asset {"assetId":"","values":{"meta":{"family":"Rajdhani","style":"normal","weight":600}}}

Notes:

  • Use an empty description only when the image is intentionally decorative.
  • Updating an image asset description updates the default alt text wherever that asset is used with an asset-backed alt prop.
  • Font metadata updates merge with the detected metadata and are validated before committing; use this to correct a family, style, or weight after upload.

Generate missing image descriptions with an agent

Commands:

  • MCP tool: audit {"scopes":["accessibility"],"verbose":true}
  • MCP tool: set-image-descriptions {"updates":[{"assetId":"hero-id","description":"Team collaborating around a whiteboard"},{"assetId":"texture-id","decorative":true}]}
  • MCP tool: audit {"scopes":["accessibility"]}

Notes:

  • Start from missing-image-description findings. Inspect each image in its rendered page context before writing text.
  • The vision-capable agent generates the wording; the CLI validates and stores it but does not contain its own vision model.
  • Use decorative:true only when the image adds no information. This intentionally stores an empty description so later audits do not report it as missing.
  • Re-run the accessibility audit after the update. Asset-backed Image components use the saved asset description as their default alt text.

Manage fonts

Commands:

  • MCP tool: list-fonts {"includeSystem":true}
  • MCP tool: list-assets {"type":"font"}
  • MCP tool: upload-asset {"asset":{"name":"acme-sans.woff2","type":"font","format":"woff2","meta":{"family":"Acme Sans","style":"normal","weight":400}},"assetsDir":".webstudio/assets"}
  • MCP tool: update-styles {"updates":"styles.json contents"}

Notes:

  • Use list-fonts to discover uploaded families and system stacks. Upload/delete fonts through the existing asset tools, then apply a family with a font-family style declaration.

Upload one asset

Commands:

  • MCP tool: upload-asset {"asset":{"name":"image.png","type":"image","format":"png","meta":{"width":1200,"height":630}},"assetsDir":".webstudio/assets"}
  • MCP tool: upload-asset {"asset":{"name":"image.png","type":"image","format":"png","folderId":"","meta":{"width":1200,"height":630}},"assetsDir":".webstudio/assets"}

Upload asset batch

Commands:

  • MCP tool: upload-assets {"assets":[{"name":"image.png","type":"image","format":"png","meta":{"width":1200,"height":630}}],"assetsDir":".webstudio/assets"}

Notes:

  • Multi-file uploads return uploaded, failed, and ambiguous lists with the original input index. Retry only failed files. A forced upload in ambiguous may already be committed; inspect the Assets list before deciding whether to upload it again. Successful uploads remain committed.

Duplicate asset

Commands:

  • MCP tool: duplicate-asset {"assetId":""}
  • MCP tool: duplicate-asset {"assetId":"","folderId":""}
  • MCP tool: duplicate-asset {"assetId":"","folderId":null}

Notes:

  • Duplication is the asset equivalent of copy and paste. Updating folderId is the equivalent of cut and paste; use null for Root.

Download asset

Commands:

  • MCP tool: download-asset {"assetId":""}

Find asset usage

Commands:

  • MCP tool: find-asset-usage {"assetId":""}

Replace asset references

Commands:

  • MCP tool: replace-asset {"fromAssetId":"","toAssetId":""}

Delete assets

Commands:

  • MCP tool: delete-asset {"assetIdsOrPrefixes":[""],"force":true}

Publish project

Commands:

  • webstudio publish deploy --target production --json

List publishes

Commands:

  • webstudio publish list --json

Check publish job

Commands:

  • webstudio publish status --job --json

Unpublish

Unpublish completes without a publish job.

Commands:

  • webstudio publish unpublish --target production --confirm --json

List domains

Commands:

  • webstudio domains list --json

Create domain

Commands:

  • webstudio domains create --domain example.com --json

Update domain

Commands:

Delete domain

Commands:

  • webstudio domains delete --domain-id --confirm --json

Verify domain

Commands:

  • webstudio domains verify --domain-id --json

Make arbitrary store-level changes

Commands:

  • MCP tool: inspect {}
  • MCP tool: snapshot {"include":[""]}
  • MCP tool: apply-patch {"baseVersion":"","transactions":"patch.json contents"}

Notes:

  • Use only when no semantic command exists.

Manage marketplace metadata

Commands:

  • MCP tool: get-marketplace-product {}
  • MCP tool: update-marketplace-product {"category":"pageTemplates","name":"Acme Template","thumbnailAssetId":"asset-id","author":"Acme Studio","email":"[email protected]","website":"https://example.com","issues":"","description":"Reusable template project for Acme landing pages."}
  • MCP tool: submit-marketplace-product {"acknowledgePublicSubmission":true}

Patch namespaces:

  • marketplaceProduct

Search and inspect safely

Commands:

  • webstudio search-project '{"query":"pricing"}'
  • MCP tool: search-project {"query":"pricing"}
  • MCP tool: search-project {"query":"api.example.com","namespaces":["resources"]}
  • MCP tool: search-project {"query":"Brand","namespaces":["styles","styleSources","styleSourceSelections"]}
  • MCP tool: list-instances {"pagePath":"/","maxDepth":5}
  • MCP tool: inspect-instance {"instanceId":"","include":["props","styles","children"]}
  • MCP tool: list-texts {"pagePath":"/"}
  • MCP tool: list-assets {"withUsage":true}
  • MCP tool: find-asset-usage {"assetId":""}
  • MCP tool: snapshot {"include":["pages","instances","props","resources","assets"]}

Notes:

  • search-project is a standalone local-session command over every Builder namespace. It returns matching values with stable match ids, namespace paths, owning entities, references, and affected pages.
  • Use it when a value or id is known. Use list/get tools when the project structure or target is not known.
  • The command synchronizes its required Builder namespaces, then searches locally and returns only matches. Namespace filters limit values matched; related namespaces may still supply route and reference context, and synchronization is unchanged. This reduces data passed to the model, not the initial project-data synchronization.
  • Asset records and file metadata are searchable. Asset binary or document contents are not Builder namespace data and are not searched.
  • Values in recognized credential fields are excluded and counted in excludedSensitiveValueCount.
  • Use audit for project health findings.

Audit project quality

Commands:

  • webstudio audit --json
  • webstudio audit --scopes accessibility --scopes seo --json
  • webstudio audit --page-path /pricing --json
  • webstudio audit --scopes accessibility --verbose --json
  • webstudio audit --rendered --page-path /pricing --json
  • webstudio audit --rendered --route-example post=/blog/hello --json
  • webstudio audit --rendered --image-domain images.example.com --json
  • MCP tool: audit {}
  • MCP tool: audit {"scopes":["accessibility","security"],"severities":["error","warning"]}
  • MCP tool: audit {"scopes":["accessibility"],"verbose":true}
  • MCP tool: audit {"scopes":["craft"],"verbose":true}
  • MCP tool: audit {"rendered":true,"verbose":true}

Notes:

  • With no scopes, audit checks accessibility, security, SEO, performance settings, unused assets, ineffective Collection styles, non-GET resources exposed as render-time data, and unused or duplicate style data.
  • Craft is opt-in and read-only. Run audit with scopes:["craft"] to detect whether the project is not using Craft, partially compatible, or compatible with the versioned Craft 1.2 profile. profileStatuses includes the University-doc provenance and the smallest safe next action. The audit never installs Craft or changes a non-Craft project.
  • The performance scope reports disabled atomic CSS generation. A rendered audit also measures broken, eager below-fold, and oversized images, browser-marked render-blocking resources, and legacy font formats.
  • Rendered image and resource metrics run only when the selected scopes include performance; responsive layout dimensions remain available whenever rendered:true is requested.
  • Compact findings include stable ids, severity, message, and location. Use --verbose or {"verbose":true} for evidence, explanation, suggested remediation, skipped-check details, and manual-check workflows.
  • summary counts all findings before severity filtering and pagination.
  • contractVersion identifies the audit response contract. Handle a new value before assuming existing fields retain the same meaning.
  • Expression-, resource-, and parameter-backed values that cannot be checked reliably appear in skippedChecks; they are not treated as passing or failing.
  • Page filters apply to page-owned accessibility, security, and SEO checks. Asset and style usage remain project-wide to avoid false unused findings.
  • Continue paginated results with cursor. Restart the audit if the project version changes.
  • Verbose skipped-check and manual-check details are included on the first findings page only; their total counts remain available on every page.
  • manualChecks describes responsive, hierarchy, and contrast checks that require preview screenshots and vision.
  • Focused audits return only manual checks relevant to their selected scopes.
  • In a long-lived MCP session, {"rendered":true} reuses preview and screenshot tools to capture every static page at mobile, desktop, and Builder breakpoint edges. Compact output reports rendered check/issue/failure counts; verbose output includes screenshot paths and measured layout dimensions.
  • Dynamic route templates are skipped unless --route-example <pageId>=<path> (or MCP routeExamples) supplies a concrete path. The path must not contain unresolved : or * parameters.
  • Plans above 120 captures return a short-lived confirmation token. Review the unchanged plan, then rerun with --confirm-large-run and --confirmation-token.
  • Detailed rendered evidence is stored in a versioned manifest under .webstudio/audits; compact output includes its path and screenshot count.
  • Rendered checks also report broken images, eager images below the fold, and image sources more than 2x their rendered dimensions in both axes, including Webstudio instance ids and measured dimensions when available.
  • Rendered checks include sanitized Resource Timing evidence and report browser-marked render-blocking resources plus legacy .ttf, .otf, and .woff fonts without applying a universal transfer-size threshold.
  • Fix findings through semantic mutation commands, then rerun audit to confirm their deterministic finding ids disappeared.

Verify dynamic bindings

Commands:

  • webstudio verify-bindings --json
  • MCP tool: verify-bindings {"pagePath":"/pricing"}
  • MCP tool: verify-bindings {"instanceId":"","limit":50}

Notes:

  • Statically checks persisted text expressions, expression/action/resource/parameter props, resource expressions, and page metadata.
  • Findings distinguish invalid syntax, unknown or out-of-scope variables, stale internal data-source ids, and missing resource or parameter references.
  • Page and instance filters can be combined when the instance belongs to the selected page. Continue findings with cursor.
  • This operation does not resolve rendered values or execute external resources. Preview representative loading, empty, error, and populated states after static findings are fixed.

Refactor targeted content

Commands:

  • MCP tool: list-instances {"pagePath":"/"}
  • MCP tool: list-texts {"pagePath":"/"}
  • MCP tool: update-text {"instanceId":"","childIndex":0,"text":"Launch faster"}
  • MCP tool: replace-text {"find":"Old headline","replace":"New headline","match":"exact","pagePath":"/pricing","limit":20}
  • MCP tool: update-props {"updates":"props.json contents"}
  • MCP tool: update-page {"pageId":"","values":{"title":""Pricing"","meta":{"description":""Plans""}}}
  • MCP tool: update-resource {"resourceId":"","values":{"url":"https://api.example.com/posts"}}
  • MCP tool: replace-asset {"fromAssetId":"","toAssetId":""}
  • MCP tool: replace-styles {"property":"color","fromValue":{"type":"keyword","value":"red"},"toValue":{"type":"keyword","value":"blue"}}
  • MCP tool: rewrite-css-variable-refs {"map":"variables.json contents"}

Notes:

  • Use focused reads first, then mutate only matching instances, props, metadata, resource URLs, assets, or style references. Use replace-text for bounded literal text changes, replace-prop-text for bounded static prop text, replace-resource-text for fixed resource names/URLs, and update-text for one known child or expressions.

Optimize existing project

Commands:

  • MCP tool: list-pages {}
  • MCP tool: list-folders {}
  • MCP tool: update-page {"pageId":"","values":{"title":""Pricing"","meta":{"description":""Plans""}}}
  • MCP tool: update-props {"updates":"props.json contents"}
  • MCP tool: list-breakpoints {}
  • MCP tool: update-breakpoint {"breakpointId":"tablet","values":{"maxWidth":1023}}
  • MCP tool: get-styles {"instanceIds":[""],"includeTokens":true}
  • MCP tool: update-styles {"updates":"styles.json contents"}
  • MCP tool: attach-design-token {"designTokenId":"","instanceIds":"instances.json contents"}
  • MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}

Notes:

  • Use this for SEO metadata, accessibility labels, responsive behavior, token consistency, and project settings.

Connect external data

Commands:

Notes:

  • Use this for CMS sections, blog listings, Ghost/headless CMS pages, n8n-style integrations, and API URLs built from variables.
  • For read data, expose GET resources as scoped data variables with scopeInstanceId/dataSourceName and read the loaded result from the resource result wrapper, usually .data.
  • For writes, webhooks, GraphQL submissions, and deletes, prefer unscoped resources bound to Form action props so they become action resources instead of auto-loaded read resources.
  • Use direct props for fixed values and prop bindings only when a prop must read a data variable, resource, action, or documented runtime context value such as system.

Render an array or object as repeated content

Commands:

  • MCP tool: insert-collection {"parentInstanceId":"","data":{"type":"expression","value":"posts.data.items"},"itemFragment":"

    {expressioncollectionItem.title}

    "}
  • MCP tool: inspect-instance {"instanceId":"","include":["props","bindings","children"]}

Notes:

  • Use Collection whenever an array or object from a resource or data variable should render a list, grid, cards, table rows, options, tabs, or other repeated UI.
  • Pass insert-collection the complete array or object. Do not pass the resource response wrapper or one indexed item. External resource arrays are commonly nested under the scoped resource result's data field or deeper.
  • Pass one repeated-item Webstudio JSX root. The command creates the Collection, its private current-item/current-key parameters, the iterable binding, and descendant item bindings atomically.
  • Collection renders the item root once for every entry. Use expression values such as collectionItem.title in descendant text and props. Object iteration also exposes collectionItemKey.
  • Wrap multiple repeated sibling instances in one Element inside Collection.
  • For repeated Radix items such as accordion items, tabs, or menu options, bind a stable unique id or slug to every required value prop.
  • See the Collection documentation for the equivalent Builder workflow.

Support dynamic runtime behavior

Commands:

Notes:

  • Use integrate-runtime-ui to create variables/resources, insert one editable fragment or Collection, and add safe data bindings in one transaction.
  • List existing script-owned responsibilities under retainedBehavior. The operation preserves those instances and never evaluates or accepts replacement script bodies.
  • unsupportedConversions records behavior that cannot be represented safely. Dry-run returns the complete transaction and the same retained/unsupported report without changing the project.
  • New actions and HtmlEmbed scripts are intentionally rejected. Create normal editable components and data bindings; keep opaque runtime behavior in existing script instances.

Build authenticated pages

Commands:

  • MCP tool: meta.guide {"brief":"Build a Supabase-authenticated account page","taskScope":"structural-project-change","workflow":"authenticated-page"}
  • MCP tool: create-page {"name":"Account","path":"/account"}
  • MCP tool: update-page {"pageId":"","values":{"meta":{"auth":{"method":"basic","login":"","password":""}}}}
  • MCP tool: create-resource {"resource":{"name":"Session","method":"get","url":"https://api.example.com/session","headers":[]}}
  • MCP tool: create-variable {"scopeInstanceId":"","name":"user","value":{"type":"json","value":{}}}
  • MCP tool: update-props {"updates":"props.json contents"}
  • MCP tool: bind-props {"bindings":"bindings.json contents"}

Notes:

  • Inspect and reuse the project's existing auth convention before authoring. Do not add a second provider or session model implicitly.
  • Model signed-out, loading, signed-in, and failed-auth states explicitly.
  • Never store credentials, service-role keys, refresh tokens, private session values, or authenticated response bodies in project data, command output, screenshots, agent instructions, or error reports. Privileged provider calls and authorization enforcement belong server-side.
  • Basic auth is semantic today. Provider-specific Supabase/Firebase setup still uses the existing resource, variable, prop, binding, and embed tools; there is no provider-specific installer.

Generate from design input

Commands:

  • MCP tool: meta.guide {"brief":"Recreate this Figma design as a responsive page","taskScope":"visual-change","workflow":"design-input"}
  • MCP tool: create-page {"name":"Landing","path":"/landing"}
  • MCP tool: create-design-token {"tokens":"tokens.json contents"}
  • MCP tool: define-css-variable {"vars":"vars.json contents"}
  • MCP tool: list-breakpoints {}
  • MCP tool: insert-fragment {"parentInstanceId":"","fragment":"

    Section copy

    "}
  • MCP tool: update-styles {"updates":[{"instanceId":"","breakpoint":"","property":"padding-left","value":{"type":"unit","unit":"px","value":24}}]}
  • MCP tool: preview.start {}
  • MCP tool: screenshot {"path":"/landing","output":"landing-desktop.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}
  • MCP tool: screenshot {"path":"/landing","output":"landing-mobile.png","viewport":{"width":390,"height":844},"waitUntil":"load","waitForTimeout":250}
  • MCP tool: screenshot {"baseUrl":"http://127.0.0.1:5177","path":"/landing","output":"landing-desktop.png","viewport":{"width":1440,"height":900},"waitUntil":"load","waitForTimeout":250}

Notes:

  • Use this after the agent can inspect the supplied design. There is no direct Figma, screenshot, Inception, or design.md import command.
  • Inspect and reuse existing variables, tokens, styles, components, assets, and page patterns before authoring. Build semantic editable structure rather than flattening the design into an image or absolute-positioned approximation.
  • Ask whether the user wants visual verification unless they explicitly requested it. If they decline, stop after focused reads and a static audit. If they opt in, verify one familiar viewport inside every distinct Builder breakpoint range, then run rendered audit and inspect the screenshots before completion.

Cross-project maintenance

Commands:

  • webstudio mcp run .temp/projects.json
  • webstudio mcp run .temp/projects.json --dry-run
  • webstudio mcp run .temp/projects.json --approve-mutations --concurrency 2

Notes:

  • Put shared calls and a projects array of independently linked project roots in the existing mcp run manifest. Project roots are relative to the manifest file.
  • Each project uses its own config, authentication, ProjectSession storage, checkpoint, and failure boundary. Confirmed successful calls are checkpointed. Reads can resume automatically; a mutation interrupted after dispatch is reported as ambiguous and is not replayed automatically, preventing silent duplicate writes.
  • Focus the manifest on bounded reads or audits first. Use per-call dryRun, global --dry-run, or explicitly approve committed mutations with --approve-mutations after reviewing the manifest.

Known CLI Gaps

Provider-specific authenticated pages

Missing: CLI supports page basic auth and generic resources/props/embeds, but not guided Supabase/Firebase auth setup.

Current fallback: Call meta.guide with workflow:"authenticated-page", then create the page, resources, variables, props, bindings, and embeds with existing semantic tools.

Suggested commands:

  • setup-auth-page

Generate from design input

Missing: No command imports Figma, screenshots, Inception output, or design.md and turns it into pages/tokens/layout.

Current fallback: Call meta.guide with workflow:"design-input", let the agent inspect the supplied design, then use semantic page, token, asset, fragment, style, preview, screenshot, and audit tools. Use apply-patch only when no semantic operation fits.

Suggested commands:

  • generate-from-design

Built-in cross-project maintenance

Missing: Public API and CLI intentionally operate on one configured project at a time; there is no built-in multi-project discovery or loop runner.

Current fallback: Run the CLI from an external script that reconfigures one project/session at a time.

Suggested commands:

  • none