vlocode a hyper fast :rocket: Vlocity/Salesforce CLI

vlocode is a fast, Salesforce-native command line tool for exporting, deploying, and activating Vlocity/OmniStudio metadata against any Salesforce org. It is built on the @vlocode/vlocity-deploy library and does not depend on the Vlocity build tools.

📖 Full documentation: the Vlocode DataPack Export & Import guide covers concepts, the complete CLI reference, exporting, building export definitions, and deploying.

Key differences with vlocityinc/vlocity_build and Vlocity DX

• :rocket: Vlocode is significantly faster — up to 10x–20x compared to Vlocity DX depending on the use case
• :computer: Vlocode does all the heavy lifting — dependency resolution and datapack conversion — client side
• :rainbow: Vlocode supports a true delta check that is both fast and reliable: it detects changes made in your org and restores them without relying on git

Installation

The Vlocode CLI is packaged as a dependency-free, bundled build, making it very fast to install. Because all (transitive) dependencies are pinned into the bundle, it is easy to integrate into any CI/CD setup and behaves consistently across environments.

npm install --global @vlocode/cli

Requires Node.js >= 20. Verify the install with vlocode --version.

Note If you intend to use the deployment/export engine as a library, depend on @vlocode/vlocity-deploy rather than on this CLI package.

Commands

List all available commands with vlocode --help, and get help for a specific command with vlocode <command> --help.

Command	Summary
deploy <paths...>	Deploy datapacks from disk into a Salesforce org.
export [ids...]	Export records from an org into datapack files.
bulk-export [sobject]	Export raw record data via the Bulk API v2 as NDJSON.
activate [scriptFilter]	Activate OmniScripts and deploy their LWC components.
convert <paths...>	Convert managed-runtime OmniScript datapacks to native OmniProcess datapacks.
build-export-definitions	Generate export-definition YAML from an org's DataRaptor migration configuration.
impacted-tests <folders...>	Find which Apex unit tests cover a set of classes (offline).

See the CLI reference for the full options of every command.

Authentication

Commands that connect to Salesforce support three authentication modes:

• SFDX username or alias (--user <alias>) — reuse an existing Salesforce CLI (sf/sfdx) authorization. Recommended for CI/CD.
• Interactive OAuth (default when --user is omitted) — opens a browser login against --instance (default test.salesforce.com; use login.salesforce.com for production).
• Session replay (--replay-session <file>) — replay a previously recorded session, with no org connection.

Quick start

Deploy a folder of datapacks. Vlocode recursively scans the folder for *_DataPack.json files:

# Interactive OAuth login (production: add --instance login.salesforce.com)
vlocode deploy ./path-to-datapack-json-files

# Using an existing SFDX credential or alias
vlocode deploy ./path-to-datapack-json-files --user <SFDX alias/username>

Export records into expanded datapack files:

vlocode export \
  --definitions ./export-definitions.yaml \
  --type Product2 \
  --query "SELECT Id FROM Product2 WHERE IsActive = true" \
  --expand --output ./datapacks --user <SFDX alias/username>

FAQ

Q: Does vlocode deploy LWC-enabled OmniScripts?

A: Yes. Vlocode deploys the OmniScript and compiles and deploys its LWC component using either the Metadata API or the Tooling API. The Tooling API is used by default as it can run in parallel to an ongoing metadata deployment.

Q: Does vlocode deploy custom datapack properties that are not part of the standard datapack definition?

A: Yes. Vlocode loads the datapack and matches its fields against the fields available in the target org. Matching fields are deployed; any field present in the datapack but missing in the org produces an error that can be reviewed at the end of the deployment.

Q: Vlocode does not delete Product Child Items (PCI) that I removed from the datapack, why?

A: Vlocode is designed to be safe to run on production orgs and does not delete records unless explicitly requested. When removing child items from the product hierarchy, it is recommended to set their state to disabled rather than deleting them, as deleting a PCI has side effects on cached content and on Assets already created from the old definition. For non-production orgs you can enable --purge-dependencies, which deletes the embedded records before deploying the new ones.

Q: Should I prefer the --bulk-api option for production deployments?

A: No. The Bulk API generally performs worse, as it depends on available Salesforce resources and runs at a lower priority than regular database API operations. Prefer it only to reduce API consumption.

Q: When I activate my OmniScript from the UI it looks different from the one deployed by Vlocode.

A: By default Vlocode uses local script definition generation, generating script definitions client-side instead of via a Vlocity remote Apex function. Although extensively tested, discrepancies are possible. If you encounter one, deploy with --remote-script-activation and please raise an issue on GitHub so the local generation can be updated for your use case.

Q: Does vlocode compile FlexCards into LWC components?

A: Not yet. FlexCard LWC generation is planned but not currently available.

Q: We want to use Vlocode to improve our deployment — can you help us?

A: Yes, support for project implementations can be provided on request.