COE Read Metadata

A powerful Salesforce CLI plugin that reads profile metadata from your org and converts it into YAML folder structures or XML files. Perfect for profile management, version control, and documentation.

Features

✨ Interactive CLI - User-friendly prompts for format selection and conversion confirmation 📋 Profile Metadata Export - Fetch complete profile metadata from your Salesforce org 🔄 Multiple Format Support - Convert to YAML (folder structure) or XML (deployable file) 📊 Detailed Output - Shows file counts, sizes, and conversion progress 🎨 Colored Output - Beautiful CLI messages with status indicators

Installation

Install this plugin as a Salesforce CLI plugin:

sf plugins install coe-read-metadata

Or install from source:

npm install -g coe-read-metadata

Quick Start

Basic Usage (Interactive)

sf metadata read profile -o <org-alias> -p "Profile Name"

This will:

1. Fetch the profile metadata from your org
2. Prompt you to choose between YAML or XML format
3. Ask for confirmation before converting
4. Display conversion results with file/folder statistics

With Format Flag (Non-Interactive)

Convert to XML:

sf metadata read profile -o <org-alias> -p "System Administrator" -f xml

Convert to YAML:

sf metadata read profile -o <org-alias> -p "System Administrator" -f yaml

Command Options

Required Flags

| Flag | Short | Description | | ---------------- | ----- | ----------------------------------------- | | --profile-name | -p | The name of the profile you want to fetch | | --target-org | -o | Username or alias of the Salesforce org |

Optional Flags

| Flag | Short | Description | Default | | ---------- | ----- | --------------------------- | ------- | | --format | -f | Output format (yaml or xml) | yaml |

Output Formats

YAML Format (Folder Structure)

Generates a nested folder structure with individual YAML files:

DS - System Administrator/
├── main.yaml                           # Profile metadata
├── applicationVisibilities.yaml        # Application visibility settings
├── classAccesses/
│   ├── Account.yaml
│   ├── Contact.yaml
│   └── ...
├── fieldPermissions/
│   ├── Account.yaml                    # Account field permissions
│   ├── Contact.yaml                    # Contact field permissions
│   └── ...
└── objectPermissions/
    ├── Account.yaml
    ├── Contact.yaml
    └── ...

Benefits:

• Easy version control with Git
• Granular permissions per object
• Human-readable format
• Simple to merge and review

XML Format (Single File)

Generates a single deployable XML file:

DS - System Administrator.profile-meta.xml

This file:

• Can be directly deployed to Salesforce
• Contains all profile metadata in standard XML format
• Compatible with Salesforce metadata API
• Perfect for backup and archival

<?xml version="1.0" encoding="UTF-8"?>
<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
    <applicationVisibilities>
        <application>Accelerator_Support_Console</application>
        <default>false</default>
        <visible>false</visible>
    </applicationVisibilities>
    <classAccesses>
        <apexClass>MyApexClass</apexClass>
        <enabled>true</enabled>
    </classAccesses>
    <fieldPermissions>
        <editable>true</editable>
        <field>Account.Name</field>
        <readable>true</readable>
    </fieldPermissions>
    ...
</Profile>

Usage Examples

Example 1: Export with Interactive Prompts

$ sf metadata read profile -o sfcoeprod -p "Sales Executive"

📋 Salesforce Profile Metadata Reader

Fetching profile: Sales Executive...
✓ Successfully fetched profile metadata

  JSON saved to: ./Sales Executive.json

? Choose output format: (Use arrow keys)
❯ yaml
  xml

? Convert profile to YAML format? (Y/n)

Converting to YAML format...
✓ Successfully converted to YAML

  Output folder: Sales Executive/ (2,847 files)

✨ Profile conversion complete!

Example 2: Direct XML Export

$ sf metadata read profile -o sfcoeprod -p "System Administrator" -f xml

📋 Salesforce Profile Metadata Reader

Fetching profile: System Administrator...
✓ Successfully fetched profile metadata

  JSON saved to: ./System Administrator.json

Converting to XML format...
✓ Successfully converted to XML

  Output file: System Administrator.profile-meta.xml (10.39 MB)

✨ Profile conversion complete!

Example 3: YAML Export for Git

$ sf metadata read profile -o production -p "Marketing Cloud User" -f yaml

