salesforce-metadata-writer

name

salesforce-metadata-writer

description

Declaratively update Salesforce Metadata API XML files using YAML/JSON instruction files. Use this skill when the user asks you to modify, update, add, remove, rename, replace, or move elements in Salesforce metadata XML files such as Custom Objects, Profiles, Permission Sets, Flows, Layouts, or any other Salesforce XML metadata. Pair with salesforce-metadata-reader for read-modify-write workflows.

salesforce-metadata-writer

A CLI tool that declaratively updates Salesforce metadata XML using YAML/JSON instruction files.

When to Use

Use salesforce-metadata-writer whenever you need to:

• Modify field values, labels, or settings in Salesforce metadata XML
• Add new fields, validation rules, record types, or child elements
• Remove deprecated fields, permissions, or metadata components
• Replace text content with exact, contains, or regex matching
• Rename XML elements across metadata files
• Move elements from one location to another within a file
• Batch apply changes across multiple metadata files

Quick Start

Run the wrapper script from this skill's directory:

# Unix (macOS / Linux)
./scripts/run.sh --instructions <INSTRUCTION_FILE>

# Windows (PowerShell)
.\scripts\run.ps1 --instructions <INSTRUCTION_FILE>

Binary location from this skill's directory:

./bin/sfmeta-write-darwin-aarch64
./bin/sfmeta-write-darwin-x86_64
./bin/sfmeta-write-linux-aarch64
./bin/sfmeta-write-linux-x86_64
./bin/sfmeta-write-windows-x86_64

Instruction File Format

Create a YAML instruction file to describe your changes:

version: "1"
target: path/to/Account.object-meta.xml
variables:
  field_name: AnnualRevenue
operations:
  - action: set
    path: "/CustomObject/fields[fullName='${field_name}']/required/#text"
    value: "true"
    description: Make AnnualRevenue required

  - action: add
    path: /CustomObject
    content:
      fields:
        fullName: NewField__c
        type: Text
        label: New Field
        length: "255"

  - action: remove
    path: "/CustomObject/fields[fullName='OldField__c']"
    confirm: true

  - action: replace
    path: "/CustomObject/fields[fullName='Revenue']/label/#text"
    old_value: Revenue
    new_value: Total Revenue
    match_type: exact   # exact | contains | regex

Supported Actions

Action	Required Fields	Description
set	path, value	Set text content of an element
add	path, content	Add a new child element
remove	path, confirm: true	Remove an element
replace	path, old_value, new_value	Replace text content
rename	path, new_name	Rename an element
move	from_path, to_path	Move an element to a new location

Common Workflows

1. Apply Instructions to a Metadata File

./scripts/run.sh --instructions update-fields.yaml

2. Dry Run (Preview Without Writing)

./scripts/run.sh --instructions update-fields.yaml --dry-run

Review the diff output before applying changes.

3. Create Backup Before Modifying

./scripts/run.sh --instructions update-fields.yaml --backup --keep-backups 5

4. Rollback to a Previous Backup

./scripts/run.sh --rollback path/to/Account.object-meta.xml.bak.20260215_140000

5. Read → Modify → Write Workflow

# Step 1: Read current state with sfmeta-reader
./scripts/run.sh --input Account.object-meta.xml --format toon

# Step 2: Create instruction file based on analysis
cat > update.yaml << 'EOF'
version: "1"
target: Account.object-meta.xml
operations:
  - action: set
    path: "/CustomObject/fields[fullName='AnnualRevenue']/required/#text"
    value: "true"
EOF

# Step 3: Apply changes with sfmeta-write
./scripts/run.sh --instructions update.yaml --dry-run     # preview
./scripts/run.sh --instructions update.yaml --backup       # apply

6. Validate After Modification

./scripts/run.sh --instructions update-fields.yaml --validate

Path Addressing

Paths use XPath-like syntax to target elements:

Pattern	Example	Description
Predicate	fields[fullName='Revenue']	Match by child element value
Index	fields[5]	Match by position (0-based)
Wildcard	fields[*]	Match all siblings
Text	required/#text	Target text content

Key CLI Options

Option	Description
--instructions <FILE>	YAML/JSON instruction file
--output <FILE>	Write to file instead of in-place
--dry-run	Preview changes without writing
--backup	Create timestamped backup before modifying
--keep-backups <N>	Number of backups to retain
--rollback <BACKUP>	Restore from a backup file
--validate	Validate XML structure before and after
--partial	Allow partial success (default: atomic)
--verbose	Detailed operation logging

For the full CLI reference, see resources/reference.md.