# Workflow imports and workspace sync (/cli/workflow-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](/api-reference/workflow-sync). 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 [#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. | Operation | Required access | | - | - | | Export | Workflow read access | | Import preview/apply | Destination write access; credential binding requires an acting personal/OAuth identity with credential access | | Fork discovery, preview, creation | Personal API key or OAuth login and source workspace Admin; creation policy must allow a new workspace | | Sync and mapping changes | Personal API key or OAuth login and Admin access to both workspaces on a direct parent/child fork edge | | Selectors | Read access in the discovery workspace and access to the chosen credential; workspace keys are unsupported | | Operation reads | Read access in the receipt workspace | 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 [#import-a-workflow-with-destination-bindings] ### 1. Export and inspect the workflow [#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: ```sh 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 [#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`: ```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: ```json [ { "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 [#3-resolve-dependent-choices] Use the selector key and destination context returned by preview to discover valid values. For example: ```sh 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`: ```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 [#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: ```sh 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 [#fork-push-and-pull] ### Create a fork [#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: ```sh 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 [#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: ```sh 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: ```json [{ "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: ```sh 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 [#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: ```json [{ "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 [#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](/cli/workspaces). ## Reconcile completion and retries [#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: | Operation | Receipt workspace | | - | - | | Import | Destination | | Fork creation | Source workspace on which `fork` ran | | Push/pull | Current `--workspace` on which the command ran | ```sh 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: | Exit code | Outcome | | - | - | | `0` | Completed, including completion with warnings | | `1` | Failed completion or command/request failure | | `3` | Operation committed but requires configuration | | `4` | Wait timed out; the operation can still continue | 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 [#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 [#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 [#related-docs] * [API workflow guide](/api-reference/workflow-sync) * [Workspace forking](/platform/enterprise/forks) * [Workflow commands](/cli/workflows) * [Workspace commands](/cli/workspaces) * [Selectors](/cli/selectors) * [Exit codes](/cli/scripting#exit-codes) * [Workflow-sync contributor harness](/api-reference/workflow-sync#related-docs)