vlocode-project - v2.4.5
    Preparing search index...

    Vlocode CLI reference

    The Vlocode command line interface (vlocode) is a fast, dependency-free tool for exporting, deploying, and activating Salesforce/Vlocity metadata. It is distributed as the @vlocode/cli npm package and is designed to run both interactively and unattended in CI/CD pipelines.

    This page is the authoritative reference for installation, authentication, global behaviour, and every command. For task-oriented guides see Exporting datapacks and Importing / deploying datapacks.

    Vlocode CLI ships as a bundled, dependency-pinned build, which makes it fast to install and gives consistent, reproducible behaviour across environments — important for CI/CD.

    npm install --global @vlocode/cli

    Requirements:

    Requirement Value
    Node.js >= 20.0.0
    Package @vlocode/cli
    Command vlocode

    Verify the installation and view the build version:

    vlocode --version       # prints the version and build date
    vlocode --help          # lists all commands
    vlocode <command> --help
    vlocode help <command>  # equivalent to <command> --help

    Library usage. If you intend to embed the deployment/export engine in your own application, depend on @vlocode/vlocity-deploy directly rather than on the CLI package.

    Command Summary
    deploy Deploy datapacks from disk into a Salesforce org.
    export Export records from an org into datapack files.
    bulk-export Export raw record data via the Bulk API v2 as NDJSON.
    activate 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 Analyze Apex source to find which unit tests cover a set of classes (offline).

    Every command that connects to Salesforce supports three authentication modes, selected by which options you provide:

    1. SFDX username or alias (recommended for CI/CD) — reuse an existing Salesforce CLI (sf/sfdx) authorization:

      vlocode deploy ./datapacks --user my-org-alias

      The org must already be authorized in the Salesforce CLI on the machine running Vlocode (for example via sf org login).

    2. Interactive OAuth (default when --user is omitted) — Vlocode opens a browser login against the instance given by --instance. The default instance is test.salesforce.com (sandbox/scratch); for production logins pass --instance login.salesforce.com:

      vlocode deploy ./datapacks --instance login.salesforce.com

    3. Session replay (offline/testing) — replay a previously recorded API session instead of contacting an org. See Session recording and replay.

    These options are available on every command and primarily control logging.

    Option Description
    -v, --verbose Enable verbose logging.
    --debug Enable debug logging and print a call stack on unhandled errors.
    --log-level <level> Set the log level explicitly. Overrides -v/--debug. One of debug, verbose, info, warn, error, fatal.
    --log-file <path> Append logs as NDJSON to the given file. See Logging.
    -h, --help Display help for the command.

    These options are available on every command that talks to an org — that is, all commands except impacted-tests, which works entirely offline.

    Option Description
    -u, --user <username> SFDX username or alias of the target org. When omitted, an interactive OAuth login is started.
    -i, --instance <url> Salesforce instance/login URL for interactive OAuth. Default test.salesforce.com. Use login.salesforce.com for production.
    --record-session Record the Salesforce API interaction to a session log for later replay. Conflicts with --replay-session.
    --replay-session <file> Replay a previously recorded session log instead of connecting to an org. Conflicts with --record-session.

    Session record/replay captures the HTTP interaction with Salesforce so a run can be reproduced deterministically — useful for debugging and for building regression fixtures.

    # Record a deployment's API traffic to a session log
    vlocode deploy ./datapacks --user my-org --record-session

    # Re-run later against the recorded session, with no org connection
    vlocode deploy ./datapacks --replay-session ./vlocode-session-1718000000.log

    Vlocode always writes a structured NDJSON log file in addition to console output, so runs remain auditable even when the console scrollback is lost.

    • Console level. Defaults to info. -v/--verbose raises it to verbose; --debug raises it to debug and includes stack traces. An explicit --log-level always takes precedence.
    • Log file. By default logs are appended as NDJSON to ./.vlocode/logs/<command>-<timestamp>.log under the current working directory. Override the location with --log-file <path>. Each line is a JSON object, which is convenient for ingestion into log aggregation tooling.
    • Interactive progress. Commands with a progress bar (such as export) route log lines above the bar so output is not corrupted. Use --no-progress (on export) for plain, line-oriented output suitable for CI logs.

    Tip. Add .vlocode/ to your .gitignore so generated logs are not committed.

    Vlocode is designed to be scriptable: it returns a non-zero exit code on failure so pipelines fail fast.

    Exit code Meaning
    0 The command completed.
    1 The command terminated with an unhandled error.

    Note. A deploy run that finishes but reports per-record errors still exits 0; inspect the deployment summary (and the NDJSON log) to gate a pipeline on individual record failures. See Importing / deploying datapacks.

    Deploy datapacks from one or more folders or files into a Salesforce org. Folders are scanned recursively for *_DataPack.json files. See Importing / deploying datapacks for the full workflow and the deployment pipeline.

    vlocode deploy <paths...> [options]

    Arguments

    Argument Description
    paths... One or more folders or datapack files to deploy.

    Options (in addition to the global and connection options)

    Option Default Description
    --purge-dependencies [mode] false Use none, unmatched, or all matching-dependency cleanup. Supplying the option without a mode retains the previous all behavior.
    --purge-matching-records-filter <objects...> [] Limit unmatched cleanup to the listed embedded SObject types. An empty filter considers every embedded child type. Completely empty collections are not inferred.
    --lookup-failed false Look up the Ids of dependencies that failed to deploy so dependent records can still resolve them.
    --allow-unresolved false Do not fail a datapack when a dependency cannot be resolved; the field is set to null and a warning logged. May produce inconsistent data.
    --retry-count <count> 1 Number of times a record deployment is retried before it is failed.
    --bulk-api false Use the Salesforce Bulk API. Slower; use only to reduce API call-outs.
    --delta false Only deploy datapacks that differ from the target org.
    --strict-order false Enforce datapack-level ordering in addition to record-level ordering. Slower but more compatible.
    --skip-lwc false Skip LWC activation for LWC-enabled OmniScripts.
    --use-metadata-api false Deploy LWC via the Metadata API instead of the Tooling API.
    --remote-script-activation false Activate OmniScripts via anonymous Apex instead of local script generation.
    -y, --continue-on-error false Continue with datapacks that loaded successfully even if others failed to load/convert. 
    # Deploy a folder tree using an SFDX alias
    vlocode deploy ./datapacks --user my-org

    # Deploy only changed datapacks to production
    vlocode deploy ./datapacks --instance login.salesforce.com --delta

    Export records from an org into datapack files, by Id, by SOQL query, or driven by a YAML manifest. See Exporting datapacks for the full workflow, and Building export definitions for the definition format.

    vlocode export [ids...] [options]

    Arguments

    Argument Description
    ids... Optional list of record Ids to export.

    Options (in addition to the global and connection options)

    Option Default Description
    --definitions <file> — YAML/JSON export definitions describing how records become datapacks.
    -f, --file <file> — YAML export manifest with datapack queries. Conflicts with --query.
    -e, --expand false Expand each datapack into a folder of separate files.
    -q, --query <soql> — SOQL query selecting records to export (must select Id). Conflicts with --file.
    -t, --type <type> — Datapack type to apply when exporting Ids or a single query.
    -o, --output <dir> ./ Output folder for exported datapacks.
    -d, --depth <n> — Dependency export depth; -1 follows all dependencies.
    --suppress-nulls false Omit null field values from the export.
    --fail-on-error false Abort the export if any datapack errors (otherwise the record is skipped).
    --no-progress — Disable the interactive progress bar; print plain output. 
    vlocode export \
      --definitions ./export-definitions.yaml \
      --type Product2 \
      --query "SELECT Id FROM Product2 WHERE IsActive = true" \
      --depth -1 --expand --output ./datapacks --user my-org

    Export raw record data using the Salesforce Bulk API v2, streaming results to a newline-delimited JSON (NDJSON) file. This is a data export (one JSON object per record), distinct from datapack export — use it for large data extracts, not for metadata transport.

    vlocode bulk-export [sobject] [options]

    Arguments

    Argument Description
    sobject SObject to query (SELECT Id FROM <sobject>) when no --query/--file is given.

    Options (in addition to the global and connection options)

    Option Default Description
    -o, --output <file> required Path to the output NDJSON file.
    -q, --query <query> — SOQL query to execute. Conflicts with --file.
    -f, --file <file> — Path to a file containing a SOQL query. Conflicts with --query.
    -l, --limit <number> — Limit the number of records (only when an SObject name is given).
    --include-deleted false Include deleted/archived records (queryAll).
    --chunk-size <size> 50000 Number of records retrieved per API call. 
    vlocode bulk-export Account --output ./accounts.ndjson --user my-org
    vlocode bulk-export --query "SELECT Id, Name FROM Product2" -o ./products.ndjson -u my-org

    Activate OmniScripts in an org and deploy their associated LWC components. Dependencies between scripts are respected: when a reusable OmniScript is activated, the scripts that embed it are reactivated unless suppressed.

    vlocode activate [scriptFilter] [options]

    Arguments

    Argument Description
    scriptFilter A Salesforce Id, or a type/subType/language filter with wildcard support (e.g. MACD/ matches all sub-types). Omit to consider all scripts.

    Options (in addition to the global and connection options)

    Option Default Description
    --parallel-activations 4 Number of activations to run in parallel.
    --skip-lwc false Skip LWC activation for LWC-enabled OmniScripts.
    --use-metadata-api false Deploy LWC via the Metadata API instead of the Tooling API.
    --skip-reactivate-dependencies false Do not reactivate parent scripts that embed the activated scripts.
    --remote-activation false Activate via anonymous Apex instead of local script generation.
    --debug-activation false Save script definitions as JSON before/after activation for comparison. 
    vlocode activate "MACD/" --user my-org

    Convert managed-runtime OmniScript datapacks into native OmniProcess datapacks.

    vlocode convert <paths...> [options]

    Arguments

    Argument Description
    paths... One or more folders or datapack files to convert.

    Supports the global and connection options.

    vlocode convert ./datapacks --user my-org

    Generate a DatapackExportDefinition YAML file from an org's DataRaptor migration configuration (DRMapItem records). Use this to bootstrap an export-definitions file instead of authoring it by hand, then trim and customize the result.

    vlocode build-export-definitions [options]

    Options (in addition to the global and connection options)

    Option Default Description
    -e, --expand-definition <file> — Optional datapacksexpanddefinition YAML to merge expansion settings from.
    -x, --expanded false Write one YAML file per datapack definition instead of a single combined file.
    -o, --output <file> ./export-definitions.yaml Output file for combined mode.
    -d, --output-dir <dir> ./datapack-export-definitions Output directory for expanded (-x) mode. 
    vlocode build-export-definitions --output ./export-definitions.yaml --user my-org

    Parse Apex classes and triggers to determine which unit tests cover a given set of classes, directly or indirectly. This command runs offline — it analyzes local source and does not connect to an org, so it has no connection options.

    vlocode impacted-tests <folders...> [options]

    Arguments

    Argument Description
    folders... One or more folders containing Apex class (.cls) and trigger (.trigger) files.

    Options (in addition to the global options)

    Option Default Description
    --classes <classes...> — Classes to report impacted tests for.
    --output <file> impactedTests.json Path to write the full analysis as JSON. 
    vlocode impacted-tests ./force-app/main/default/classes --classes AccountService

    Vlocode's bundled distribution, SFDX-based authentication, NDJSON logging, and non-zero exit codes make it straightforward to run in a pipeline. A typical deployment stage:

    # 1. Authorize the target org with the Salesforce CLI (once per runner/session)
    sf org login sfdx-url --sfdx-url-file ./AUTH_URL.txt --alias target-org

    # 2. Install Vlocode
    npm install --global @vlocode/cli

    # 3. Deploy, failing the build on unhandled errors
    vlocode deploy ./datapacks \
      --user target-org \
      --delta \
      --log-file ./artifacts/vlocode-deploy.log

    Guidelines:

    • Authenticate with --user against an org pre-authorized in the Salesforce CLI; avoid interactive OAuth in headless runners.
    • Use --no-progress (on export) for clean, line-oriented logs.
    • Archive the NDJSON --log-file as a build artifact for auditing.
    • Use --delta to deploy only what changed and keep runs fast.
    • Gate the stage on the process exit code; for finer control, parse the deploy summary or NDJSON log for record-level errors.

    Settings

    Member Visibility

    On This Page

    Vlocode CLI reference