Last update / Última actualización: 2026-08-02 — @nervill/metadelta 0.15.0

Metadelta Salesforce CLI Plugin

• English
• Español

English

Metadelta is a custom Salesforce CLI plugin that offers thirteen complementary command families:

• sf metadelta find inspects a target org and reports metadata components modified by a specific user within a recent time window, optionally generating manifest files for deployment or Vlocity datapack migration. When it writes package.xml, the command stamps the file with the API version detected from the target org.
• sf metadelta orgApiVersion prints the API version reported by a target org and is used internally by commands that need to align generated manifests with the org.
• sf metadelta finddelta compares two Git branches and generates delta manifests under manifest/ for Salesforce Core (.xml) and Vlocity (.yaml), including destructive manifests when complete deletions are detected. ApexClass destructive entries require both .cls and .cls-meta.xml to be deleted, and Vlocity destructive entries require the entire datapack folder to be absent from the source branch. It can also merge missing components into existing manifests with --xml and --yaml without duplicating entries.
• sf metadelta postvalidate re-retrieves the manifests you deployed (Core package.xml and/or Vlocity YAML), downloads the corresponding components into a temporary folder, and compares them to your local sources with a colorized diff table.
• sf metadelta access exports aliases, captures encrypted auth URLs, and restores secure org access across Windows/Linux/WSL with an MFA checkpoint.
• sf metadelta security users reads a security master matrix plus a target users list, resolves required IDs in the org, generates bulk-ready CSV files for role/PSG/group assignments, and can optionally apply changes via Bulk API or generate a current-state validation matrix via --validate, and compare that file against the master matrix locally via --compare.
• sf metadelta initspace bootstraps a local Salesforce workspace by creating the base folder tree and seed project files required by this plugin.
• sf metadelta monitor run starts a terminal monitor for Salesforce Core and Vlocity metadata drift using local filesystem snapshots, a local Git diff engine, optional XML/YAML scoped manifests, Vlocity modifier enrichment, a persistent JSONL change log, and optional CSV export.
• sf metadelta task record and sf metadelta task play record/play Playwright-based Salesforce tasks with automatic recovery stabilizers, patched .metadelta.* playback, and orchestrated diagnostics.
• sf metadelta cleanps extracts a focused copy of a permission set by keeping only the entries that match a fragment or appear in a curated allowlist.
• sf metadelta findtest reviews Apex classes inside a local SFDX project, confirms the presence of their corresponding test classes, and can validate existing package.xml manifests prior to a deployment. Generated or updated manifests inherit the API version reported by the target org when available.
• sf metadelta manual collect aggregates manual-step markdown documents stored under docs/, renders a consolidated index/banner per story, and offers a sprint-aware mode that only includes the files still pending merge into the base branch.
• sf metadelta merge scans manifest XML files whose names contain a given substring, deduplicates their metadata members, and builds a consolidated globalpackage.xml (or a custom output filename).

Created by Nerio Villalobos ([email protected]).

Index

• Installation
• sf metadelta find
• sf metadelta orgApiVersion
• sf metadelta finddelta
• sf metadelta postvalidate
• sf metadelta access
• sf metadelta security users
• sf metadelta initspace
• sf metadelta monitor run
• sf metadelta task record / task play
• sf metadelta cleanps
• sf metadelta findtest
• sf metadelta manual collect
• sf metadelta merge

Installation

1. Install the Salesforce CLI (requires version 2.102.6 or later):

   npm install --global @salesforce/[email protected]

2. Install the latest published version from npm using the Salesforce CLI (recommended):

   sf plugins install @nervill/metadelta

   To install this exact release instead, pin the version:

   sf plugins install @nervill/[email protected]

   npmjs.com displays npm i @nervill/metadelta as the generic Node.js package command. Use sf plugins install so the package is registered as a Salesforce CLI plugin.

   Confirm installation with sf plugins, which should list @nervill/metadelta 0.11.14.

3. Alternatively, install the current repository version directly from GitHub:

   sf plugins install github:NerioVillalobos/plugin-metadelta.git

   Confirm installation with sf plugins, which should list @nervill/metadelta 0.15.0.

   

4. (Optional, for local development) Clone this repository and install dependencies:

   git clone <repo-url>
   cd plugin-metadelta
   npm install

5. Link the plugin to your local Salesforce CLI:

   npm run compile
   sf plugins link .

   Confirm installation with sf plugins, which should list @nervill/metadelta 0.15.0 (link).

find command

Explanation

The plugin compares metadata changes for the specified user and prints a table of modified components. When requested, it also produces manifest files under the manifest/ directory.

Usage

Run the command from any directory after linking:

sf metadelta find --org <alias_or_username> [flags]

Flags

