Site component operations

5 operations named component.*. Every one runs in a batch through apply_ops, dry_run_ops, the CLI or the admin.

Updated
OperationWhat it doesPermissionConfirmation
component.listList the site components: key, name and exposed props.site.readnone
component.createFromNodeMake a site component from a page node and its subtree: the component gets a fresh copy, and the node is replaced by an instance of it.site.editnone
component.updateRename a site component or replace its exposed props (each binds a field of an inner node).site.editnone
component.instantiatePlace an instance of a site component in a page.site.editnone
component.detachReplace an instance with a plain copy of the subtree it renders, overrides applied and fresh ids; it no longer follows the component.site.editnone

component.list

List the site components: key, name and exposed props. Open one with tree.read on its pageId; place one with component.instantiate.

permission: site.readreads onlyclass: read

Example input

{}

Input

The input is a record; see the schema below.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output

FieldTypeRequiredNotes

Try it

yarn splash component.list '{}' --dry-run

component.createFromNode

Make a site component from a page node and its subtree: the component gets a fresh copy, and the node is replaced by an instance of it. Refuses bindings the copy cannot keep.

permission: site.editwrites: pages, tree:{pageId}class: transactionundo: yes

Example input

{
  "pageId": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
  "nodeId": "claim001",
  "key": "member-card",
  "name": "Member card"
}

Input

FieldTypeRequiredNotes
pageIdstringyesAt least 1 character.
nodeIdstringyes
keystringyesAt most 64 characters.
namestringyesAt least 1 character. At most 80 characters.
propsSchemaarray of objectnoAt most 32 items.
propsSchema[].namestringyes
propsSchema[].labelstring | record of stringno
propsSchema[].defaultany JSONno
propsSchema[].bindobjectyes
{
  "type": "object",
  "properties": {
    "pageId": {
      "type": "string",
      "minLength": 1
    },
    "nodeId": {
      "$ref": "#/$defs/__schema0"
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "propsSchema": {
      "maxItems": 32,
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema1"
      }
    }
  },
  "required": [
    "pageId",
    "nodeId",
    "key",
    "name"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "string",
      "pattern": "^[0-9a-z]{8}$"
    },
    "__schema1": {
      "type": "object",
      "properties": {
        "name": {
          "$ref": "#/$defs/__schema2"
        },
        "label": {
          "anyOf": [
            {
              "$ref": "#/$defs/__schema3"
            },
            {
              "type": "object",
              "propertyNames": {
                "$ref": "#/$defs/__schema4"
              },
              "additionalProperties": {
                "$ref": "#/$defs/__schema3"
              }
            }
          ]
        },
        "default": {
          "$ref": "#/$defs/__schema5"
        },
        "bind": {
          "type": "object",
          "properties": {
            "nodeId": {
              "$ref": "#/$defs/__schema0"
            },
            "prop": {
              "anyOf": [
                {
                  "$ref": "#/$defs/__schema2"
                },
                {
                  "type": "string",
                  "enum": [
                    "$theme",
                    "$variant"
                  ]
                }
              ]
            }
          },
          "required": [
            "nodeId",
            "prop"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "name",
        "bind"
      ],
      "additionalProperties": false
    },
    "__schema2": {
      "type": "string",
      "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$"
    },
    "__schema3": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "__schema4": {
      "type": "string",
      "enum": [
        "it",
        "en-US"
      ]
    },
    "__schema5": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema5"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema5"
          }
        }
      ]
    }
  }
}

Output

FieldTypeRequiredNotes
revisionintegeryesAt least 0.
inversearray of object | object | object | object | object | object | object | object | object | object | object | object | objectyes
nodeIdstringyes
componentobjectyes
component.pageIdstringyesAt least 1 character.
component.keystringyesAt most 64 characters.
component.namestringyesAt least 1 character. At most 80 characters.
component.propsSchemaarray of objectyesAt most 32 items.
component.unreadableLabelsarray of objectno

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash component.createFromNode '{"pageId":"6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f","nodeId":"claim001","key":"member-card","name":"Member card"}' --dry-run

component.update

Rename a site component or replace its exposed props (each binds a field of an inner node). Edit its tree with tree.commit on its pageId; every instance follows.

permission: site.editwrites: pagesclass: transactionundo: yes

Example input

{
  "key": "member-card",
  "propsSchema": [
    {
      "name": "name",
      "default": "Name Surname",
      "bind": {
        "nodeId": "name0001",
        "prop": "text"
      }
    },
    {
      "name": "portrait",
      "bind": {
        "nodeId": "photo001",
        "prop": "src"
      }
    }
  ]
}

Input

