> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Components

> Reusable node groups that stay in sync across workflows

Workflow components let you save a group of nodes as a reusable building block. When you paste a component into other workflows, it stays linked — updating the component propagates changes to every workflow that uses it.

## Core concepts

| Term            | Meaning                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Component**   | A saved group of nodes with their internal edges, stored in your workspace's component library.                                 |
| **Instance**    | A copy of a component inside a specific workflow. Instances stay linked to the library component they came from.                |
| **Propagation** | When you update a component, every workflow in the workspace that contains an instance of it is automatically updated to match. |

## Saving a component

1. Select two or more nodes in the workflow visualizer.
2. Right-click and choose **Save as Component**.
3. Give it a name and confirm.

The selected nodes are saved to your workspace's component library and tagged with a blue overlay border in the current workflow. This overlay indicates they're linked to a library component.

<Warning>
  Avoid including **Start** or **End** nodes in a component. Pasting them into another workflow would create duplicate start/end points.
</Warning>

## Using a component

Right-click the canvas and open the **Components** section in the add-node menu. Selecting a component pastes its nodes into the workflow at the cursor position. The pasted nodes are linked instances — they show the blue overlay border and will receive future updates from the library.

A workflow can contain **multiple instances of the same component**. Each paste creates a fresh `source_component_instance_id`, and propagation tracks each instance independently — updating the component updates every instance in every workflow.

### Vault credentials

If the source component references vault credentials (e.g., a TFA node configured with a vault alias), the relevant vault schema entries are automatically merged into the target workflow when you paste. Your existing entries are never overwritten — target entries take precedence if there's a conflict.

## Editing and updating

### Detecting changes

When you modify a component instance's nodes in a workflow (change parameters, rename, add or remove nodes), CloudCruise tracks the diff against the library version. A dirty indicator appears on the component overlay.

When you save the workflow, a dialog shows what changed and lets you choose whether to push the update back to the library component.

### Propagation

When you update a component (either from the save dialog or the context menu), all workflows in your workspace that contain an instance of that component are updated automatically:

* **Node matching** — Existing instance nodes are matched to the updated template by their stable mapping ID. New template nodes get fresh workflow node IDs.
* **Edge preservation** — Internal edges (between component nodes) are replaced with the new template. External edges (connections from component nodes to non-component nodes) are preserved.
* **Vault credentials** — Only vault entries actually referenced by the component's node parameters are merged into each target workflow. Target entries always take precedence.

You can disable propagation per-update by unchecking the propagate checkbox in the update dialog.

### Version history

Every update creates a new version. You can view the full version history from the component's context menu and revert to any previous version. Reverting creates a new version and propagates the reverted state to all instances.

## Unlinking and removing

| Action                   | What it does                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Split from Component** | Unlinks a single node from the component. The node stays in the workflow but is no longer part of the component instance. |
| **Clear Component**      | Unlinks all nodes in the component instance. The nodes remain but lose their component association.                       |
| **Remove Component**     | Deletes all nodes belonging to that component instance from the current workflow. Does not delete the library component.  |
| **Delete Component**     | Deletes the component from the library entirely. Nodes in workflows that used it become plain unlinked nodes.             |

## Managing components from the CLI

The same lifecycle is scriptable via the [CloudCruise CLI](/sdk/cli/overview#workflow-components) — useful for coding agents (Claude, Cursor), CI flows, and bulk operations:

```bash theme={null}
cloudcruise components list                                                       # see what's in your workspace
cloudcruise components usage <component_id>                                       # check affected workflows before updating
cloudcruise components update <component_id> --file new.json --version-note "…"   # update + propagate (default)
cloudcruise components update <component_id> --file new.json --no-propagate       # update without propagating
cloudcruise components delete <component_id>                                      # permanent delete (irreversible)
```

See the [CLI overview](/sdk/cli/overview#workflow-components) for the full command set or the [REST endpoints](/workflow-api/list-components) for direct API integration.

## Scope and limitations

* Components are **workspace-scoped**. They can be used in any workflow within the same workspace but are not shared across workspaces.
* **Many instances per workflow are supported.** A component can be pasted into a workflow any number of times — each instance is tracked independently and updated by propagation.
* **Input/output schemas are per-workflow**, not per-component. A component does not carry or propagate input/output schema — each workflow maintains its own.
* Component updates propagate only to workflows in the **same workspace**. If a teammate doesn't have read access to a particular workflow (via RLS), that workflow won't be updated.
* **Component deletion is irreversible** — version history is wiped along with the component. Embedded instances in workflows remain as orphaned nodes (their structure persists but they no longer receive propagation).