| Flag | Description | Default | |------|-------------|---------| | --org, -o | Required. Alias or username of the target org. | N/A | | --metafile | Path to a JSON file listing the metadata types to override the default selection. | Built‑in list | | --days | Number of days in the past to inspect for modifications. | 3 | | --namespace | Vlocity namespace to query datapacks (enables Vlocity datapack checks). | None | | --xml | When set, generates manifest/package-<branch_or_org>[-v#].xml containing found metadata. The resulting file uses the API version fetched from the specified org when available. | false | | --yaml | When set, generates manifest/package-vlocity-<branch_or_org>[-v#].yaml with Vlocity datapack entries. | false | | --audit | Full name of the user to audit. If omitted, the command uses the org user associated with the provided alias. | Authenticated user |

Using a custom metadata file

By default, the command builds its metadata type list by running sf force:mdapi:describemetadata --target-org so it stays synchronized with the connected org. If the describe call fails, a built-in fallback list is used. The resulting list is further filtered to include only types that expose both lastModifiedByName and lastModifiedDate, avoiding unnecessary queries. A maximum of five metadata types are processed in parallel to limit resource usage.

The --metafile flag allows you to override the built‑in metadata list. Provide a JSON (.json) file that either contains a top-level array or an object with a metadataTypes array. The file must contain plain JSON (no module.exports = wrappers) and use UTF-8 encoding.

Create a file—for example mismetadatos.json—with the following content:

{
  "metadataTypes": [
    "Bot", "BotVersion", "CustomPermission", "FlexiPage", "Flow",
    "GenAiFunction", "GenAiPlanner", "GenAiPlugin", "GenAiPlannerBundle",
    "PermissionSet", "Profile", "StaticResource", "PermissionSetGroup"
  ]
}

Minimal example using an array:

[
  "ApexClass",
  "Flow"
]

Reference the file when running the command (prefix with ./ when the file lives in the current folder):

sf metadelta find --org myOrg --metafile ./mismetadatos.json

Tip: If you previously used a .js file with module.exports, rename it to end with .json and remove the assignment wrapper so only the JSON structure remains.

Note: When the path to your metafile contains spaces or special characters, wrap it in quotes (for example, --metafile "./metadata lists/mismetadatos.json").

Examples

• Basic scan for the default user:

  sf metadelta find --org myOrg

• Audit a different user for the last seven days and create a package.xml:

  sf metadelta find --org myOrg --audit "Jane Doe" --days 7 --xml

• Check Vlocity datapacks with a custom namespace and output a Vlocity package file:

  sf metadelta find --org myOrg --namespace myns --yaml

  

Output

The find command prints each matching component with its type, full name, last modified date, and modifier. When --xml or --yaml are set, the corresponding manifest files are created inside the manifest/ directory. If the command runs inside a Git repository, the manifest filename uses the current branch name; otherwise it falls back to the provided org alias. Existing files are preserved by adding incremental -v1, -v2, … suffixes.

orgApiVersion command

Explanation

Print the API version reported by a target org:

Usage

sf metadelta orgApiVersion --org <alias_or_username>

The command runs sf org display --target-org <alias> --json, extracts result.apiVersion, and prints only the version value. It is also used internally by commands that need to align generated manifests with the org API version.

Flags

| Flag | Description | Default | |------|-------------|---------| | --org, -o | Required. Alias or username of the target org. | N/A |

finddelta command

Explanation

Generate delta manifests by comparing two branches:

Usage

sf metadelta finddelta --from <source_branch> --to <base_branch> [--xml manifest/Release.xml] [--yaml manifest/vlocity.yaml]

Characteristics

1. Runs git diff --name-status <to>..<from> to detect additions, deletions, and renames.
2. Generates Core and Vlocity delta manifests under manifest/ using the from branch as the output name.
3. Creates destructive manifests automatically when complete deletions exist.
4. If --xml and/or --yaml are provided, merges only missing components into the destination manifests (no duplicates).

Notes

Destructive hardening:

• ApexClass entries are emitted only when both the .cls file and its .cls-meta.xml companion were deleted.
• Vlocity entries are emitted only when the full Vlocity/<DataPackType>/<DataPackName> folder has no remaining files in the from branch.

Core outputs:

• manifest/<from>.xml
• manifest/Destructive-<from>.xml (only when needed)

Vlocity outputs:

• manifest/<from>.yaml
• manifest/Destructive-<from>.yaml (only when needed)

Flags

| Flag | Description | |------|-------------| | --from | Required. Source branch (typically the PR branch). | | --to | Required. Base branch for comparison. | | --xml | Existing destination package.xml to update with missing Core components. | | --yaml | Existing destination YAML manifest to update with missing Vlocity components. |

postvalidate command

Explanation

Validates a deployment by re‑retrieving the manifests you used (XML for Salesforce Core and/or YAML for Vlocity) into a temporary folder, comparing the downloaded files against your local sources, and rendering a colorized Component | Name | Diff table with ✓ for matches and ✗ for differences.

Characteristics

1. Creates a temporary retrieve directory and hides the raw command output behind a spinner while the retrieves run.
2. For Salesforce Core (--xml), runs sf project retrieve start --manifest <xml> --target-org <org> --output-dir <tempDir>.
3. For Vlocity (--yaml), runs vlocity --sfdx.username <org> -job <yaml> packExport --maxDepth 0 into the same temp directory.
4. Maps retrieved Core files back to your repo using sfdx-project.json package directories (including main/default), and datapacks against the directory you pass in --vlocity-dir (default Vlocity).
5. Compares folder-to-folder ignoring whitespace, blank lines, XML/JS/YAML comments, Vlocity GlobalKey lines, and skips noise files like VlocityBuildErrors.log, VlocityBuildLog.yaml, and the vlocity-temp/ directory.
6. Prints a box-style table with colored headers and status symbols, then deletes the temporary folder.

Flags

| Flag | Description | Default | |------|-------------|---------| | --xml | Path to the package.xml used for the Core deployment. Requires --org. | None | | --yaml | Path to the Vlocity manifest used for the datapack deployment. Requires --org. | None | | --org, -o | Alias or username for both Core and Vlocity retrieves. | CLI default | | --vlocity-dir | Local folder that stores your datapacks. Also probed when manifests contain a Vlocity/ prefix. | Vlocity |

Provide at least one manifest (--xml or --yaml). When both are present, the retrieves share the same temp folder and a single comparison pass.

Examples

• Core only:

  sf metadelta postvalidate --xml manifest/SP1.2.11.0.xml --org SFOrg-prod

• Vlocity only from a custom folder:

  sf metadelta postvalidate --yaml manifest/vlo-manifest.yaml --org SFOrg-Demo02 --vlocity-dir Vlocity

• Core + Vlocity in one run:

  sf metadelta postvalidate --xml manifest/package.xml --yaml manifest/vlocity.yaml --org my-env --vlocity-dir Vlocity

Run the command from the Salesforce project root so Core retrieves line up with your packageDirectories structure. Datapacks are resolved relative to the current directory first and then to --vlocity-dir.

access command

Explanation

Metadelta Access is an Org Access Replication Tool with applied security controls. It automates a formerly manual process to export aliases, protect auth URLs, and restore org access across machines with MFA + passphrase encryption.

Use Metadelta Access to transfer org login access securely between machines:

Usage

sf metadelta access --all --output docs

Characteristics

1. --all or --prefix <text> creates <output>/<name>/accessbackup.dat with connected aliases and usernames and also creates accessbackup.dat.mfa. During this step, the command tries to print an ASCII QR in the terminal (when Python qrcode is available); it always prints Secret + URI as fallback.
2. --capture <folder> asks for MFA + passphrase, reads each alias auth URL with sf org display --verbose, encrypts it, and rewrites accessbackup.dat with encrypted payloads. Starting in v0.11.4, Metadelta injects SF_TEMP_SHOW_SECRETS=true only for this internal Salesforce CLI call so the automated capture receives the real sfdxAuthUrl even when recent Salesforce CLI versions redact secrets by default; users do not need to export the variable manually.
3. --addaccess <folder> asks for MFA + passphrase, decrypts each entry, and restores auth using sfdx auth:sfdxurl:store -f <file> -a <alias> (fallback: sf org login sfdx-url when available).

Important: --addaccess only works after --capture has encrypted the file. If accessbackup.dat still contains alias;username rows, run capture first. Usage reminder: pass the folder as the value of the flag, for example sf metadelta access --addaccess docs/FolderName (do not duplicate the flag).

The command is implemented in Node.js only (no Python runtime/dependencies), so it works the same on Windows, Linux, and WSL as long as Salesforce CLI is installed.

Platform requirements (Windows / macOS / Linux / WSL)

To run sf metadelta access reliably, ensure the following prerequisites are available:

1. Salesforce CLI
   • Required on all platforms.
   • Verify with:

     sf --version

2. Authenticated org session(s)
   • Export/capture depends on active org sessions in your local CLI auth store.
   • Verify with:

     sf org list

3. Node.js environment compatible with this plugin
   • The plugin requires Node.js 18+ (as declared in package.json).
4. Legacy sfdx binary (recommended for replication restore)
   • Primary restore command uses sfdx auth:sfdxurl:store.
   • If unavailable, the command attempts sf org login sfdx-url fallback.
5. Optional ASCII QR rendering dependency
   • If Python + qrcode module exists, the command prints an ASCII QR in terminal during MFA creation.
   • Without it, Secret + URI are still printed and can be entered manually in your authenticator app.

Platform notes:

• Windows (PowerShell/CMD): keep Salesforce CLI binaries available in PATH and prefer running from a regular user terminal with profile initialization enabled.
• macOS/Linux: ensure sf (and optionally sfdx) resolve from the same shell session where you run the plugin.
• WSL: if mixing Windows and WSL auth contexts, validate where your CLI auth store is located and run export/restore in the same environment when possible.

Responsibility and security notice

By using metadelta access and all other commands in this plugin, you acknowledge that:

• You are responsible for complying with your organization’s security policies.
• You are responsible for protecting MFA secrets, passphrases, backup files, and generated auth artifacts.
• You should only run these commands in trusted environments and with authorized org access.
• The maintainers/authors are not responsible for misuse, credential leakage, or operational impact caused by incorrect handling.

Use the tool carefully, rotate credentials when needed, and treat backup files as sensitive secrets.

security users command

Explanation

Use this command to transform a security matrix into actionable Bulk API files for a target org:

Usage

sf metadelta security users --master data/master.csv --target-users data/target-users.csv --org myOrg

This workflow mirrors the original Python utility and is designed for controlled migrations of user access models.

Characteristics

1. Reads the master matrix (--master) and the target users file (--target-users).
2. Resolves org IDs by querying User, UserRole, PermissionSetGroup, and Group via Salesforce CLI.
3. Builds these output files under --output-dir (default out):
   • user_role_updates.csv
   • permissionsetassignment_insert.csv
   • groupmember_insert.csv
   • validation_errors.csv
4. Runs as dry-run by default (only generates files).
5. When --apply is present, executes the corresponding bulk operations:
   • sf data update bulk -s User
   • sf data import bulk -s PermissionSetAssignment
   • sf data import bulk -s GroupMember
6. When --validate is present, the command does not apply changes and instead generates validation_current_matrix.csv with one row per target user and current values for RoleName, PermissionSetGroup, PublicGroupPuesto, PublicGroupSegmento, and Queues.
7. When --compare is present, no org connection is required: the command compares --file-validation against --master locally and outputs only users with differences in comparison_mismatches.csv using compact annotations: <value> means missing in user (present in master), and =value= means extra in user (not present in master).

Input

• --master must include columns like: RoleName, PermissionSetGroup, PublicGroupPuesto, PublicGroupSegmento, Queues.
• PermissionSetGroup, PublicGroupSegmento, and Queues support multiple values separated by |.
• --target-users should include at least: Username, RoleName.

Flags

| Flag | Description | Default | |------|-------------|---------| | --master | Required. Master security matrix CSV. | N/A | | --target-users | Required. CSV with users to process. | N/A | | --org, -o | Required. Alias/username of the target org. | N/A | | --output-dir | Output directory for generated CSV files. In --validate/--compare, if you pass a value different from out, the command creates/uses <output-dir>/out. | out | | --apply | Applies generated operations through Bulk API. Cannot be combined with --validate. | false | | --validate | Generates validation_current_matrix.csv (current values per target user) without applying changes. | false | | --compare | Compares --file-validation vs --master locally and exports only users with differences to comparison_mismatches.csv in compact format (<value> missing, =value= extra). Cannot be combined with --apply or --validate. | false | | --file-validation | Path to validation_current_matrix.csv used by --compare. | None |

Examples

• Dry run (generate files only):

  sf metadelta security users --master ./data/master.csv --target-users ./data/users.csv --org my-org

• Apply mode (execute bulk operations):

  sf metadelta security users --master ./data/master.csv --target-users ./data/users.csv --org my-org --apply

• Validate mode (export current assignments in matrix format):

  sf metadelta security users --master ./data/master.csv --target-users ./data/users.csv --org my-org --validate --output-dir ./reports

• Compare mode (local comparison without org connection):

  sf metadelta security users --master ./data/security_master_matrix.csv --file-validation ./reports/out/validation_current_matrix.csv --compare --output-dir ./reports

initspace command

Explanation

Create the recommended workspace scaffold in your current directory:

Usage

sf metadelta initspace

Characteristics

• Folders:
  • force-app/main/default
  • docs
  • data
  • manifest
  • scripts
• Root files:
  • .gitignore (Metadelta template)
  • sfdx-project.json (sourceApiVersion 66.0)
  • package.xml (Metadata API version 66.0)

initspace is idempotent for directories (safe to re-run) and rewrites the three root files so they stay aligned with the plugin defaults.

monitor run command

Explanation

Starts a persistent terminal monitor for Salesforce Core and Vlocity metadata drift:

Usage

sf metadelta monitor run --org DEV

Flags

| Flag | Description | Default | | --- | --- | --- | | --org, -o | Alias or username of the target org. Required for the normal monitor mode. | Required unless --control or --watchdog-once is used | | --interval | Refresh interval in minutes. Values below 1 are normalized to 1. | 5 | | --scope | Metadata source to monitor: all, salesforce, or vlocity. | all | | --scope-xml | Path to a Salesforce Core package.xml. When present, the monitor retrieves and watches only the Core components listed in that manifest. | None | | --scope-yaml | Path to a Vlocity YAML job/manifest. When present, the monitor exports and watches only the DataPacks listed in that file. | None | | --export-csv | Path where the persistent change-log.jsonl should be exported as CSV when the monitor exits. The path is resolved from the directory where the command was started. | None | | --control | Opens the portable Metadelta Monitor control menu for watchdog targets and monitor launches. | false | | --watchdog-once | Runs one Teams watchdog cycle using change-log.jsonl targets from the watchdog config, then exits. | false | | --watchdog-config | Path to the watchdog config JSON. | ~/.metadelta/monitor/watchdog.config.json | | --teams-webhook-url | Microsoft Teams webhook URL for --watchdog-once. Prefer METADELTA_TEAMS_WEBHOOK_URL for secrets. | Environment/config | | --once | Run one refresh cycle and exit. Useful for validation. | false |

The monitor stores its runtime state under ~/.metadelta/monitor/<orgAlias>/. Inside that folder it maintains current/, manifest/, temp/, the local-only Git repository used as the diff engine, and refreshes every five minutes. NEXT shows the exact next refresh time instead of repainting a countdown, and RETRIEVE shows the last Salesforce Core + Vlocity retrieve/export duration. The first cycle creates the baseline and shows STATUS: BASELINE CREATED; later refreshes show added, modified, deleted, or renamed files. Full errors and Vlocity warnings are wrapped in a detail section and automatically pause UI repainting so the text can be selected/copied.

For Salesforce Core changes, the monitor queries the org metadata APIs to enrich each row with LastModifiedBy.Name and LastModifiedDate. For Vlocity changes, it now shares the Vlocity DataPack query catalog used by sf metadelta find, so paths such as vlocity/Promotion/<GlobalKey>/... are resolved against the parent DataPack record by Name, Id, or namespaced GlobalKey__c when available. This improves the modifier shown in the dashboard and in the change log instead of falling back to N/A for many Vlocity DataPack files.

When --scope-xml or --scope-yaml is present, the dashboard scope label reflects the custom scope: SALESFORCE-CUSTOM, VLOCITY-CUSTOM, or ALL-CUSTOM. The XML/YAML paths can use any filename and are resolved relative to the directory where you start the command, before the monitor changes into ~/.metadelta/monitor/<orgAlias>/.

Examples

Examples for scoped monitoring:

sf metadelta monitor run --org DEV --scope-xml manifest/core.xml
sf metadelta monitor run --org DEV --scope-yaml manifest/vlocity.yaml
sf metadelta monitor run --org DEV --scope-xml manifest/core.xml --scope-yaml manifest/vlocity.yaml

The UI has two navigable sections. SALESFORCE CORE / VLOCITY groups changes by metadata type and shows the count, latest change date, and latest modifier for each type. RECENT CHANGES lists the session-cumulative component changes with the most recently detected items first. The arrow keys move the > selector across both sections; when the selected row moves past the visible terminal area, the list scrolls so the selector remains visible. Press Enter or d on an individual change to see its file, metadata query, modifier, detection time, and Git diff summary. Press Enter or d on a metadata type to open TYPE DETAILS, which lists the changed components for that type in recent-first order.

Press p to pause/resume, r to refresh, s for Salesforce only, v for Vlocity only, a for all, and q, x, ESC, CTRL+C, or exit to quit.

For Vlocity-enabled orgs, the default monitor scope runs packExportAllDefault with a temporary job file that includes continueAfterError: true:

sf metadelta monitor run --org DEV --scope vlocity

When the scope is all, a Vlocity export failure does not block Salesforce Core monitoring; the UI keeps the Core diff and shows the Vlocity warning. For orgs without Vlocity CLI installed, use:

sf metadelta monitor run --org DEV --scope salesforce

RECENT CHANGES is cumulative within the active terminal session. Across restarts, the Git baseline and snapshots are preserved under ~/.metadelta/monitor/<orgAlias>/, so the next run continues from the last baseline instead of starting from scratch. A persistent append-only change log is written to ~/.metadelta/monitor/<orgAlias>/change-log.jsonl. It records SESSION_STARTED, CHANGE_DETECTED, and SESSION_ENDED events with the component type, component name, action, detection time, last modified date, and modifier when available. Vlocity files named *_SampleInputJson.json are ignored by the monitor because they are sample payloads and can produce noisy JSON parsing failures.

To export the accumulated persistent log to CSV when the monitor exits, use --export-csv. The export includes session and change events in stable columns such as event, org, scope, source, action, type, component, file, detectedAt, lastModifiedDate, lastModifiedBy, startedAt, endedAt, exitCode, and reason.

sf metadelta monitor run --org DEV --export-csv reports/metadelta-monitor.csv

The complementary watchdog mode reads the persistent change-log.jsonl files and sends Microsoft Teams alerts when a CHANGE_DETECTED event was touched by a user outside the configured DevOps allowlist. It is incremental and stores byte offsets in a local state file, so repeated scheduled executions do not resend already processed events. Put the webhook URL in METADELTA_TEAMS_WEBHOOK_URL or pass it explicitly only in secure local environments.

sf metadelta monitor run --watchdog-once
sf metadelta monitor run --watchdog-once --watchdog-config ~/.metadelta/monitor/watchdog.config.json

The control menu is a portable companion for managing watchdog targets and monitor launches without editing JSON by hand. It can add/remove org targets, configure or clear per-target scopeXml and scopeYaml, change each monitor interval, switch the menu language between English and Spanish, run one watchdog cycle, start monitors in background, use tmux for a multi-monitor TUI when available on Linux/WSL/macOS, and open all monitors as Windows Terminal tabs when wt.exe is available.

sf metadelta monitor run --control

Watchdog target entries can include custom manifests per org:

{
  "org": "Telecentro-qa",
  "logPath": "~/.metadelta/monitor/Telecentro-qa/change-log.jsonl",
  "scopeXml": "/absolute/path/Release.xml",
  "scopeYaml": "/absolute/path/Release.yaml",
  "interval": 8,
  "exportCsv": "~/.metadelta/Telecentro-qa-metadelta-monitor.csv"
}

Monitor persistence, scoped manifests, Vlocity enrichment, CSV export, and watchdog control (v0.15.0): sf metadelta monitor run preserves snapshots, Git baseline, and change-log.jsonl under ~/.metadelta/monitor/<orgAlias>/. Use --scope-xml and/or --scope-yaml to monitor only the components listed in a Core XML or Vlocity YAML manifest. Use --export-csv to produce an audit-friendly CSV copy of the persistent log when the command exits. Use --control and --watchdog-once for the complementary Teams watchdog/control workflow.

task record / task play command

Explanation

Use task record to capture a Playwright flow and task play to replay it in another org with automatic patching, recovery stabilizers, and orchestrated diagnostics:

Usage

sf metadelta task record --org <alias>
sf metadelta task play --org <alias> --tstname tests/<recorded-file>.ts [--header] [--ai --ai-provider gemini --ai-model <model> --ai-key <key>]

Characteristics

Supported coverage for sf metadelta task play (scope and limits):

• task play creates a temporary patched file (tests/.metadelta.*) to stabilize recurring Salesforce UI differences.
• Optional AI hardening (--ai) runs after deterministic patching, uses a constrained AI fragility-analysis plan (targeted hardening, not full-file free rewrite), creates a second derived file (tests/.metadelta.<name>.ai.ts) when safe, supports model override with --ai-model/METADELTA_AI_MODEL, and falls back to the deterministic file if AI is unavailable/invalid.
• Playback now also includes conservative idempotent guards for supported patterns (checkbox state, toggle state, and safe fill-value matches): when target state is already satisfied the step is skipped; otherwise it runs normally.
• The command aims to auto-mitigate known recurrent failures first; if mitigation is not possible, it surfaces orchestrator-backed actionable errors instead of generic failures.

Flags

AI and idempotency options (quick reference):

| Option | Purpose | Required | |---|---|---| | --ai | Enables optional AI hardening stage over deterministic patched file. | No | | --ai-provider | AI provider selector (current supported value: gemini). | No (defaults to gemini when --ai is used) | | --ai-model | Overrides Gemini model (e.g. gemini-2.5-flash). | No | | --ai-key | API key passed inline (pipeline-friendly but prefer env secrets). | No (required only when --ai is enabled and no env key exists) |

Notes

Environment variables recognized by AI mode:

• GEMINI_API_KEY or METADELTA_AI_KEY for credentials.
• METADELTA_AI_MODEL or GEMINI_MODEL for model override.

How idempotent playback behaves:

• Supported patterns (checkbox/switch/fill and specific toggle flows) are checked before acting.
• If target state is confidently already satisfied, the step is skipped with concise log (⏭️ action skipped: already satisfied ...).
• If state is uncertain, playback does not skip blindly; it keeps conservative execution.

Automatic mitigations currently covered:

• frontdoor URL vs base origin separation to avoid malformed navigation URLs.
• Retry flow for transient net::ERR_ABORTED style navigation interruptions.
• Initial Setup popup recovery when Salesforce delays or redraws the “Setup Opens in a new tab…” menu item before opening the setup tab.
• Visible-first fallback for ambiguous .slds-checkbox_faux clicks that would otherwise fail in Playwright strict mode.
• Agentforce Agents recovery with full-page refresh, Setup reopen retries, broader Quick Find terms, and direct Setup-route fallback after enabling Einstein Setup.
• Popup rebind/reopen handling when a recorded tab/window is closed and reused later.
• App Launcher fallback path (combobox/placeholder/reopen launcher).
• Dynamic selectors for Permission Set Assignments ([0], [2], [5], etc.).
• Action Library waits + scroll handling before selecting actions.
• Finish-button enablement checks before click.
• Normalization of dynamic vfFrameId_* and related fragile selectors in recorded tests.

Known limits (not guaranteed by automation only):

• Org-specific permissions/visibility gaps (apps/actions/records/features).
• Deep UX/DOM changes not yet modeled by current stabilizers.
• Missing business data dependencies in the target org.
• External MFA/session policies that block unattended playback.

Expected reliability:

• High for recurrent failures already covered by existing stabilizers.
• Medium for new flows with moderate UI variation.
• Low for orgs with strong functional divergence (permissions/data/features/layouts).

How we measure coverage:

• Recommended metric is by recurrent failure families, not code lines.
• Stabilization coverage = (recurrent failure families with automatic mitigation) / (recurrent failure families observed) × 100.
• Current technical estimate: ~60%–70% coverage over known recurrent failure families (not all possible Salesforce scenarios).

Comments

Diagnostics + collaboration:

1. Review test-results/.../error-context.md.
2. Review .metadelta/metadelta-task-orchestrator.json for suggestions/history.
3. Re-run with --header for visual evidence.
4. Open Issues → New issue → task play bug report and complete all required fields.

Please report new failures using the task play bug report template so issues can be triaged publicly and prioritized incrementally.

cleanps command

Explanation

Generate a trimmed permission-set file with:

Usage

sf metadelta cleanps --permissionset <name> --prefix <fragment> [flags]

The command locates the default package directory declared in sfdx-project.json, reads the matching permission-set XML under <packageDir>/main/default/permissionsets, and produces a filtered copy inside <project-root>/cleanps/ (the folder is created automatically when missing).

Characteristics

1. Prefix-driven matches. Every candidate entry is evaluated against the fragment provided through --prefix. If any relevant value (such as the object name, record type, or tab API name) contains that fragment, the entire node is kept.
2. Allowlist overrides. When you pass --exclude <file>, the command loads each non-empty line of the text file (relative paths are resolved from the project root). Any entry whose relevant value equals one of those lines is preserved even when it does not contain the prefix. Use this to retain standard objects or tabs that complement your custom solution.
3. Section-aware filtering. The cleaner scans the following sections: applicationVisibilities, classAccesses, customPermissions, fieldPermissions, objectPermissions, pageAccesses, recordTypeVisibilities, tabSettings, and userPermissions. For composite fields such as fieldPermissions and recordTypeVisibilities, both the full API name (Account.Field__c) and its components (Account, Field__c) are checked against the prefix and allowlist so you can keep entire objects or individual fields.
4. Preserve untouched metadata. Elements outside of the filtered sections (labels, descriptions, activation flags, etc.) are copied verbatim from the source permission set.

The default output file follows the pattern <PermissionSet>_<prefix>_filtered.permissionset-meta.xml. Use --output to provide a custom name (the .xml extension is appended automatically when omitted).

Flags

| Flag | Description | Default | |------|-------------|---------| | --permissionset, -p | Required. File name (with or without .permissionset-meta.xml) located under the project’s permission-set folder. | N/A | | --prefix, -f | Required. Fragment that must appear in an entry for it to remain in the cleaned file. | N/A | | --exclude, -e | Path to a newline-delimited text file containing exact values that must always be kept. | None | | --output, -o | Name of the XML file written under cleanps/. | <PermissionSet>_<prefix>_filtered.permissionset-meta.xml | | --project-dir | Optional root directory that holds sfdx-project.json. When omitted, the command walks up from the current working directory. | Auto-detected |

findtest command

Explanation

Analyse Apex classes and their associated tests with:

Usage

sf metadelta findtest [flags]

By default the command looks for sfdx-project.json in the current directory (or its parents) and inspects the force-app/main/default/classes folder.

Tip: After pulling plugin updates, run sf plugins link . again so the Salesforce CLI registers the new findtest command.

When --xml-name points to a manifest that needs to be updated (for example to add detected tests), the command refreshes its <version> node with the API version reported by the target org when --org/--target-org is supplied.

Examples

| Scenario | Example | |----------|---------| | Show the Apex ↔︎ test mapping in the console | sf metadelta findtest | | Restrict the report to the Apex classes listed in a manifest (analysis only) | sf metadelta findtest --xml-name manifest/package.xml | | Validate a manifest against a specific org while keeping a dry-run deploy | sf metadelta findtest --xml-name manifest/package.xml --org SFOrg | | Execute the deployment helper without --dry-run | sf metadelta findtest --xml-name manifest/package.xml --org SFOrg --run-deploy | | Run a production-ready deployment that skips -l when no Apex tests are found | sf metadelta findtest --xml-name manifest/package.xml --org SFOrg --run-deploy-prod | | Ignore the manifest and inspect only local sources | sf metadelta findtest --only-local | | Include managed-package classes explicitly | sf metadelta findtest --xml-name manifest/package.xml --no-ignore-managed |

Note: The deployment helper (dry-run or live deploy) requires --org or --target-org. Without either flag, the command only analyses manifests and local sources—even when --xml-name is provided.

Manual-step documentation detection

When you provide --xml-name (or --deploy), the command cross-checks the manifest name against files inside the project’s docs/ directory. If it finds documentation that references the manifest identifier (for example docs/Prefix-NumberStories-PRE.md for manifest/name-branch.xml), the console shows a prominent warning so you can review and run those manual steps before or instead of the deployment.

If the manifest file itself is missing but matching documentation exists under docs/, the command stops and reminds you to follow the documented manual procedure without using --dry-run or --run-deploy. When neither the manifest nor related documentation exist, it reports the missing XML file as an error.

How Apex tests are detected

sf metadelta findtest splits Apex sources into functional classes and tests by applying a case-insensitive name pattern (TEST_NAME_PATTERN) while scanning the target directory. Non-matching .cls files become candidates for validation, whereas files whose names contain test, _test, testclass, or similar suffixes are treated as potential test classes.

Once the functional and test pools are separated, the command evaluates each class with the following steps:

1. Direct suffix match. findtest attempts to append each of the known test suffixes (Test, _Test, TestClass, etc.) to the Apex class name and looks for an exact match. The comparison also tolerates trigger handler patterns by trimming a trailing Handler before trying the suffixes, so classes like MyTriggerHandler can pair with tests named MyTriggerTest.
2. Content analysis. When there is no direct match, the command opens every potential test class and looks for evidence that it exercises the Apex class: instantiations (new MyClass), static member access (MyClass.someMethod(), or variable declarations (MyClass variable;). The best-scoring candidate is reported as a low-confidence suggestion, leaving the final decision to you.
3. Manifest reconciliation. If a manifest is provided, the command normalizes every <members> entry (ignoring whitespace, nil markers, and letter casing) before comparing it against the inferred tests. This prevents duplicate insertions and ensures that existing test names are respected even when the XML formatting varies.

Flags

| Flag | Description | Default | |------|-------------|---------| | --project-dir | Path to the Salesforce project root (folder that contains sfdx-project.json). If omitted, the command walks up from the current directory until it finds it. | Current project | | --source-dir | Relative or absolute path to the Apex classes directory. | force-app/main/default/classes | | --xml-name | Relative or absolute path to an existing package.xml. When provided, the console report starts from the Apex classes declared in that manifest and the same file is used for deployment validation. | N/A | | --deploy | Alias for providing the deployment manifest path. It behaves like --xml-name. | N/A | | --org | Alias or username to use with the deployment helper. Mirrors --target-org but is shorter to type. | CLI default | | --target-org | Alias or username passed to sf project deploy start (same behaviour as --org). | CLI default | | --run-deploy | Executes the deployment helper without appending --dry-run. When omitted, the helper always adds --dry-run to keep the validation non-destructive. | false | | --run-deploy-prod | Production deployment helper that omits the -l flag when the manifest lacks Apex classes and uses -l RunSpecifiedTests with the detected test names when they exist. | false | | --only-local | Ignores the manifest (if any) and analyses only the Apex classes present in the local repository. | false | | --ignore-managed, --no-ignore-managed | Skip (true) or include (false) classes whose names start with namespace__. | true | | --ignore-communities, --no-ignore-communities | Skip (true) or include (false) the built-in Communities controllers (ChangePasswordController, etc.). | true | | --verbose | Print detailed warnings for every class filtered out or missing locally. | false | | --json | Emit a JSON summary with filtering metrics (inputCount, filteredCount, finalCount, and ignored/missing lists). | false |

Deployment helper flow

When you provide a manifest file through --xml-name or --deploy, the command:

1. Reads the existing package.xml (the file must already exist).
2. Checks for <types><name>ApexClass</name></types> entries. If none are present, it reports the absence of Apex classes. When --org/--target-org is provided, the command still invokes sf project deploy start --manifest <file> -l NoTestRun (adding --dry-run unless you include --run-deploy). Without an org, the workflow stops after the report.
3. Builds the evaluation list by intersecting the manifest with the local filesystem, optionally removing managed-package members and Communities controllers. Use --verbose to list the skipped entries.
4. Finds the associated test classes for each remaining Apex entry. Direct name matches (MyClassTest, MyClass_Test, MyClassTests, …) are appended to the manifest. Name-only heuristics are surfaced as warnings so you can double-check coverage manually.
5. If any Apex class lacks an associated test, only has a heuristic match, or a required test file is missing, the command reports the names and skips sf project deploy start so you can fix the manifest or restore the files.
6. Otherwise, it executes sf project deploy start --manifest <file> -l RunSpecifiedTests -t <Test1> -t <Test2> … (or -l NoTestRun if no tests were detected). The command appends --dry-run unless you pass --run-deploy. Use --org/--target-org to override the CLI default org.

Output

Every run starts with a summary line detailing how many classes came from the manifest (or filesystem), how many were filtered out, and how many remain in the local repository. The detailed mapping preserves the original script format (ApexClass → ApexTest). When a manifest is provided, the command automatically ignores managed-package entries (namespace__*) and common Communities controllers unless you opt back in; only classes that exist locally are considered for test discovery. Use --verbose to list the filtered names and --json to capture the underlying metrics programmatically.

Only test classes whose names match the Apex class directly (MyClassTest, MyClass_Test, MyClassTests, …) are considered reliable and appear in the mapping. Potential matches detected heuristically are reported as warnings for review and are not added to manifests or deployment commands automatically.

manual collect command

Explanation

Build a consolidated runbook of manual steps by parsing markdown files stored under a directory such as docs/. Valid filenames follow the Prefix-<story>-<PRE|POST>.md pattern—files that start with Prefix are normalized automatically. Run the command with:

Usage

sf metadelta manual collect --docs ./docs --output ./docs/MANUAL-STEPS.md --all

By default (or when passing --all) the command gathers every matching .md, sorts entries so PRE steps appear before POST, orders them chronologically (filesystem mtime unless --order-by git is provided), and emits a markdown file with an index, a metadata banner, and the original content per story.

Enable partial mode to limit the output to the stories that are still pending merge between a sprint branch and its base branch. The command runs git diff --name-only <base>..<sprint> -- <docs> behind the scenes and filters the list to keep only the manual-step markdown files:

sf metadelta manual collect \
  --docs ./docs \
  --output ./docs/MANUAL-STEPS.md \
  --partial \
  --sprint-branch SP1/main \
  --base-branch master \
  --sprint-name SP1 \
  --order-by git

If no qualifying files remain in the requested range the command stops with a friendly message so you can confirm whether the sprint actually merged any documentation. Leaving out both --partial and --all behaves the same as --all for convenience.

Flags

| Flag | Description | Default | |------|-------------|---------| | --docs, -d | Required. Directory that hosts the manual-step .md files. | N/A | | --output, -o | Required. Destination markdown file that will contain the consolidated content. | N/A | | --partial | Restricts the output to the files pending merge between the base branch and the sprint branch. Requires --sprint-branch. | false | | --all | Forces the command to include every manual-step file in --docs. (This is also the default behaviour when --partial is not set.) | false | | --sprint-branch | Sprint branch used in partial mode. | N/A | | --sprint-name | Optional label shown in the markdown header/banner. | None | | --base-branch | Base branch used to compute the diff range when --partial is active. | master | | --order-by | Source for the ordering timestamp. Use git to rely on commit dates instead of file modification times. | mtime |

merge command

Explanation

Combine multiple manifest fragments into a single package with:

Usage

sf metadelta merge --xml-name <substring> [flags]

By default the command looks inside the manifest/ directory for XML files whose filenames contain the provided substring. It merges their <types> entries, deduplicating members per metadata type and keeping the highest API version found across the inputs. Each <members> node in the resulting manifest now carries an inline <!-- source --> comment listing the contributing manifest filenames (without the .xml suffix) so you can trace every component. The result is saved to manifest/globalpackage.xml, unless you override the filename.

When you add --partial --sprint-branch <name> [--base-branch master], the command limits its search to manifest files that are still pending merge between the specified sprint branch and its base branch. Internally it runs git diff --name-only <base>..<sprint> -- manifest/ (respecting --directory) and keeps only the matching XML files. If the diff is empty the command stops with a clear message so you can adjust the range or fallback to a full merge.

Flags

| Flag | Description | Default | |------|-------------|---------| | --xml-name, -x | Required. Substring that matching manifest filenames must contain. | N/A | | --directory, -d | Directory that holds the manifest XML files to merge. | manifest | | --output, -o | Name of the combined manifest file to generate. | globalpackage.xml | | --partial | Restricts the merge to manifest files pending merge between the base branch and the sprint branch. Requires --sprint-branch. | false | | --sprint-branch | Sprint branch that contains the manifests you want to consolidate. | N/A | | --base-branch | Base branch already deployed to production. Used to compute the diff in partial mode. | master |

Example

To merge every manifest whose filename contains Prefix into manifest/globalpackage.xml:

sf metadelta merge --xml-name Prefix

To restrict the merge to manifests that have not been merged back into master yet:

sf metadelta merge --xml-name Prefix --partial --sprint-branch Branch-Destination --base-branch master

Uninstalling

To unlink the plugin from your Salesforce CLI:

sf plugins unlink @nervill/metadelta

License

This project is released under the ISC License.

Español

Metadelta es un plugin personalizado de Salesforce CLI que ofrece trece familias de comandos complementarias:

• sf metadelta find inspecciona una org de destino y reporta los componentes de metadatos modificados por un usuario específico durante un rango de tiempo reciente, generando opcionalmente manifiestos para despliegues o migraciones de paquetes de Vlocity. Al crear package.xml, la versión del manifiesto coincide con la versión de API detectada en la org de destino.
• sf metadelta orgApiVersion imprime la versión de API reportada por una org de destino y se usa internamente por comandos que necesitan alinear manifiestos generados con la org.
• sf metadelta finddelta compara dos ramas Git y genera manifiestos delta en manifest/ para Salesforce Core (.xml) y Vlocity (.yaml), incluyendo manifiestos destructivos cuando detecta eliminaciones completas. Las entradas destructivas de ApexClass requieren que se eliminen tanto el .cls como su .cls-meta.xml, y las entradas destructivas de Vlocity requieren que la carpeta completa del datapack no exista en la rama fuente. También puede fusionar componentes faltantes en manifiestos existentes con --xml y --yaml sin duplicar entradas.
• sf metadelta postvalidate vuelve a recuperar los manifiestos que desplegaste (package.xml de Core y/o YAML de Vlocity), descarga los componentes correspondientes en una carpeta temporal y los compara con tus fuentes locales mostrando una tabla de diferencias colorizada.
• sf metadelta access exporta aliases, captura auth URLs cifradas y restaura accesos de forma segura entre Windows/Linux/WSL con validación MFA.
• sf metadelta security users lee una matriz maestra de seguridad y una lista de usuarios objetivo, resuelve IDs requeridos en la org, genera CSVs listos para Bulk API para roles/PSG/grupos y opcionalmente aplica los cambios o genera una matrix de estado actual con --validate, y compara localmente ese archivo contra la matrix maestra con --compare.
• sf metadelta initspace prepara un workspace local de Salesforce creando la estructura base de carpetas y los archivos semilla requeridos por el plugin.
• sf metadelta monitor run inicia un monitor de terminal para detectar drift de metadatos Salesforce Core y Vlocity usando snapshots locales, Git local como motor de diff, manifiestos XML/YAML opcionales para scope específico, enriquecimiento de modificador Vlocity, log persistente JSONL y exportación CSV opcional.
• sf metadelta task record y sf metadelta task play graban/reproducen tareas de Salesforce con Playwright, estabilizadores automáticos de recuperación, reproducción sobre .metadelta.* y diagnósticos orquestados.
• sf metadelta cleanps genera una copia depurada de un permission set conservando solo los nodos que coincidan con un fragmento o con una lista permitida.
• sf metadelta findtest revisa las clases Apex dentro de un proyecto SFDX local, confirma la presencia de sus clases de prueba correspondientes y puede validar package.xml existentes antes de un despliegue. Los manifiestos generados o actualizados usan la versión de API que reporte la org de destino cuando esté disponible.
• sf metadelta manual collect consolida los documentos de pasos manuales almacenados en docs/, agrega índice y banner informativo y ofrece un modo parcial que solo incluye los archivos aún pendientes de merge en la rama base.
• sf metadelta merge busca archivos de manifiesto cuyos nombres contengan una subcadena específica, unifica sus miembros de metadatos sin duplicados y construye un globalpackage.xml consolidado (o el nombre de archivo que indiques).

Creado por Nerio Villalobos ([email protected]).

Índice

• Instalación
• sf metadelta find
• sf metadelta orgApiVersion
• sf metadelta finddelta
• sf metadelta postvalidate
• sf metadelta access
• sf metadelta security users
• sf metadelta initspace
• sf metadelta monitor run
• sf metadelta task record / task play
• sf metadelta cleanps
• sf metadelta findtest
• sf metadelta manual collect
• sf metadelta merge

Instalación

1. Instala Salesforce CLI (requiere versión 2.102.6 o superior):

   npm install --global @salesforce/[email protected]

2. Instala la última versión publicada en npm mediante Salesforce CLI (recomendado):

   sf plugins install @nervill/metadelta

   Para instalar específicamente esta versión:

   sf plugins install @nervill/[email protected]

   npmjs.com muestra npm i @nervill/metadelta como comando genérico para paquetes Node.js. Usa sf plugins install para registrar correctamente el paquete como plugin de Salesforce CLI.

   Confirma la instalación con sf plugins, que debe mostrar @nervill/metadelta 0.11.14.

3. Como alternativa, instala directamente la versión actual del repositorio en GitHub:

   sf plugins install github:NerioVillalobos/plugin-metadelta.git

   Confirma la instalación con sf plugins.

   

4. (Opcional, para desarrollo local) Clona este repositorio e instala las dependencias:

   git clone <repo-url>
   cd plugin-metadelta
   npm install

5. Vincula el plugin con tu Salesforce CLI local:

   npm run compile
   sf plugins link .

   Confirma la instalación con sf plugins, que debe mostrar @nervill/metadelta 0.11.14 (link).

Comando find

Explicación

El plugin compara los cambios de metadatos para el usuario especificado y muestra una tabla de componentes modificados. Cuando se solicita, también produce archivos de manifiesto en el directorio manifest/.

Uso

Ejecuta el comando desde cualquier directorio después de vincularlo:

sf metadelta find --org <alias_o_usuario> [banderas]

Banderas

| Bandera | Descripción | Valor por defecto | |--------|-------------|-------------------| | --org, -o | Requerido. Alias o usuario de la org de destino. | N/A | | --metafile | Ruta a un archivo JSON con la lista de tipos de metadatos que reemplazan la selección predeterminada. | Lista integrada | | --days | Número de días hacia atrás a inspeccionar por modificaciones. | 3 | | --namespace | Namespace de Vlocity para consultar datapacks (habilita las revisiones de datapacks). | Ninguno | | --xml | Si se especifica, genera manifest/package-<rama_o_org>[-v#].xml con los metadatos encontrados. El archivo resultante utiliza la versión de API obtenida de la org indicada cuando está disponible. | false | | --yaml | Si se especifica, genera manifest/package-vlocity-<rama_o_org>[-v#].yaml con entradas de datapacks de Vlocity. | false | | --audit | Nombre completo del usuario a auditar. Si se omite, el comando utiliza el usuario asociado al alias proporcionado. | Usuario autenticado |

Uso de un archivo de metadatos personalizado

Por defecto, el comando construye la lista de tipos de metadatos ejecutando sf force:mdapi:describemetadata --target-org, de modo que se mantenga sincronizada con la org conectada. Si la llamada de describe falla, se utiliza una lista integrada de respaldo. La lista resultante se filtra para conservar solo los tipos que exponen lastModifiedByName y lastModifiedDate, evitando consultas innecesarias. Además, se procesan como máximo cinco tipos de metadatos en paralelo para no saturar la memoria.

La bandera --metafile permite reemplazar la lista integrada de tipos de metadatos. Crea un archivo JSON (.json) que contenga un arreglo en la raíz o un objeto con la propiedad metadataTypes. El archivo debe incluir únicamente JSON plano (sin module.exports =) y usar codificación UTF-8.

Crea un archivo—for ejemplo mismetadatos.json—con el siguiente contenido:

{
  "metadataTypes": [
    "Bot", "BotVersion", "CustomPermission", "FlexiPage", "Flow",
    "GenAiFunction", "GenAiPlanner", "GenAiPlugin", "GenAiPlannerBundle",
    "PermissionSet", "Profile", "StaticResource", "PermissionSetGroup"
  ]
}

Ejemplo minimalista usando un arreglo directo:

[
  "ApexClass",
  "Flow"
]

Luego ejecuta el comando haciendo referencia al archivo (agrega ./ si está en la carpeta actual):

sf metadelta find --org miOrg --metafile ./mismetadatos.json

Consejo: Si antes utilizabas un archivo .js con module.exports, cámbiale la extensión a .json y elimina la asignación para que solo quede la estructura JSON.

Nota: Si la ruta al archivo contiene espacios o caracteres especiales, enciérrala entre comillas (por ejemplo, --metafile "./listas metadata/mismetadatos.json").

Ejemplos

• Escaneo básico para el usuario por defecto:

  sf metadelta find --org miOrg

• Auditar a un usuario diferente por los últimos siete días y crear un package.xml:

  sf metadelta find --org miOrg --audit "Jane Doe" --days 7 --xml

• Revisar datapacks de Vlocity con un namespace personalizado y generar un archivo de paquete de Vlocity:

  sf metadelta find --org miOrg --namespace miNS --yaml

Salida

El comando find imprime cada componente coincidente con su tipo, nombre completo, fecha de última modificación y usuario modificador. Cuando se establecen --xml o --yaml, los archivos de manifiesto correspondientes se crean dentro del directorio manifest/. Si el comando se ejecuta dentro de un repositorio Git, el nombre del archivo utiliza la rama actual; en caso contrario, emplea el alias de la org. Los archivos existentes se conservan agregando sufijos incrementales -v1, -v2, etc.

Comando orgApiVersion

Explicación

Imprime la versión de API reportada por una org de destino:

Uso

sf metadelta orgApiVersion --org <alias_o_usuario>

El comando ejecuta sf org display --target-org <alias> --json, extrae result.apiVersion e imprime únicamente el valor de la versión. También se usa internamente por comandos que necesitan alinear los manifiestos generados con la versión de API de la org.

Banderas

| Bandera | Descripción | Valor por defecto | |---------|-------------|-------------------| | --org, -o | Requerida. Alias o usuario de la org destino. | N/A |

Comando finddelta

Explicación

Genera manifiestos delta comparando dos ramas:

Uso

sf metadelta finddelta --from <rama_fuente> --to <rama_base> [--xml manifest/Release.xml] [--yaml manifest/vlocity.yaml]

Características

1. Ejecuta git diff --name-status <to>..<from> para detectar adiciones, eliminaciones y renombrados.
2. Genera manifiestos delta Core y Vlocity en manifest/ usando la rama from en el nombre de salida.
3. Crea manifiestos destructivos automáticamente cuando existen eliminaciones completas.
4. Si indicas --xml y/o --yaml, fusiona solo los componentes faltantes en los manifiestos destino (sin duplicados).

Comentarios

Endurecimiento de destructivos:

• ApexClass se emite solo cuando se eliminaron tanto el archivo .cls como su .cls-meta.xml.
• Vlocity se emite solo cuando la carpeta completa Vlocity/<DataPackType>/<DataPackName> no tiene archivos restantes en la rama from.

Salidas Core:

• manifest/<from>.xml
• manifest/Destructive-<from>.xml (solo cuando corresponde)

Salidas Vlocity:

• manifest/<from>.yaml
• manifest/Destructive-<from>.yaml (solo cuando corresponde)

Banderas

| Bandera | Descripción | |---------|-------------| | --from | Requerida. Rama fuente (normalmente la rama del PR). | | --to | Requerida. Rama base para la comparación. | | --xml | package.xml destino existente para incorporar componentes Core faltantes. | | --yaml | YAML destino existente para incorporar componentes Vlocity faltantes. |

Comando postvalidate

Explicación

Valida un despliegue recuperando nuevamente los manifiestos usados (package.xml para Salesforce Core y/o YAML para Vlocity), descargando los componentes en una carpeta temporal y comparándolos contra tus fuentes locales con una tabla colorizada Componente | Nombre | Diff, usando ✓ para coincidencias y ✗ para diferencias.

Características

1. Crea una carpeta temporal de retrieve y oculta la salida cruda de los comandos detrás de un spinner mientras se ejecutan.
2. Para Salesforce Core (--xml), ejecuta sf project retrieve start --manifest <xml> --target-org <org> --output-dir <tempDir>.
3. Para Vlocity (--yaml), ejecuta vlocity --sfdx.username <org> -job <yaml> packExport --maxDepth 0 dentro de la misma carpeta temporal.
4. Mapea los archivos Core recuperados contra el repositorio usando los packageDirectories de sfdx-project.json (incluyendo