May 13, 2026

Fetching OmniStudio Metadata with sf CLI: OmniScript, DataRaptor, FlexCard, Integration Procedure

How to retrieve OmniScript, DataRaptor (OmniDataTransform), FlexCard (OmniUiCard), and Integration Procedure metadata from Salesforce using sf CLI, with standard runtime requirements and deployment caveats.

This article is part of the Salesforce Admin Git & sf CLI series, a complete guide to version control and metadata management for Salesforce admins. Articles are standalone; no need to read in order.

TL;DR

Check runtime first: sf CLI retrieval only works on OmniStudio Standard Runtime with "Use OmniStudio Metadata API" enabled. Vlocity managed package runtime requires VBT instead
Correct type names: OmniScript, OmniDataTransform (DataRaptor), OmniUiCard (FlexCard), OmniIntegrationProcedure. Not OmniProcess (deprecated)
No source tracking: OmniStudio types don't support source push/pull. Always use --metadata or --manifest explicitly
Reactivate after deploy: Deploying via sf CLI does not activate components. You must manually deactivate and reactivate each component in the target org

What You'll Learn

How to check whether your org uses Standard Runtime or the Vlocity managed package runtime
The correct Metadata API type names for OmniScript, DataRaptor, Integration Procedure, and FlexCard
How to retrieve OmniStudio components using sf CLI
The difference between sf CLI retrieval and UI export (DataPacks)
What happens after you deploy OmniStudio metadata (activation requirement)
What NOT to commit to version control (auto-generated LWCs)

The Problem

OmniStudio components (OmniScripts, DataRaptors, FlexCards, Integration Procedures) are some of the most critical configuration in your org. But retrieving them is different from other metadata types. Whether sf CLI works at all depends on which OmniStudio runtime your org uses.

This article tells you what to check and how to proceed.

Common questions this article answers:

Can I use sf CLI to retrieve OmniScript metadata?
Why does sf project retrieve start --metadata OmniScript return nothing?
What is the difference between Standard Runtime and Vlocity runtime?
How is sf CLI retrieval different from exporting DataPacks from the OmniStudio UI?
What do I need to do after deploying OmniStudio metadata to a target org?

Quick Answer

Before anything else: check your runtime. sf CLI only works with OmniStudio Standard Runtime.

If your org has Standard Runtime with Metadata API enabled, the core retrieve command is:

sf project retrieve start --metadata OmniScript OmniDataTransform OmniIntegrationProcedure OmniUiCard --target-org myorg

After deploying to a target org, you must manually deactivate and reactivate each component in OmniStudio Designer. Deployment does not automatically activate components. They will not function until you do this.

If your org is on the Vlocity managed package runtime, sf project retrieve start will return nothing for OmniStudio types. Use the Vlocity Build Tool (VBT) or IDX Workbench instead.

Section 1: Check Your OmniStudio Runtime First

Before running any retrieve commands, confirm which runtime your org uses. This determines whether sf CLI works at all.

Standard Runtime (Metadata API works): Go to Setup → OmniStudio Settings. If you see a "Use OmniStudio Metadata API" setting and it is ON, sf CLI retrieval is available.

Vlocity Managed Package Runtime (Metadata API does NOT work): If your org uses the Vlocity managed package (identifiable by objects with vlocity_cmt__ prefix or component names containing underscores), OmniStudio configuration is stored as data, not metadata. sf project retrieve start will not retrieve any OmniStudio components. You must use the Vlocity Build Tool (VBT) or IDX Workbench instead.

If you are on Vlocity managed package runtime: This article does not apply to your org. Jump to the "Vlocity Managed Package Runtime: What To Do Instead" section at the end.

Enabling Metadata API (Standard Runtime only)

If your org is on Standard Runtime but Metadata API is not yet enabled, you can enable it in Setup → OmniStudio Settings → "Use OmniStudio Metadata API".

Warning: This setting is irreversible. Once enabled, you cannot turn it off. Consult with your Salesforce partner and test in a sandbox before enabling in production.

Section 2: Metadata API Type Names

The UI names and the Metadata API names are different. This trips up almost everyone the first time.

What you see in the UI	Metadata API type name
OmniScript	`OmniScript`
DataRaptor	`OmniDataTransform`
Integration Procedure	`OmniIntegrationProcedure`
FlexCard	`OmniUiCard`

Common mistake: Older Salesforce documentation uses OmniProcess as a type name. This is no longer a registered metadata type. Use OmniScript for OmniScripts and OmniIntegrationProcedure for Integration Procedures separately.

Section 3: List OmniStudio Components First

