sf-package-list
Version:
Convert Salesforce manifest files (package.xml) into list format.
212 lines (148 loc) • 6.81 kB
Markdown
# `sf-package-list`
[](https://www.npmjs.com/package/sf-package-list)
[](https://npmjs.org/package/sf-package-list)
[](https://raw.githubusercontent.com/mcarvin8/sf-package-list/main/LICENSE.md)
[](https://qlty.sh/gh/mcarvin8/projects/sf-package-list)
[](https://qlty.sh/gh/mcarvin8/projects/sf-package-list)
[](https://snyk.io//test/github/mcarvin8/sf-package-list?targetFile=package.json)
A Salesforce CLI plugin that helps you convert `package.xml` files to a simple, human-readable list format—and back again.
This makes working with metadata easier for admins and developers, especially in version control systems, automation pipelines, or anywhere you want to quickly review or edit what’s being deployed.
<details>
<summary>Table of Contents</summary>
- [Install](#install)
- [What It Does](#what-it-does)
- [Why Use It?](#why-use-it)
- [Examples](#examples)
- [Commands](#commands)
- [`sf sfpl list`](#sf-sfpl-list)
- [`sf sfpl xml`](#sf-sfpl-xml)
- [Troubleshooting](#troubleshooting)
- [Use Case](#use-case)
- [Issues](#issues)
- [License](#license)
</details>
## Install
```bash
sf plugins install sf-package-list@x.y.z
```
## What It Does
This plugin lets you:
- Convert a Salesforce `package.xml` to a cleaner, flat **package list**
- Convert a **package list** back into a valid `package.xml`
Both directions are supported so you can go back and forth easily.
## Why Use It?
Salesforce `package.xml` files can be verbose and tricky to edit manually. This tool simplifies that by providing a flat list format that’s:
- **Easy to Read** – You can quickly scan and understand what metadata is included.
- **Easy to Edit** – Add, remove, or change metadata items without worrying about XML syntax.
- **Git-Friendly** – Cleaner diffs and fewer merge conflicts.
- **Script-Friendly** – Perfect for CI/CD and automation pipelines.
- **Admin-Friendly** – No XML knowledge required to contribute to or understand metadata lists.
## Examples
### `package.xml`
```xml
<?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>
```
### Package List
> Separate multiple metadata members using a comma.
```
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
```
## Commands
### `sf sfpl list`
Convert a `package.xml` to a flat list format.
```
USAGE
$ sf sfpl list [-x <value>] [-l <value>] [-n] [--json]
FLAGS
-x, --package-xml=<value> Path to the package.xml to convert.
-l, --package-list=<value> Where to save the converted list. [default: package.txt]
-n, --no-api-version Exclude API version from the output. [default: false]
GLOBAL FLAGS
--json Format output as JSON.
EXAMPLES
Convert and save list format:
$ sf sfpl list -x package.xml -l package.txt
Convert and exclude API version:
$ sf sfpl list -x package.xml -l package.txt -n
```
### `sf sfpl xml`
Convert a package list back into a `package.xml`.
```
USAGE
$ sf sfpl xml [-x <value>] [-l <value>] [-n] [--json]
FLAGS
-l, --package-list=<value> Path to the package list file.
-x, --package-xml=<value> Where to save the generated package.xml. [default: package.xml]
-n, --no-api-version Exclude API version from the generated XML. [default: false]
GLOBAL FLAGS
--json Format output as JSON.
EXAMPLES
Convert list to package.xml:
$ sf sfpl xml -x package.xml -l package.txt
Convert list to package.xml without API version:
$ sf sfpl xml -x package.xml -l package.txt -n
```
## Troubleshooting
If the provided `package.xml` to convert to list format is invalid or has no components, you’ll get this warning:
```
Warning: The provided package is invalid or has no components. Confirm package is a valid Salesforce package.xml.
```
If the provided package list to convert to XML format has invalid lines, each invalid line will be skipped with a warning:
```
Warning: Line does not match expected package list format and will be skipped: ${line}
```
By default, the output of both commands will be an empty file, either an empty `package.xml` (no `<types>` in it) or an empty package list text file.
The plugin should not fail even if the inputs are invalid or missing.
## Use Case
We use this plugin alongside `sfdx-git-delta` to build deployment packages from git diffs. But we also let developers specify extra metadata via GitLab merge request descriptions or commit messages.
Instead of copying and pasting a `package.xml` (which is error-prone), they can just list the metadata in this simple format. It’s faster, cleaner, and works well with automation.
We also use this format to support destructive deployments triggered from GitLab’s web UI. Users can input a package list into a form field (CI/CD variable), and this plugin turns it into a `destructiveChanges.xml`.
## Issues
Found a bug or have an idea? [Open an issue](https://github.com/mcarvin8/sf-package-list/issues).
## License
This project is licensed under the [MIT License](https://raw.githubusercontent.com/mcarvin8/sf-package-list/main/LICENSE.md).