[![CI](https://github.com/Codeneos/vlocode/actions/workflows/ci.yml/badge.svg)](https://github.com/Codeneos/vlocode/actions/workflows/ci.yml) [![GitHub top language](https://img.shields.io/github/languages/top/codeneos/vlocode.svg?logo=github)](https://github.com/Codeneos/vlocode) [![Bugs](https://img.shields.io/sonar/https/sonarcloud.io/curlybracket.vlocode/bugs.svg?color=lightgray&label=bugs&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAolBMVEUAAAD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgCXdjhZAAAANXRSTlMA%2Bg335ykFAwnr7hDZON7Ie1ZDMfTUmIUUSSLPoVAa4r6K8rtyXD62gG2xpsKSjnZpYx6qTp5XIo8AAAOWSURBVFjD7VbZtqIwEGSVRXYQAVFBFvf16v%2F%2F2tgJKsYEvPM4Z%2FLiwV7SXV2phPu3lyB71fnserLwN9HD%2BGBL4u2%2BRMk%2BeMJvw887CH6uIKuGvwhXvIK%2FEYtf1sq38epRu1GWtFa%2FLH%2FPNxFFvq6q9aGQ8LeYC19hH2L30VFWm4p8Z4Tb2H%2BRYbBC%2B2urWfvfy1hHGZx%2BHNwFeBox4alMDfhfv%2FbFJxNUvvlpqVEGe9aTYAxe85pmihGWTne8bEGnJ7qx5KG5pDNBCZssBcZ8M7CeOkcILuKUCTAP6bvo5GuAE5P1ESAsyR0JKqhxzLYfACG3ZwY8dMDsoWcOKXDFZ9tNYFnYQeMNkPh09fzZgD5loMKWfYxrREOeF3VjU%2FqUHMn8bp8w5Elwl4tba2nbTwWRNSRPBUWeFHMjkgqirckMXuPDFx5hUtcSGU4b%2BemV3BHeSHpoUut2uirL8XYSwNfCJEDetjQyjFrtNyJmjE3cnBJ54b3dgmhVBgytfIRTpENChPQ8aYNSHxzy4DkoTrmMseju1XcRmg64L866eL0nj1ER4rkZ7oghQuScgadNWz5ijIVBzlkiRCDoQKOB25Dagqhw8ECGP%2FXGHwOEwKPvCj4184HMpk%2Fwo72IGpWfzEEjze8WGwqL%2BwrIMbNafrUO52LGefCb9RUwtFG82ybvBnaecsd%2BrQYEfgD0d6lZ4x6gFdGj3%2FLDV2H%2B0tr4FHVZcjaUllDnvppk8etrRqrxzAJUOQNIGLEEcHTpwAVpNIfSRCyFDcwOZu6ACbgC6o25Quj0VrAjhINAuWInuGAMUtiHyqMp333L1AFQmCuZbr7WSTHMoBVngpsd0UCCCetm50W88DihgB5c5mNjz0oQB3hnjNWOVoKpA8Amo4Dl4wwkBupFoR4AgGnIfq7M5ScYOq0JD9jO5wPmgwmDH%2B2Qpk0%2FKyjxa32lfsYjRZtcmo0kfJERE4vyoHnihgRT1TOK0J97ngLk92MOWk5XKKxZtiu0CvNTXNlReQmu2FzIbgLlKoJ8XuLtdQ0XUZxkAfzVyzSV8N02Vtvd6s2NN8%2FSMNzaEo%2B%2F525sPG5a%2BycM08xqLAtHfX8Kj26UlZmgRTzFYlTkbJK9RjrNHUSvYWmQFj2UKbQxQ6u1Fz8ay8ojuTMR24nTekAX0aQKd5am65KRHaZvo4vivDAkfaFZdnhOKOEt7ZR9XwYBJZeKLJf7LP4vYv0BK5jBy9A2z3IAAAAASUVORK5CYII%3D)](https://sonarcloud.io/dashboard?id=curlybracket.vlocode) [![Vulnerabilities](https://img.shields.io/sonar/https/sonarcloud.io/curlybracket.vlocode/vulnerabilities.svg?label=vulnerabilities&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAolBMVEUAAAD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgD%2FZgCXdjhZAAAANXRSTlMA%2Bg335ykFAwnr7hDZON7Ie1ZDMfTUmIUUSSLPoVAa4r6K8rtyXD62gG2xpsKSjnZpYx6qTp5XIo8AAAOWSURBVFjD7VbZtqIwEGSVRXYQAVFBFvf16v%2F%2F2tgJKsYEvPM4Z%2FLiwV7SXV2phPu3lyB71fnserLwN9HD%2BGBL4u2%2BRMk%2BeMJvw887CH6uIKuGvwhXvIK%2FEYtf1sq38epRu1GWtFa%2FLH%2FPNxFFvq6q9aGQ8LeYC19hH2L30VFWm4p8Z4Tb2H%2BRYbBC%2B2urWfvfy1hHGZx%2BHNwFeBox4alMDfhfv%2FbFJxNUvvlpqVEGe9aTYAxe85pmihGWTne8bEGnJ7qx5KG5pDNBCZssBcZ8M7CeOkcILuKUCTAP6bvo5GuAE5P1ESAsyR0JKqhxzLYfACG3ZwY8dMDsoWcOKXDFZ9tNYFnYQeMNkPh09fzZgD5loMKWfYxrREOeF3VjU%2FqUHMn8bp8w5Elwl4tba2nbTwWRNSRPBUWeFHMjkgqirckMXuPDFx5hUtcSGU4b%2BemV3BHeSHpoUut2uirL8XYSwNfCJEDetjQyjFrtNyJmjE3cnBJ54b3dgmhVBgytfIRTpENChPQ8aYNSHxzy4DkoTrmMseju1XcRmg64L866eL0nj1ER4rkZ7oghQuScgadNWz5ijIVBzlkiRCDoQKOB25Dagqhw8ECGP%2FXGHwOEwKPvCj4184HMpk%2Fwo72IGpWfzEEjze8WGwqL%2BwrIMbNafrUO52LGefCb9RUwtFG82ybvBnaecsd%2BrQYEfgD0d6lZ4x6gFdGj3%2FLDV2H%2B0tr4FHVZcjaUllDnvppk8etrRqrxzAJUOQNIGLEEcHTpwAVpNIfSRCyFDcwOZu6ACbgC6o25Quj0VrAjhINAuWInuGAMUtiHyqMp333L1AFQmCuZbr7WSTHMoBVngpsd0UCCCetm50W88DihgB5c5mNjz0oQB3hnjNWOVoKpA8Amo4Dl4wwkBupFoR4AgGnIfq7M5ScYOq0JD9jO5wPmgwmDH%2B2Qpk0%2FKyjxa32lfsYjRZtcmo0kfJERE4vyoHnihgRT1TOK0J97ngLk92MOWk5XKKxZtiu0CvNTXNlReQmu2FzIbgLlKoJ8XuLtdQ0XUZxkAfzVyzSV8N02Vtvd6s2NN8%2FSMNzaEo%2B%2F525sPG5a%2BycM08xqLAtHfX8Kj26UlZmgRTzFYlTkbJK9RjrNHUSvYWmQFj2UKbQxQ6u1Fz8ay8ojuTMR24nTekAX0aQKd5am65KRHaZvo4vivDAkfaFZdnhOKOEt7ZR9XwYBJZeKLJf7LP4vYv0BK5jBy9A2z3IAAAAASUVORK5CYII%3D)](https://sonarcloud.io/dashboard?id=curlybracket.vlocode) # **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](https://www.npmjs.com/package/@vlocode/vlocity-deploy)_ library and does **not** depend on the Vlocity build tools. > 📖 **Full documentation:** the > [Vlocode DataPack Export & Import guide](https://github.com/Codeneos/vlocode/tree/main/docs) > covers concepts, the complete [CLI reference](https://github.com/Codeneos/vlocode/blob/main/docs/cli.md), > [exporting](https://github.com/Codeneos/vlocode/blob/main/docs/export.md), > [building export definitions](https://github.com/Codeneos/vlocode/blob/main/docs/export-definitions.md), > and [deploying](https://github.com/Codeneos/vlocode/blob/main/docs/import.md). ## Key differences with **[vlocityinc/vlocity_build](https://github.com/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. ```shell 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](https://www.npmjs.com/package/@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 --help`. | Command | Summary | | --- | --- | | `deploy ` | 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 ` | 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 ` | Find which Apex unit tests cover a set of classes (offline). | See the [CLI reference](https://github.com/Codeneos/vlocode/blob/main/docs/cli.md) for the full options of every command. ## Authentication Commands that connect to Salesforce support three authentication modes: - **SFDX username or alias** (`--user `) — 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 `) — 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: ```shell # 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 ``` Export records into expanded datapack files: ```shell vlocode export \ --definitions ./export-definitions.yaml \ --type Product2 \ --query "SELECT Id FROM Product2 WHERE IsActive = true" \ --expand --output ./datapacks --user ``` ## 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.