Before retrieving, list what is in your org. This also serves as a quick diagnostic: if these commands return nothing on an org that has OmniStudio components visible in the UI, your org is likely on Vlocity managed package runtime.

# List all OmniScripts
sf org list metadata --metadata-type OmniScript --target-org myorg

# List all DataRaptors
sf org list metadata --metadata-type OmniDataTransform --target-org myorg

# List all Integration Procedures
sf org list metadata --metadata-type OmniIntegrationProcedure --target-org myorg

# List all FlexCards
sf org list metadata --metadata-type OmniUiCard --target-org myorg

If these list commands return nothing on an org that has OmniStudio components visible in the UI, your org is on Vlocity managed package runtime. sf CLI retrieval will not work in that case.

Section 4: Retrieve in Source Format (Standard Runtime only)

Once you have confirmed Standard Runtime and verified components are visible via sf org list metadata, retrieve them:

# Retrieve ALL OmniScripts
sf project retrieve start --metadata OmniScript --target-org myorg

# Retrieve a specific OmniScript
sf project retrieve start --metadata "OmniScript:MyScriptName" --target-org myorg

# Retrieve ALL DataRaptors
sf project retrieve start --metadata OmniDataTransform --target-org myorg

# Retrieve a specific DataRaptor
sf project retrieve start --metadata "OmniDataTransform:MyDataRaptor" --target-org myorg

# Retrieve ALL Integration Procedures
sf project retrieve start --metadata OmniIntegrationProcedure --target-org myorg

# Retrieve ALL FlexCards
sf project retrieve start --metadata OmniUiCard --target-org myorg

# Retrieve all OmniStudio types together
sf project retrieve start --metadata OmniScript OmniDataTransform OmniIntegrationProcedure OmniUiCard --target-org myorg

Important: No Source Tracking

OmniStudio metadata types do NOT support source tracking. You must always specify --metadata or --manifest explicitly. Running sf project pull without specifying metadata types will NOT pick up OmniStudio changes.

Section 5: Retrieve Using package.xml

For repeatable retrieves across environments, use a package.xml manifest:

sf project retrieve start --manifest package.xml --target-org myorg

Full package.xml for all OmniStudio types:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>OmniScript</name>
    </types>
    <types>
        <members>*</members>
        <name>OmniDataTransform</name>
    </types>
    <types>
        <members>*</members>
        <name>OmniIntegrationProcedure</name>
    </types>
    <types>
        <members>*</members>
        <name>OmniUiCard</name>
    </types>
    <version>62.0</version>
</Package>

Section 6: Retrieve in MDAPI Format

If you need MDAPI format instead of source format:

sf project retrieve start --metadata OmniScript --target-org myorg --target-metadata-dir mdapi-output --unzip

Section 7: What Files Look Like on Disk

After retrieval, OmniStudio files appear under force-app/main/default/ with type-specific subdirectories and file extensions:

force-app/
└── main/
    └── default/
        ├── omnis/
        │   └── MyScriptName.os-meta.xml           ← OmniScript
        ├── omniDataTransforms/
        │   └── MyDataRaptor.rpt-meta.xml           ← DataRaptor
        ├── omniIntegrationProcedures/
        │   └── MyProcedure.oip-meta.xml            ← Integration Procedure
        └── omniUiCards/
            └── MyFlexCard.ouc-meta.xml             ← FlexCard

The XML files are human-readable but dense. Each file contains the full component definition including all steps, actions, and configuration. Commit these to version control. Knowing when a component changed is worth more than being able to parse the raw XML at a glance.

Section 8: sf CLI vs UI Export (DataPacks): Key Differences

OmniStudio has two ways to export components: the sf CLI (Metadata API) and the UI export (DataPacks). They are not interchangeable.

Aspect	UI Export (DataPacks)	sf CLI retrieve
Format	JSON DataPack bundle	XML source/MDAPI files
Works on Vlocity runtime?	Yes	No
Works on Standard runtime?	Yes	Yes (with Metadata API enabled)
After deploy	Component activates automatically	Must manually deactivate and reactivate
LWC generation	LWC auto-generated on import	LWC auto-generated on activation (not in repo)
Version handling	Single version bundle	Each version is a separate component

Section 9: Critical Post-Deploy Step: Activation

This is the most common mistake when deploying OmniStudio metadata via sf CLI.

After deploying OmniStudio metadata, components are NOT automatically active. You must:

In the target org, navigate to the component in OmniStudio Designer
Deactivate it if it was previously active
Activate it again

This triggers Salesforce to regenerate the LWC for the component in the target org. Without this step, the component will not function even though the deploy succeeded.

Section 10: What NOT to Version-Control

