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.

11.1 KB
Raw Blame

Webstudio API CLI Manual

The API commands operate on the single project configured by:

  • .webstudio/config.json: projectId
  • global Webstudio config: origin and token

::doc-section{field="safetyRules"}

  • Pass --json to API/discovery commands that support it. Do not add --json to top-level commands unless their help/schema documents it.
  • Never pass a project id. Commands use configured project only.
  • Read ids before writing. Do not invent ids for existing records.
  • stdout is one JSON object. stderr is diagnostics.
  • Prefer MCP semantic tools for detailed project edits. Use MCP apply-patch only when no semantic tool exists.

Start

{{start}}

Read First

{{readFirst}}

Project Session Cache

  • CLI commands use one local ProjectSession snapshot for the configured project.
  • Local-capable reads use cached namespaces when compatible and fetch only missing or stale namespaces.
  • Local-capable mutations build patches from the local snapshot, then commit with the cached build version.
  • Successful mutation commits update the local snapshot only after the remote commit succeeds.
  • Server-only commands run remotely and invalidate/refetch namespaces declared by the operation catalog.
  • Use --refresh on local-capable commands to refresh required namespaces before running.
  • Successful JSON responses include compact meta.session with operationId, buildId, version, source, committed, namespaceCounts, diagnosticCount, non-empty diagnostic summaries, and optional compatibilityVersion.

Search project data

Run webstudio search-project '{"query":"known value"}' to search all Builder namespaces in the local project session. Narrow it with {"query":"Brand","namespaces":["styleSources","styles"]} when only specific namespaces are relevant. Results contain the current value, stable match id, namespace path, owning entity, resolved references, and affected pages.

Values in recognized credential fields are excluded and reported in excludedSensitiveValueCount.

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 sent to the model, not project synchronization. It searches asset metadata, not asset binaries or document contents.

CLI Capability Inventory

For a short end-consumer summary of what MCP can do, see manual mcp / webstudio man mcp. The MCP inventory describes the same project, page, element, style, data, asset, publish, domain, and visual verification capabilities without internal command names.

Top-Level Commands

{{topLevelCapabilityIndex}}

High-Level API Commands By Area

{{apiCapabilityIndex}}

MCP Tool Operations

These are MCP tools. From a shell, call them with the shortcut form webstudio <tool> '<json>' or with the explicit form webstudio mcp single-op-call <tool> '<json>':

{{mcpOnlyCommandIndex}}

Task Recipes

{{taskRecipeIndex}}

Use Case Index

{{useCaseIndex}}

Known CLI Gaps

{{knownCliGapIndex}}

Input File Shapes

{{inputFileShapeIndex}}

Raw Patch Fallback

apply-patch accepts either BuildPatchTransaction[] or { "transactions": BuildPatchTransaction[] }. An Editor link with API access can patch text and editable props inside a Content Block. The server checks the complete batch before saving it. Pages, assets, component structure, and design changes still require Builder access.

Each transaction has:

{ "id": "patch-transaction-label", "payload": [ { "namespace": "projectSettings", "patches": [ { "op": "replace", "path": ["meta", "siteName"], "value": "New Site" } ] } ] }

The transaction id is a patch label used for optimistic synchronization. It is not a Builder record id. Do not invent ids for pages, instances, props, breakpoints, resources, variables, folders, assets, or other project records.

Patch paths are JSON-patch-like paths into Builder store data. Map-like namespaces use ids as the first path item.

Supported namespaces:

  • pages: redirects, page records, and folders
  • projectSettings: project-wide metadata and compiler settings
  • instances: element instances and children, including text/expression children
  • props: element props, bindings, page references, resource bindings
  • styles: CSS declarations keyed by style declaration key
  • styleSources: local style sources and reusable design tokens
  • styleSourceSelections: instance-to-style-source connections
  • dataSources: data variables, parameters, and resource data sources
  • resources: data resource definitions
  • assets: project asset records handled by the existing asset patch path
  • breakpoints: responsive breakpoints
  • marketplaceProduct: marketplace metadata

Data Sources

dataSources is the internal Builder namespace for variables. Public API, CLI, and MCP tools expose it through two user-facing groups:

  • data variables: list-variables, create-variable, update-variable, and delete-variable
  • data resources: list-resources, create-resource, update-resource, and delete-resource

For raw snapshot, request the public variables namespace rather than the internal dataSources name. Raw patch payloads still use dataSources when applying direct changes.

