Workflow imports and workspace sync

Import an exported workflow as a draft, or fork and sync related workspaces. Preview the destination bindings, apply the same choices, and inspect the operation receipt before using the destination.

These commands use the v2 protocol described in the API workflow guide. CLI single-resource results omit the outer HTTP data envelope: read .previewFingerprint in CLI output and .data.previewFingerprint in raw HTTP output. Paginated CLI lists retain {data, nextCursor}.

Prerequisites

Use an explicit profile and workspace for each environment. Replace example resource IDs with IDs from your export and destination. Save a stable request ID and the exact input for each intended mutation before applying it.

Workspace keys cannot administer fork relationships or stand in for a user when binding credentials. OAuth import/fork/sync previews require api:write; export, discovery, mapping reads, selectors, and operation reads use api:read.

Forking and sync require Enterprise on billing-enabled deployments. Billing-disabled deployments must enable forking through deployment configuration. Check workspaces fork-availability before starting. Import and operation reports do not inherit this fork-specific gate.

Import a workflow with destination bindings

1. Export and inspect the workflow

--include-references adds a versioned manifest of resource identities and their occurrences. Default export clears registered credential fields and workspace bindings. It does not remove every ordinary variable value or literal configuration; inspect the payload before sharing it. Credentials and secret values are not transferred as destination resources.

Pin JSON because import does not accept YAML:

sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
  workflows export "$WORKFLOW_ID" --include-references > workflow.json

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  workflows import-preview --workflow @workflow.json > preview.json

--include-workspace-bindings can preserve non-secret bindings for a same-workspace round trip. Otherwise, configure required bindings reported by import.

2. Map destination resources

Read unresolvedBindings and unresolvedConfiguration. Resource mappings select a destination by kind and source ID. Save an array such as this in mappings.json:

[
  { "kind": "credential", "sourceId": "source-connection", "targetId": "destination-connection" },
  { "kind": "sandbox", "sourceId": "source-sandbox", "targetId": "destination-sandbox" }
]

Use the credential, table, file, sandbox, and other resource commands to discover or create destination resources. A mapping applies to registered occurrences of that source resource. targetId:null requests clearing and cannot satisfy a required binding. Source IDs are labels, not permission to read a source workspace.

Older exports without a reference manifest can use --bindings @bindings.json for individual registered source fields. A nested Agent tool credential can be addressed as:

[
  {
    "kind": "credential",
    "blockId": "source-agent",
    "subBlockKey": "tools",
    "valuePath": [0, "params", "oauthCredential"],
    "encoding": "scalar",
    "targetId": "destination-connection"
  }
]

Use the path and encoding registered for the actual export. A top-level field uses its own subBlockKey and valuePath:[]. Field bindings have no sourceId; they address an occurrence directly. Conflicting mappings/bindings are rejected. Include --bindings in both preview and apply when using them.

3. Resolve dependent choices

Use the selector key and destination context returned by preview to discover valid values. For example:

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  selectors list --selector-key gmail.labels \
  --context '{"oauthCredential":"destination-connection"}'

MCP tool discovery uses mcp.tools with mcpServerId. OAuth connections can require human provider authorization before discovery succeeds. Check selector pagination and truncation rather than assuming one result contains every provider option.

Import-dependent values use source block IDs and the returned field key. Save values in values.json:

[{ "blockId": "source-agent", "subBlockKey": "tools[0].folder", "value": "destination-label" }]

Keep the field key unchanged, including nested tool indices. A field with multiSelect:true accepts selected IDs as one comma-separated string.

4. Preview and apply the same choices

Preview again with the exact mappings and values. When the preview is ready, apply its fingerprint using the request ID saved for this mutation:

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  workflows import-preview --workflow @workflow.json \
  --mappings @mappings.json --dependent-values @values.json > preview.json

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  workflows import --workflow @workflow.json \
  --mappings @mappings.json --dependent-values @values.json \
  --preview-fingerprint "$(jq -er '.previewFingerprint' preview.json)" \
  --request-id "$IMPORT_REQUEST_ID" --wait

Mapped import creates the draft atomically after required bindings/configuration resolve. The receipt includes imported IDs and idMap; remapping occurs before graph ID regeneration. The workflow remains a draft and must be deployed for ordinary execution.

Plain imports without mapping options retain their earlier behavior and return no durable operation receipt. Supplying mapping options, including --mappings '[]', requires both --request-id and --preview-fingerprint. JSON flags accept @file or @- for local stdin.

Fork, push, and pull

Create a fork

Inspect workspaces fork-availability, lineage, and fork-resources. Resource copies are opt-in. Preview and apply the identical name and copy selections:

sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
  workspaces fork-resources --kind tables --limit 50

sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
  workspaces fork-preview --name "Review environment" \
  --copy '{"tables":["source-table"]}' > fork-preview.json

sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
  workspaces fork --name "Review environment" \
  --copy '{"tables":["source-table"]}' \
  --preview-fingerprint "$(jq -er '.previewFingerprint' fork-preview.json)" \
  --request-id "$FORK_REQUEST_ID" --wait