Auto-generated LWCs: OmniStudio generates Lightning Web Components from OmniScript and FlexCard definitions at activation time. These LWCs appear in force-app/main/default/lwc/ with names like c_myScript. They are regenerated in each target org on activation.

Do not commit these to your git repo. If you accidentally retrieve and commit them, you will have stale LWC copies that diverge from the actual generated output in each org.

OmniStudio data records (Vlocity runtime only): If you use the Vlocity runtime, component data is stored in custom objects. This is Salesforce data, not metadata. Do not try to export and commit database records as source code.

Section 11: Vlocity Managed Package Runtime: What To Do Instead

If your org uses the Vlocity managed package runtime (components have underscores in names, or you see vlocity_cmt__ prefixed objects), use these tools instead of sf CLI:

Vlocity Build Tool (VBT): vlocity packExport / vlocity packDeploy: command-line tool for DataPack operations
IDX Workbench: Browser-based UI for exporting and importing DataPacks

These tools are outside the scope of this article. Search for "Vlocity Build Tool GitHub" for documentation and setup instructions.

Troubleshooting

1. List command returns no components

Your org is likely on Vlocity managed package runtime. OmniStudio components are stored as data, not metadata, so sf org list metadata --metadata-type OmniScript returns nothing. Use VBT or IDX Workbench instead.

2. "No such metadata type: OmniProcess"

OmniProcess is deprecated. Use OmniScript for OmniScripts and OmniIntegrationProcedure for Integration Procedures.

3. Component deployed but not working in target org

OmniStudio components require manual deactivation and reactivation after deployment via sf CLI. See Section 9.

4. Component names with underscores fail

Standard Runtime requires alphanumeric-only component names. Underscores are not allowed. Rename the component in the source org before retrieving.

5. Auto-generated LWCs appearing in retrieve output

Do not commit these. They are generated at activation time and should not be version-controlled. Add the OmniStudio LWC patterns to your .gitignore.

Frequently Asked Questions

Q: How do I know if my org is on Standard Runtime or Vlocity runtime?

Go to Setup → OmniStudio Settings. If you see a "Use OmniStudio Metadata API" toggle, you are on Standard Runtime. If OmniStudio Settings looks different or the toggle is absent, check whether custom objects with vlocity_cmt__ prefix exist in your org. That indicates the Vlocity managed package runtime.

Q: Is enabling OmniStudio Metadata API reversible?

No. Enabling "Use OmniStudio Metadata API" in Setup → OmniStudio Settings is a one-way operation. You cannot turn it off after enabling. Test this in a sandbox before enabling in production.

Q: Can I use change sets to deploy OmniStudio metadata instead of sf CLI?

On Standard Runtime, yes. Change sets can include OmniStudio metadata types (OmniScript, OmniDataTransform, etc.) because they are now proper Metadata API types. You still need to reactivate components after the change set completes.

Q: Why are there multiple versions of the same OmniScript in my retrieve output?

In OmniStudio, each saved version of a component creates a new version record. The Metadata API exposes each version as a separate component. Your sf org list metadata output may show MyScript/1, MyScript/2, etc. Retrieve the version you want by specifying its full name.

Q: What is the difference between OmniDataTransform and DataRaptor?

They are the same thing. DataRaptor is the UI/marketing name; OmniDataTransform is the Metadata API type name. Use OmniDataTransform in all sf CLI commands.

Key Takeaways

Runtime check first: OmniStudio sf CLI retrieval only works on Standard Runtime with Metadata API enabled. If your org is on Vlocity managed package runtime, use VBT instead
Different API names: UI calls them OmniScript/DataRaptor/FlexCard/Integration Procedure; Metadata API names are OmniScript, OmniDataTransform, OmniUiCard, OmniIntegrationProcedure
No source tracking: Always use --metadata or --manifest. OmniStudio types don't support source push/pull
Reactivate after deploy: Deploying via sf CLI does not activate components. Manually deactivate and reactivate each component in the target org
Don't commit auto-generated LWCs: OmniStudio generates LWCs at activation time; these should not be in your version-controlled source

What's Next?

Recommended Reading:

Action Items:

Go to Setup → OmniStudio Settings to confirm your runtime type
If on Standard Runtime with Metadata API enabled, run sf org list metadata --metadata-type OmniScript --target-org myorg to see components
Retrieve one OmniScript: sf project retrieve start --metadata "OmniScript:YourScriptName" --target-org myorg

Resources & References

Tags: #salesforce #sfcli #omnistudio #vlocity #metadata #versioncontrol

Written by the team at CloudCounsel — builders of Paywren and Mehfil.