Variables can be scoped to an instance. Expressions under that instance can use the variable by name; nested variables with the same name mask outer variables. Variable values support string, number, boolean, and json. Use json for all arrays and objects, including tags, selected categories, and nested API filter state. 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. Public tools should preserve existing parameter records and may reference documented context values such as system in expressions where they are already in scope.

Resource url accepts plain fixed URLs and paths, for example https://api.example.com/posts or /$resources/current-date. Dynamic URLs can combine strings and variables, for example "https://api.example.com/posts?tag=" + filters.tag. Prefer searchParams for query parameters that should be encoded separately: [{ "name": "tag", "value": "filters.tag" }]. Header values, search parameter values, and bodies are expressions for dynamic content. For fixed text, use { "type": "literal", "value": "application/json" }; Webstudio stores the required string expression. Headers can still read variables such as "Bearer " + auth.token, and GraphQL bodies can return objects such as { query: "...", variables: { slug: system.params.slug } }.

Create a GET resource with scopeInstanceId when the fetched resource result should be available as a read data variable. Scoped GET resources default to exposeAsDataSource: true, are generated into the page resource data map, and may be loaded during page rendering. Use dataSourceName to choose the variable name.

For submit/write/action resources, create the resource without scopeInstanceId, then bind a component prop such as a Form action to the resource 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 shape for POST, PUT, DELETE, webhook, and other resources that should run only from an explicit form/action flow, not merely because the page rendered.

POST, PUT, and DELETE resources default to exposeAsDataSource: false even when a scope is supplied. Set exposeAsDataSource: true only when a write-method resource intentionally provides render-time data, such as a read-only GraphQL POST query. A scope is required, and the result includes a warning because the request may execute during page rendering. Set exposeAsDataSource: false on update-resource to detach an existing render-time data source.

Resource method can be get, post, put, or delete. Use GET for read data. Use POST for creates, GraphQL requests, webhooks, and form submissions. Use PUT for full updates/replacements. Use DELETE for deletion actions. Optional control values are graphql and system: graphql marks a GraphQL-style resource, usually POST with a query body; system marks a resource intended to use the built-in system parameter or one of the built-in local resource URLs: "/$resources/sitemap.xml", "/$resources/current-date", and "/$resources/assets". The system parameter fields are system.origin, system.pathname, system.params, system.search. A query key with one value is a string; a repeated key is an array of values in their original order. For ?tag=red&tag=blue, system.search.tag is ["red", "blue"]; missing keys are absent.

For a saved Webhook Form on /products/:slug, a Resource URL can use "https://api.example.com/products/" + system.params.slug + "/comments". On /products/chair?source=newsletter&tag=red&tag=blue, use system.search.source for "newsletter" and system.search.tag for ["red", "blue"] in a header or object body expression. A missing key stays absent; use system.search.source ?? "direct" when a fallback is needed. These values come from the page being submitted, including after navigation. For a saved Webhook Form action, object body bindings are combined with the submitted fields; a submitted field wins when both use the same key.

Use prop bindings for dynamic values that read variables or resources; use direct props for static values.

Commit raw patch:

MCP tool: apply-patch

Raw Patch Examples

Rename the site:

[ { "id": "patch-site-name", "payload": [ { "namespace": "projectSettings", "patches": [ { "op": "add", "path": ["meta", "siteName"], "value": "Acme Studio" } ] } ] } ]

Update page title metadata:

[ { "id": "patch-page-title", "payload": [ { "namespace": "pages", "patches": [ { "op": "replace", "path": ["pages", "page-id", "meta", "title"], "value": "Pricing" } ] } ] } ]

Update a text child on an element:

[ { "id": "patch-text", "payload": [ { "namespace": "instances", "patches": [ { "op": "replace", "path": ["instance-id", "children", 0], "value": { "type": "text", "value": "Launch faster" } } ] } ] } ]

Create records with semantic operations such as create-variable, create-resource, create-design-token, create-page, create-folder, and create-breakpoint. Raw patch rejects generated record creation, collection replacement, record replacement with a different id, and record id field mutations in id-keyed namespaces because Webstudio must generate and preserve record ids.

::doc-section{field="safetyRules"}

Safety Rules

  • For MCP apply-patch, read the latest version with MCP snapshot before writing.
  • Reuse ids from MCP snapshot output when updating existing records.
  • Do not create generated records, replace generated record collections, replace records with different ids, or mutate record id fields with raw patch. Use semantic create operations so Webstudio generates ids.
  • If apply-patch reports a version conflict, read the latest build and regenerate the patch.
  • Prefer semantic MCP read tools for discovery, then use MCP snapshot for exact patch paths.

Command Index

{{commandIndex}}