Eligible deployed source workflows become child drafts. Neither fork nor sync copies credentials or secret values. Review destination configuration before deploying forked workflows.

Select the sync direction and mappings

Push sends the current workspace's deployed workflows to --other-workspace-id. Pull brings the other workspace's deployed workflows into the current workspace. Direction is relative to the selected workspace, regardless of which side is the parent. The pair must form a direct fork relationship.

Sync can replace target workflows and archive mapped targets whose source was deleted or archived. Review those actions before confirming:

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  workspaces pull-preview --other-workspace-id "$SOURCE_WORKSPACE" > sync-preview.json

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  workspaces pull --other-workspace-id "$SOURCE_WORKSPACE" \
  --preview-fingerprint "$(jq -er '.previewFingerprint' sync-preview.json)" \
  --request-id "$SYNC_REQUEST_ID" --yes --wait

Include identical inline mappings, dependent values, and trigger choices on preview/apply when using them. Sync mapping entries use resourceType, sourceId, and targetId; import entries use kind. Inline sync mappings persist in the same transaction as the sync.

For example, --mappings takes:

[{ "resourceType": "oauth_credential", "sourceId": "source-connection", "targetId": "destination-connection" }]

Use oauth_credential or service_account_credential according to credential type. workspaces mappings get requires the other workspace and direction, and returns storage id fields. Strip them before reuse:

sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
  workspaces mappings get --other-workspace-id "$SOURCE_WORKSPACE" --direction pull --limit 0 \
  | jq '[.data[] | {resourceType, sourceId, targetId}]' > sync-mappings.json

Configure copies and dependent values

Fork creation uses --copy; sync uses --copy-resources, for example '{"tables":["source-table"]}'. Fork copy.files contains workspace file IDs. Sync copyResources.files contains storage keys.

Sync-dependent values identify source workflows, blocks, and field keys, rather than provisional preview target IDs:

[{ "sourceWorkflowId": "source-workflow", "sourceBlockId": "source-agent", "subBlockKey": "tools[0].folder", "value": "destination-label" }]

Discover each field in its returned discoveryWorkspaceId using the returned selector context. This is the source when its parent resource is being copied and the destination when the parent is mapped. Keep nested field keys unchanged; multi-select values are one comma-separated string.

Omitting --dependent-values reuses saved choices. Supplying the flag replaces choices for affected workflows, and [] clears them. A value in a target draft alone is not saved sync configuration. dropReferences acknowledges references deleted in the source; it cannot discard live source resources.

Review trigger URLs and target changes

Preview's ready means the change can commit; it is not deployment readiness. Sync replaces eligible targets and deploys admitted snapshots while preserving exclusions. Merely undeploying a source does not archive its mapped target.

Inspect triggerSlots before replacing webhook triggers:

• Slots with ownPath preserve that URL and accept no override.
• Other slots can adopt a path from adoptablePaths, or select adoptPath:null for a new URL.
• --trigger-mappings entries use sourceWorkflowId, sourceBlockId, and adoptPath. Unknown, duplicate, or unavailable choices are rejected.

Pass identical trigger choices to preview and apply. Candidates belong to the same target workflow and provider. Review reported trigger URL changes before using the destination.

Rollback restores the latest inbound sync using prior deployed versions. It can archive sync-created workflows and restore archived targets, but does not restore arbitrary drafts or undo every resource copy. Inspect pending activation work. Unlink removes the relationship/mappings while retaining content; exclusions keep selected workflows out of later syncs. See Workspace commands.

Reconcile completion and retries

An apply receipt includes operationId, requestId, workspaceId, applied, status, resource IDs, and issues. applied:true means the transaction committed, even if later copying or deployment fails.

Poll in the receipt's workspace, which can differ from the workspace receiving workflows:

sim --profile automation --workspace "$OPERATION_WORKSPACE_ID" --output json \
  workspaces operations wait "$OPERATION_ID" --wait-timeout 300

The default wait is 3600 seconds; zero waits indefinitely. The request timeout is separate. Wait outcomes are:

Inspect issues, copied-resource progress, the exact admitted deployments' readiness, and trigger URL changes. Completed imports and forks remain drafts. For sync, verify deployment readiness before using the environment.

Recover a lost response

Use workspaces operations list --request-id "$REQUEST_ID" in the same receipt workspace, or retry the identical mutation with its original ID. Lists retain {data, nextCursor} and contain stored snapshots; operations get or operations wait refreshes completion status. Timeout and uncertain-mutation diagnostics retain reconciliation IDs.

Identical authorized retries return the original operation. Changed inputs under that request ID return 409. If a preview is stale and nothing committed, obtain a new preview and use a new ID for the revised request. The CLI does not invent a new ID to retry an uncertain mutation.

Validation boundary

Validate provider connections in the destination environment as well as the platform operation report. Repository integration fixtures do not establish a live provider connection.

Related docs

• API workflow guide
• Workspace forking
• Workflow commands
• Workspace commands
• Selectors
• Exit codes
• Workflow-sync contributor harness