FieldTypeRequiredNotes
keystringyesAt most 64 characters.
namestringnoAt least 1 character. At most 80 characters.
propsSchemaarray of objectnoAt most 32 items.
propsSchema[].namestringyes
propsSchema[].labelstring | record of stringno
propsSchema[].defaultany JSONno
propsSchema[].bindobjectyes
{
  "type": "object",
  "properties": {
    "key": {
      "$ref": "#/$defs/__schema0"
    },
    "name": {
      "$ref": "#/$defs/__schema1"
    },
    "propsSchema": {
      "$ref": "#/$defs/__schema2"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "type": "string",
      "maxLength": 64,
      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
    },
    "__schema1": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "__schema2": {
      "maxItems": 32,
      "type": "array",
      "items": {
        "$ref": "#/$defs/__schema3"
      }
    },
    "__schema3": {
      "type": "object",
      "properties": {
        "name": {
          "$ref": "#/$defs/__schema4"
        },
        "label": {
          "anyOf": [
            {
              "$ref": "#/$defs/__schema5"
            },
            {
              "type": "object",
              "propertyNames": {
                "$ref": "#/$defs/__schema6"
              },
              "additionalProperties": {
                "$ref": "#/$defs/__schema5"
              }
            }
          ]
        },
        "default": {
          "$ref": "#/$defs/__schema7"
        },
        "bind": {
          "type": "object",
          "properties": {
            "nodeId": {
              "type": "string",
              "pattern": "^[0-9a-z]{8}$"
            },
            "prop": {
              "anyOf": [
                {
                  "$ref": "#/$defs/__schema4"
                },
                {
                  "type": "string",
                  "enum": [
                    "$theme",
                    "$variant"
                  ]
                }
              ]
            }
          },
          "required": [
            "nodeId",
            "prop"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "name",
        "bind"
      ],
      "additionalProperties": false
    },
    "__schema4": {
      "type": "string",
      "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$"
    },
    "__schema5": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "__schema6": {
      "type": "string",
      "enum": [
        "it",
        "en-US"
      ]
    },
    "__schema7": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema7"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema7"
          }
        }
      ]
    }
  }
}

Output

FieldTypeRequiredNotes
pageIdstringyesAt least 1 character.
keystringyesAt most 64 characters.
namestringyesAt least 1 character. At most 80 characters.
propsSchemaarray of objectyesAt most 32 items.
propsSchema[].namestringyes
propsSchema[].labelstring | record of stringno
propsSchema[].defaultany JSONno
propsSchema[].bindobjectyes
unreadableLabelsarray of objectno
unreadableLabels[].namestringyes
unreadableLabels[].storedstringyesAt most 200 characters.

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash component.update '{"key":"member-card","propsSchema":[{"name":"name","default":"Name Surname","bind":{"nodeId":"name0001","prop":"text"}},{"name":"portrait","bind":{"nodeId":"photo001","prop":"src"}}]}' --dry-run

component.instantiate

Place an instance of a site component in a page. Set its exposed props with set_props and override inner nodes with set_override through tree.commit.

permission: site.editwrites: tree:{pageId}class: transactionundo: yes

Example input

{
  "pageId": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
  "parentId": "root0000",
  "index": 0,
  "key": "member-card"
}

Input

FieldTypeRequiredNotes
pageIdstringyesAt least 1 character.
parentIdstringyes
indexintegeryesAt least 0.
keystringyesAt most 64 characters.

Output

FieldTypeRequiredNotes
revisionintegeryesAt least 0.
inversearray of object | object | object | object | object | object | object | object | object | object | object | object | objectyes
nodeIdstringyes

Try it

yarn splash component.instantiate '{"pageId":"6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f","parentId":"root0000","index":0,"key":"member-card"}' --dry-run

component.detach

Replace an instance with a plain copy of the subtree it renders, overrides applied and fresh ids; it no longer follows the component. The component's motion does not follow the copy.

permission: site.editwrites: tree:{pageId}class: transactionundo: yes

Example input

{
  "pageId": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
  "nodeId": "claim001"
}

Input

FieldTypeRequiredNotes
pageIdstringyesAt least 1 character.
nodeIdstringyes

Output

FieldTypeRequiredNotes
revisionintegeryesAt least 0.
inversearray of object | object | object | object | object | object | object | object | object | object | object | object | objectyes
nodeIdstringyes

Try it

yarn splash component.detach '{"pageId":"6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f","nodeId":"claim001"}' --dry-run

Generated from the operation registry and the MCP tool catalogue (source e4ac41b55c6d9a7e).

Something wrong on this page? Write to docs@librettocms.com.

Libretto docs

Colophon. These docs are a Libretto site: 68 pages in two languages, 20 guide pages imported from Markdown and 41 reference pages generated from the operation registry. Set in Softcore, with code in IBM Plex Mono. Its outline:

/ Libretto docs /start Get started /start/request-access Request access /start/workspace Your workspace /start/first-site Your first site /start/invite-a-client Invite a client /start/connect-claude Connect Claude to Libretto /build Build /build/first-page Build a page /build/layers-and-canvas Layers and canvas /build/site-components Site components /design-system Design system /design-system/tokens Colours, space and themes /design-system/components Components and variants /design-system/fonts Typography and fonts /motion Motion /motion/scenes Scenes and recipes /motion/image-sequences Image sequences /motion/reduced-motion Reduced motion /publish Publish /publish/languages Site languages /publish/versions Publish and versions /publish/members-and-forms Members and forms /publish/domains Domains /handover Hand a site to a client /glossary Glossary /agents Agents and API /agents/mcp MCP server /agents/cli CLI /agents/batches Batches /agents/errors Errors and findings /agents/operations Operations /search Search