SFDMU: moving related Salesforce objects between orgs in one run

Org to org without the CSV detour

The SFDX Data Move Utility is described as an advanced SF CLI plugin designed to make data migration simpler within various Salesforce environments, including scratch, development, sandbox and production orgs. It supports migration from other Salesforce orgs or CSV files and manages various data operations, enabling the migration of multiple related sObjects in a single run. The first key feature is the one that changes the workflow, comprehensive migration support that enables direct org-to-org data migration, eliminating the need for CSV intermediates, with support for the four CRUD operations, Insert, Upsert, Update and Delete. The second is that it manages migrations involving multiple object sets and handles complex relationships, including circular references, which is the hard case in Salesforce data movement. A reference relationship between two objects, where a child points at a parent and the parent points back at the child, cannot be satisfied by a single ordered pass, and a tool that claims to handle it in one run is doing real work. The third feature is simplicity of configuration, since the whole job is described by a single export.json file, and the fourth is the one that matters for anyone handling real data, that all operations are performed locally without cloud interactions. The package description is blunter about the goal, that it will help you to populate your org with data in minutes.

The version five rewrite, and the rollback that comes with it

The version notice is the part of the README that every adopter should read first. A new improved v5 version of the SFDMU plugin was recently released, built on the latest SF CLI plugin architecture and including the latest available security updates, and the project recommends using the latest available plugin version. Then the honest caveat, that if it does not work correctly in your environment yet, you should temporarily roll back to v4.39.0. SFDMU is supported as an SF CLI plugin, invoked with sf sfdmu run, and the full migration guidance is on the Get Started page of the help centre. The plugin is installed through the Salesforce CLI rather than from npm, even though there is an npm package badge in the README, because the sf plugins commands manage the plugin lifecycle. The install sequence is therefore a set of sf plugins uninstall and sf plugins install operations, and the version you want is expressed as sfdmu@latest or [email protected]. The repository has a separate release log alongside a changelog, and the recent tags are v5.8.0, v5.7.2 and v5.7.1, all dated 2026-07-03, which tells you the v5 line was being iterated on quickly around that date, with the last push to the repository on the same day.

Installing through the CLI, and pinning a version when you need to

The installation steps start with preparing the environment, which means installing the Salesforce CLI following the official instructions. Then the plugin itself, with the old version removed first if one is present.

   # Uninstall old version, if any:
   $ sf plugins uninstall sfdmu

   # Install the latest published plugin version:
   $ sf plugins install sfdmu@latest

Rolling back is the same pair of commands with an older version, and the README gives the previous stable line as 4.39.0.

   # Remove current plugin:
   $ sf plugins uninstall sfdmu

   # Install previous stable version:
   $ sf plugins install [email protected]

Moving forward again later is a single install, and pinning a specific version is the same form with a placeholder.

   $ sf plugins install sfdmu@latest

   $ sf plugins install sfdmu@<version>

The pattern is worth noting for CI, where a pinned version in the pipeline is the difference between a reproducible build and one that silently changes behaviour when a new plugin version ships. The README's own advice to fall back to a known-good version when the new one misbehaves in your environment is the sort of thing that is easy to do with a plugin and impossible with a compiled binary, and it is a good reason to keep the rollback version noted somewhere obvious.

Debug logs and the anonymise flag

The last installation step is the one that tells you how to report a problem well, and it is the most practically useful line in the README. If you find a bug in the new improved version, the README asks you to report it with diagnostic logs, and the command to produce them takes a source and a target org plus two flags.

   $ sf sfdmu run --sourceusername [email protected] --targetusername [email protected] --diagnostic --anonymise

You then attach the full generated .log file, your export.json and the related CSV samples, and the README explains that the anonymise flag hashes sensitive values in .log files before sharing, with a full masking list available in the documentation for log file management in plugin migrations. That distinction between what is masked and what is not is the sort of detail that determines whether you can actually attach a log to a public issue, since a migration log contains record identifiers and values from a real org. The README also links a user support policy with guidelines to review before opening support cases, and a separate code contribution policy, which is the standard shape for a project with a large user base and a formal support boundary.

One export.json describes the whole job

Migration configuration is a single export.json file, and the README gives a basic example that upserts Accounts and their related Contacts, assuming a unique Name for Accounts and a unique LastName for Contacts across the source and target orgs. The structure is an objects array where each entry names the operation, the external ID field to match on, a query selecting the fields to move, and whether the object is a master in a master-detail relationship. That master flag is the mechanism behind the relationship handling, since it tells the tool which side of a relationship owns the ordering, and it is what makes a multi-object run reproducible. The externalId entry is the second half of the matching story, because an upsert has to know what identifies an existing record in the target org, and the assumption in the example is that a Name is unique for Accounts and a LastName is unique for Contacts in both orgs, which is a strong assumption and a common source of surprise. The documentation also links the full export.json format guide for the objects specification, and the advanced features pages for custom field mapping, data anonymization and composite external ID keys. The composite external ID support is worth knowing about, since it is the answer to the case where no single field is unique and you need a multi-field key, which is common for imported data. The tool also offers a desktop GUI application in a separate repository, for creating, managing and executing migrations without writing the export.json by hand.

Where SFDMU is the wrong choice

The first limit is that this is a data movement tool for a specific platform, and the value depends on the shape of your Salesforce work. If you are moving one object once, the built-in data loader or a manual export and import does the job, and learning an export.json format for it is overhead. The second is the version churn. The v5 rewrite on the new plugin architecture is a significant change with a documented fallback to v4.39.0, and while the rollback path is clear, a team whose pipelines were written against v4 now has two configurations to maintain, and the v4 line will not receive the new features or the latest security updates. The third is the dependency on Salesforce CLI, which means the tool inherits the CLI's own installation requirements, its plugin lifecycle commands and its own versioning, and it means SFDMU is not usable outside the sf command. The fourth is the query-based matching model, where the upsert depends on a field being unique in both orgs, and a source org with duplicate values in that field will produce surprising behaviour that is not obvious from the config. The fifth is that the field mapping and anonymisation features are exactly the kind of thing that needs verification before a real run, since anonymisation applies to the log output rather than necessarily to the migrated data, and a team moving real customer records should confirm what happens to sensitive fields in flight. Nothing here is a defect, but it is a tool where a dry run on a scratch org is worth more than a careful read of the documentation.

Editorial conclusion

Adopt SFDMU if you populate Salesforce orgs repeatedly and need related objects moved together with their relationships intact, and you want to skip the CSV extract and reload cycle. Skip it if your migration is a one-off with a single object, where the built-in data loader is enough. Verify first whether you are on the v5 line or need to roll back to v4.39.0 for your environment, that the export.json you write matches the documented format, and whether the objects you move use external ID keys so that upserts behave the way you expect.

Frequently asked questions

Official sources

1. forcedotcom/SFDX-Data-Move-Utility on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases