sf-package-list

Salesforce CLI plugin to convert package.xml files to a human-readable list format—and back.

Install

sf plugins install sf-package-list

List Format

Each metadata type gets one line: TypeName: member1, member2, ...

CustomLabel: Always_Be_Closing, Attention_Interest_Decision_Action, Leads_Are_Gold
CustomObject: ABC, Glengarry, Mitch_And_Murray
CustomField: Glengarry.Weak_Leadz__c, Coffee.is_Closer__c
EmailTemplate: unfiled$public/Second_Prize_Set_of_Steak_Knives
StandardValueSet: Glengarry_Leads, Cadillac_Eldorado
Version: 59.0

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Always_Be_Closing</members>
        <members>Attention_Interest_Decision_Action</members>
        <members>Leads_Are_Gold</members>
        <name>CustomLabel</name>
    </types>
    <types>
        <members>ABC</members>
        <members>Glengarry</members>
        <members>Mitch_And_Murray</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>Glengarry.Weak_Leadz__c</members>
        <members>Coffee.is_Closer__c</members>
        <name>CustomField</name>
    </types>
    <types>
        <members>unfiled$public/Second_Prize_Set_of_Steak_Knives</members>
        <name>EmailTemplate</name>
    </types>
    <types>
        <members>Glengarry_Leads</members>
        <members>Cadillac_Eldorado</members>
        <name>StandardValueSet</name>
    </types>
    <version>59.0</version>
</Package>

Commands

sf sfpl list

package.xml → list

sf sfpl list -x <package.xml> [-l <output.txt>] [-n]

| Flag | Short | Default | Description | | ------------------ | ----- | ------------- | -------------------------------- | | --package-xml | -x | — | Path to the source package.xml | | --package-list | -l | package.txt | Output path for the list file | | --no-api-version | -n | false | Omit API version from output |

sf sfpl xml

list → package.xml

sf sfpl xml -l <list.txt> [-x <package.xml>] [-n]

| Flag | Short | Default | Description | | ------------------ | ----- | ------------- | ------------------------------------------- | | --package-list | -l | — | Path to the source list file | | --package-xml | -x | package.xml | Output path for the generated package.xml | | --no-api-version | -n | false | Omit API version from output |

Use Cases

CI/CD Pipelines

The list format is easier to diff, review, and edit than XML, making it well suited for pull requests, merge requests, deployment approvals, and release workflows.

Because metadata is represented in a concise text format, pipeline logs can clearly show exactly what will be deployed before a deployment step executes.

Example deployment manifest:

CustomObject: Invoice__c
CustomField: Invoice__c.Status__c, Invoice__c.Amount__c
ApexClass: InvoiceController

This provides a human-readable deployment summary without requiring reviewers to inspect generated XML.

Controlled Destructive Deployments

Use a package list as a restricted allowlist of metadata to remove.

Teams can maintain destructive changes in source control as a simple text file, review them during change approval, convert them to destructiveChanges.xml during pipeline execution, and deploy only the explicitly declared components.

This approach helps reduce the risk of accidentally deleting metadata that was not intended to be included in a destructive deployment.

Pipeline-Driven Metadata Selection

Store metadata selections in CI variables, deployment parameters, release manifests, or generated artifacts.

The list format is compact enough to be:

• Generated by automation
• Passed between pipeline stages
• Embedded in release tickets
• Stored as deployment manifests alongside source code

and then converted to package.xml only when needed.

Release Management and Change Review

Use package lists as lightweight deployment manifests that can be reviewed by administrators, release managers, and auditors.

The format is intentionally simple enough for non-developers to verify:

CustomLabel: Feature_Flag_X
PermissionSet: Sales_User
Flow: Lead_Routing

without needing Salesforce metadata XML knowledge.

Metadata-as-Data Automation

Generate deployment manifests programmatically from:

• Change requests
• Ticketing systems
• Environment promotion tools
• Custom release automation
• Internal deployment portals

The resulting list can be transformed into a valid package.xml immediately before deployment, allowing automation to work with a simple text representation instead of XML.

Documentation and Communication

Package lists are easy to paste into:

• Pull requests
• Change requests
• Release notes
• Deployment approvals
• Team chat discussions

This makes it easier to communicate deployment scope than sharing raw package.xml files.

Troubleshooting

Invalid package.xml — Errors from @salesforce/source-deploy-retrieve (unknown types, parse failures) surface as warnings and produce empty output. If a type is unrecognized, the SDR version bundled with this plugin may predate that metadata type; upgrading the plugin may resolve it.

Invalid list lines — Each malformed line is skipped with a warning. Valid lines still produce output. Metadata type names are also validated against the SDR registry; unknown types are skipped with a warning. If a type is unrecognized, the SDR version bundled with this plugin may predate that metadata type; upgrading the plugin may resolve it.

The plugin never throws on bad input—it warns and continues.

Issues

Found a bug or have a feature request? Open an issue.

License

MIT