DTS Salesforce COE Meta Reader

A powerful Salesforce CLI plugin that makes it super easy to read and export Profile metadata from your Salesforce orgs. Perfect for Salesforce developers who want to backup, analyze, or compare Profile configurations!

🎯 What Does This Plugin Do?

This plugin helps you:

✅ Read Profile Metadata - Easily extract Profile configuration from any Salesforce org
✅ Export to XML - Get your Profile data in standard XML format
✅ Backup Profiles - Create backup copies of your Profile configurations
✅ Analyze Permissions - Review all permissions, object access, and field-level security in one file

Think of it as a super-powered way to download and view Profile details without using the Salesforce UI!

📋 Prerequisites

Before you can use this plugin, make sure you have:

1. Node.js (version 18 or higher) - Download here

   • If you're not sure if you have Node.js, open PowerShell and run: node --version

2. Salesforce CLI - Installation guide

   • If already installed, verify with: sf --version

3. An authenticated Salesforce org - Learn how to authenticate

New to CLI? Don't worry! We'll walk you through each step below. 👇

🚀 Installation Guide

Step 1: Install Node.js (Skip if already installed)

1. Visit nodejs.org
2. Download the LTS (Long Term Support) version
3. Run the installer and follow the prompts
4. Open PowerShell and verify: node --version

Step 2: Install Salesforce CLI (Skip if already installed)

1. Open PowerShell as Administrator
2. Run this command:

   npm install --global @salesforce/cli

3. Verify installation: sf --version

Step 3: Install This Plugin

Once you have Salesforce CLI installed, install this plugin:

sf plugins install dts-sf-coe-meta-reader

Verify the plugin is installed:

sf plugins

You should see dts-sf-coe-meta-reader in the list of installed plugins.

🔗 Authentication: Connect to Your Salesforce Org

Before you can use the plugin, you need to authenticate with your Salesforce org.

Option 1: Web Login (Recommended - Easiest!)

sf auth web login --alias my-org

This will:

1. Open your browser
2. Ask you to log in to Salesforce
3. Ask for permission to connect Salesforce CLI
4. Click "Allow" and you're done!

Replace my-org with any name you want for this org (example: sf auth web login --alias production or sf auth web login --alias sandbox)

Option 2: For Orgs Without Browser Access

If you need to authenticate without a browser:

sf auth device login --alias my-org

Then follow the on-screen instructions to complete the authentication.

📖 How to Use This Plugin

List All Available Orgs

Before running any commands, see which orgs you have authenticated:

sf org list

You'll see something like:

Alias          Username              Type
─────────────  ────────────────────  ─────
my-org         [email protected]   Production
my-sandbox     [email protected]     Sandbox

💡 Main Command: Read Profile Metadata

Basic Usage

Extract a Profile from your Salesforce org:

sf read profile --profile "Admin" --targetOrg my-org

What this does:

1. Connects to the org named my-org
2. Reads the Profile named "Admin"
3. Asks for confirmation
4. Creates a file called Admin-profile.xml in your current folder
5. The XML file contains all Profile details (permissions, object access, field-level security, etc.)

Parameters Explained

| Parameter | Short Flag | Required? | Description | | ------------- | ---------- | --------- | ---------------------------------------------------------------------------------------------- | | --profile | -p | ✅ Yes | The exact name of the Profile to read (e.g., "Admin", "Standard User", "System Administrator") | | --targetOrg | -o | ✅ Yes | The alias of the org you authenticated (from sf org list) | | --name | -n | ❌ No | Optional custom name for the output file |

Examples

Example 1: Export Admin Profile from Production

sf read profile --profile "System Administrator" --targetOrg production

Creates: System Administrator-profile.xml

Example 2: Export Custom Profile from Sandbox

sf read profile --profile "Custom Sales User" --targetOrg my-sandbox

Creates: Custom Sales User-profile.xml

Example 3: Export with Custom Output Name

sf read profile --profile "Admin" --targetOrg my-org --name "admin-backup-2024"

Creates: admin-backup-2024.xml

📁 Where Does the Output Go?

The exported Profile XML file is saved in your current working directory (the folder you're in when you run the command).

To change where files are saved:

# Navigate to your desired folder first
cd C:\Users\YourUsername\Desktop

# Then run the command
sf read profile --profile "Admin" --targetOrg my-org

The file will now be saved to your Desktop!

🛠️ Common Issues & Solutions

Issue: "Profile not found"

Solution: Check the exact Profile name in Salesforce:

1. In Salesforce, go to Setup > Users > Profiles
2. Find the exact name of the Profile
3. Use that exact name in the command (names are case-sensitive!)

Issue: "No such plugin"

Solution: The plugin wasn't installed. Run:

sf plugins install dts-sf-coe-meta-reader

Issue: "Not authenticated"

Solution: You need to authenticate first. Run:

sf auth web login --alias my-org

Issue: "Command not found" / "'sf' is not recognized"

Solution: Salesforce CLI isn't installed or not in your PATH. Reinstall it:

npm install --global @salesforce/cli

📝 Understanding the Output XML File

When you export a Profile, you get an XML file that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<Profile>
  <classAccess>
    <apexClass>MyApexClass</apexClass>
    <enabled>true</enabled>
  </classAccess>
  <objectPermissions>
    <object>Account</object>
    <allowCreate>true</allowCreate>
    <allowRead>true</allowRead>
    <allowUpdate>true</allowUpdate>
    <allowDelete>false</allowDelete>
  </objectPermissions>
  <!-- More permissions... -->
</Profile>

You can:

• 📖 Read it - Understand what permissions the Profile has
• 💾 Backup it - Keep a version history of Profile changes
• 📊 Compare it - Diff two profiles to see what changed
• 📤 Deploy it - Use it with Salesforce CLI to update profiles in other orgs

🤝 Support & Feedback

Found a bug? Have a feature request? Create an issue or contact the development team.

📚 Learn More

• Salesforce CLI Documentation: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference.htm
• Profile Metadata Reference: https://developer.salesforce.com/docs/atlas.en-us.meta_api_meta.meta/meta_api_meta/meta_profiles.htm
• Salesforce DX Guide: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev_guide.meta/sfdx_dev_guide/sfdx_dev_guide_intro.htm

📄 License

BSD-3-Clause License - See LICENSE file for details

Happy developing! 🚀

Made with ❤️ for Salesforce developers

For Developers: Contributing & Building

Build

This repository provides a template for creating a plugin for the Salesforce CLI. To convert this template to a working plugin:

1. Please get in touch with the Platform CLI team. We want to help you develop your plugin.

2. Generate your plugin:

   sf plugins install dev
   sf dev generate plugin
   
   git init -b main
   git add . && git commit -m "chore: initial commit"

3. Create your plugin's repo in the salesforcecli github org

4. When you're ready, replace the contents of this README with the information you want.

Tooling

This plugin uses several Salesforce development packages:

• @salesforce/core
• @salesforce/sf-plugins-core
• @salesforce/dev-config
• @salesforce/dev-scripts

Read more about Salesforce CLI plugin development.