📋 Salesforce Profile Metadata Reader

Fetching profile: Marketing Cloud User...
✓ Successfully fetched profile metadata

  JSON saved to: ./Marketing Cloud User.json

Converting to YAML format...
✓ Successfully converted to YAML

  Output folder: Marketing Cloud User/ (1,523 files)

✨ Profile conversion complete!

Then commit to version control:

git add "Marketing Cloud User/"
git commit -m "feat: export Marketing Cloud User profile"
git push origin main

Use Cases

1. Profile Backup & Recovery

Export critical profiles as XML files for backup and recovery purposes.

sf metadata read profile -o production -p "System Administrator" -f xml
# Store in secure backup location

2. Profile Documentation

Export profiles to YAML format for easy documentation and review.

sf metadata read profile -o production -p "Sales Manager" -f yaml
# Share YAML folder with stakeholders for review

3. Version Control & Collaboration

Track profile changes over time using Git:

sf metadata read profile -o staging -p "Standard User" -f yaml
git add "Standard User/"
git commit -m "chore: sync Standard User profile from staging"

4. Profile Migration

Export profile from source org, modify, and deploy to target org:

# Export from source
sf metadata read profile -o source-org -p "Custom Profile" -f xml

# Deploy to target (requires additional deploy command)
sf project deploy start -d ./

5. Audit & Compliance

Generate comprehensive profile reports for compliance documentation:

sf metadata read profile -o production -p "System Administrator" -f yaml
# YAML folder provides detailed permission breakdown for auditing

File Outputs

Generated Files

1. JSON File

   • Temporary file created during conversion
   • Raw metadata from Salesforce
   • Can be reused without re-querying the org

2. YAML Folder Structure

   • main.yaml - Profile metadata
   • *.yaml files - Simple array-based settings
   • {type}/ folders - Permissions grouped by object

3. XML File

   • Single .profile-meta.xml file
   • Ready for deployment
   • Standard Salesforce metadata format

Requirements

• Salesforce CLI (v2.0+)
• Valid Salesforce org authentication
• Read access to profiles in the target org

Troubleshooting

Profile Not Found

Error: Profile Profile_Name not found in the target org.

Solution: Verify the profile name exists and matches exactly (case-sensitive).

Permission Denied

Error: Insufficient privileges to read Profile metadata

Solution: Ensure your org user has the "Manage Profiles and Permission Sets" permission.

Large Profile Conversion

For very large profiles (millions of permissions), the conversion may take several minutes. Be patient and do not interrupt the process.

XML File Size

Profile XML files can be quite large (10+ MB for comprehensive profiles). This is normal and expected.

Output Structure Details

Field Permissions Organization

YAML Format: Field permissions are organized by object name for easy filtering:

fieldPermissions/
├── Account.yaml          # All Account field permissions
├── Contact.yaml          # All Contact field permissions
└── CustomObject__c.yaml  # All custom object field permissions

XML Format: Field permissions are listed as repeating elements:

<fieldPermissions>
    <editable>true</editable>
    <field>Account.Name</field>
    <readable>true</readable>
</fieldPermissions>

Object Permissions Organization

YAML Format: Grouped by object:

objectPermissions/
├── Account.yaml
├── Contact.yaml
└── Opportunity.yaml

XML Format: Flat list of object permissions.

Tips & Best Practices

1. Regular Exports

Export profiles regularly to track changes over time:

# Create a cron job to export weekly
0 8 * * 1 sf metadata read profile -o production -p "System Administrator" -f yaml

2. Use Meaningful Names

When committing to Git, use descriptive messages:

git commit -m "feat: add new field permissions to System Administrator"

3. Compare Profiles

Export multiple similar profiles and use diff tools:

sf metadata read profile -o org1 -p "Profile A" -f yaml
sf metadata read profile -o org2 -p "Profile B" -f yaml
diff -r "Profile A/" "Profile B/"

4. Store XML As Backup

Keep XML exports as emergency backups:

sf metadata read profile -o production -p "Critical Profile" -f xml
mkdir -p backups/$(date +%Y-%m-%d)
mv "Critical Profile.profile-meta.xml" backups/$(date +%Y-%m-%d)/

License

BSD-3-Clause

Support

For issues, questions, or feature requests, contact the Center of Excellence team.