Salesforce CLI Wrapper Scripts

A collection of convenient wrapper scripts for common Salesforce CLI operations. These scripts simplify complex sf commands by providing intuitive interfaces for deployment, testing, and org management tasks.

Available for both Unix/Linux/macOS (Bash) and Windows (PowerShell).

Overview

This toolkit provides four main utilities:

• sf-deploy - Streamlined wrapper for sf project deploy start
• sf-dry-run - Validation wrapper for sf project deploy start --dry-run
• sf-web-open - Quick org browser opener for sf org open
• sf-check - Environment verification tool to check SF CLI installation and configuration

Installation

Unix/Linux/macOS (Bash)

1. Clone or download this repository to your preferred tools directory
2. Make the scripts executable:

   chmod +x sf-deploy sf-dry-run sf-web-open sf-check
   

3. Add the directory to your PATH or create symlinks in a directory that's already in your PATH:

   # Option 1: Add to PATH (add to your ~/.zshrc or ~/.bashrc)
   export PATH="$PATH:/path/to/sf-cli-wrapper"
   
   # Option 2: Create symlinks
   ln -s /path/to/sf-cli-wrapper/sf-deploy /usr/local/bin/sf-deploy
   ln -s /path/to/sf-cli-wrapper/sf-dry-run /usr/local/bin/sf-dry-run
   ln -s /path/to/sf-cli-wrapper/sf-web-open /usr/local/bin/sf-web-open
   ln -s /path/to/sf-cli-wrapper/sf-check /usr/local/bin/sf-check
   

Windows (PowerShell)

1. Clone or download this repository to your preferred tools directory
2. Set the PowerShell execution policy to allow script execution (run as Administrator):

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
   

3. Add the directory to your PATH or create a PowerShell profile with aliases:

   # Option 1: Add to PATH (System Environment Variables)
   # Add C:\path\to\sf-cli-wrapper to your system PATH
   
   # Option 2: Create PowerShell aliases (add to your $PROFILE)
   Set-Alias sf-deploy "C:\path\to\sf-cli-wrapper\sf-deploy.ps1"
   Set-Alias sf-dry-run "C:\path\to\sf-cli-wrapper\sf-dry-run.ps1"
   Set-Alias sf-web-open "C:\path\to\sf-cli-wrapper\sf-web-open.ps1"
   Set-Alias sf-check "C:\path\to\sf-cli-wrapper\sf-check.ps1"
   

Scripts

sf-deploy

Wrapper for sf project deploy start that simplifies deploying multiple source files with optional test execution.

Usage:

sf-deploy -o <ORG_ALIAS_OR_USERNAME> (-s "<src1>,<src2>[,...]" | -d <DIRECTORY>) [-t "<Test1>,<Test2>[,...]"]

Options:

• -o - Org alias or username for --target-org
• -s - Comma-separated list of --source-dir paths
• -d - Single directory path to deploy (alternative to -s)
• -t - Comma-separated list of --tests (enables --test-level RunSpecifiedTests)
• -h - Show help

Examples:

# Deploy multiple flexipages (specific files)
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Page_Backup_With_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Deploy entire directory
sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"

# Deploy with specific tests
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" \
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"

sf-dry-run

Wrapper for sf project deploy start --dry-run that validates deployments without actually deploying.

Usage:

sf-dry-run -o <ORG_ALIAS_OR_USERNAME> (-s "<src1>,<src2>[,...]" | -d <DIRECTORY>) [-t "<Test1>,<Test2>[,...]"]

Options:

• -o - Org alias or username for --target-org
• -s - Comma-separated list of --source-dir paths
• -d - Single directory path to validate (alternative to -s)
• -t - Comma-separated list of --tests (enables --test-level RunSpecifiedTests)
• -h - Show help

Examples:

# Validate multiple flexipages (specific files)
sf-dry-run -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Validate entire directory
sf-dry-run -o DEMO-ORG -d "force-app/main/default/classes"

# Validate with specific tests
sf-dry-run -o DEMO-ORG \
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" \
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"

sf-web-open

Wrapper for sf org open that provides quick access to Salesforce orgs with optional path navigation.

Usage:

sf-web-open [-o <ORG_ALIAS_OR_USERNAME>] [-p <RELATIVE_PATH>] [-U]

Options:

• -o - Org alias or username to pass as --target-org
• -p - Relative path to open inside the org (e.g., "/lightning/setup/SetupOneHome/home")
• -U - URL-only: print the URL instead of opening a browser (passes --url-only)
• -h - Show help

Examples:

# Open a specific org (default home)
sf-web-open -o DEMO-ORG

# Open Setup Home of a target org
sf-web-open -o NUSHUB-DR2 -p "/lightning/setup/SetupOneHome/home"

# Get just the URL for scripting
sf-web-open -o NUSHUB-DR2 -U

# Open the current default org
sf-web-open

sf-check

Environment verification tool that checks if the Salesforce CLI is properly installed and configured.

Usage:

sf-check [-v] [-h]

Options:

• -v - Verbose output (show detailed information)
• -h - Show help

Examples:

# Basic environment check
sf-check

# Verbose output with detailed system information
sf-check -v

What it checks:

• SF CLI installation and version
• Authenticated orgs and default org configuration
• System requirements (Node.js, Git, etc.)
• SF CLI plugins and diagnostics
• Common configuration issues

Automatic Environment Verification

All wrapper scripts (sf-deploy, sf-dry-run, sf-web-open) include built-in environment verification:

✅ When SF CLI is installed (normal operation):

$ sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"
>>> Running: sf project deploy start --source-dir force-app/main/default/classes --target-org DEMO-ORG
# [deployment proceeds immediately]

❌ When SF CLI is missing:

$ sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"
❌ Salesforce CLI (sf) not found!

Running environment check to help you get started...

🔍 Salesforce CLI Environment Check
==================================
[✗] Salesforce CLI (sf) not found in PATH
  Please install the Salesforce CLI from: https://developer.salesforce.com/tools/sfdxcli
[✗] Unable to list orgs (sf org list failed)
[!] No default org configured
==================================
[✗] Some critical issues found. Please address them before using the SF CLI wrappers.

How It Works:

• Silent Check: Scripts automatically verify SF CLI availability
• Zero Performance Impact: Only activates when there's actually a problem
• Intelligent Discovery: Automatically finds and runs sf-check diagnostics
• Cross-Platform: Same experience on Bash and PowerShell
• User-Friendly: Clear error messages and actionable guidance

Windows PowerShell Examples

For Windows users, here are the PowerShell equivalents of the bash examples:

sf-deploy.ps1

# Deploy multiple flexipages (specific files)
sf-deploy.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Page_Backup_With_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Deploy entire directory
sf-deploy.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"

# Deploy with specific tests
sf-deploy.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" `
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"

sf-dry-run.ps1

# Validate multiple flexipages (specific files)
sf-dry-run.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Sample_Page.flexipage-meta.xml,force-app/main/default/flexipages/Sample_SalesNavigator.flexipage-meta.xml,force-app/main/default/flexipages/Sample_Role_Record_Page.flexipage-meta.xml"

# Validate entire directory
sf-dry-run.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"

# Validate with specific tests
sf-dry-run.ps1 -o "DEMO-ORG" `
  -s "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" `
  -t "SelectorOpportunity_Test,SelectorOpportunity2_Test"

sf-web-open.ps1

# Open a specific org (default home)
sf-web-open.ps1 -o "DEMO-ORG"

# Open Setup Home of a target org
sf-web-open.ps1 -o "NUSHUB-DR2" -p "/lightning/setup/SetupOneHome/home"

# Get just the URL for scripting
sf-web-open.ps1 -o "NUSHUB-DR2" -U

# Open the current default org
sf-web-open.ps1

Windows Common Workflows

# 1. First, validate your deployment (specific file)
sf-dry-run.ps1 -o "DEMO-ORG" -s "force-app/main/default/classes/MyClass.cls"

# 2. If validation passes, deploy for real
sf-deploy.ps1 -o "DEMO-ORG" -s "force-app/main/default/classes/MyClass.cls"

# 3. Open the org to verify changes
sf-web-open.ps1 -o "DEMO-ORG"

# Alternative: Deploy entire directory
sf-dry-run.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"
sf-deploy.ps1 -o "DEMO-ORG" -d "force-app/main/default/classes"

Prerequisites

• Salesforce CLI (sf): Make sure you have the Salesforce CLI installed and configured
• Shell Environment:
  • Unix/Linux/macOS: Bash 4.0+ (macOS users may need to upgrade from the default Bash 3.x)
  • Windows: PowerShell 5.1+ (PowerShell Core 7+ recommended)
• Authenticated Orgs: Ensure you have authenticated to the target orgs using sf org login

Common Workflows

Deployment with Validation

# 1. First, validate your deployment (specific file)
sf-dry-run -o DEMO-ORG -s "force-app/main/default/classes/MyClass.cls"

# 2. If validation passes, deploy for real
sf-deploy -o DEMO-ORG -s "force-app/main/default/classes/MyClass.cls"

# 3. Open the org to verify changes
sf-web-open -o DEMO-ORG

# Alternative: Deploy entire directory
sf-dry-run -o DEMO-ORG -d "force-app/main/default/classes"
sf-deploy -o DEMO-ORG -d "force-app/main/default/classes"

Working with Multiple Files

# Deploy multiple related components (specific files)
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/classes/MyController.cls,force-app/main/default/classes/MyControllerTest.cls,force-app/main/default/aura/MyComponent"

# Deploy entire directories
sf-deploy -o DEMO-ORG -d "force-app/main/default/aura"
sf-deploy -o DEMO-ORG -d "force-app/main/default/lwc"

Testing Specific Classes

# Deploy with specific test execution
sf-deploy -o DEMO-ORG \
  -s "force-app/main/default/classes/MyClass.cls" \
  -t "MyClassTest,RelatedClassTest"

Features

• Cross-Platform: Available for both Unix/Linux/macOS (Bash) and Windows (PowerShell)
• Automatic Environment Verification: Scripts automatically check if SF CLI is available and run diagnostics if not
• Error Handling: All scripts include robust error handling
• Help Documentation: Each script includes comprehensive help accessible with -h (both Bash and PowerShell)
• Flexible Input: Support for both absolute and repository-relative paths
• Command Echo: Shows the actual sf command being executed for transparency
• Multiple Sources: Easy handling of multiple source directories and test classes
• Parameter Validation: Scripts validate required parameters and show helpful error messages

Tips

1. Use Tab Completion: Most shells support tab completion for file paths when using these scripts
2. Combine with Git: Use git status to identify modified files for targeted deployments
3. Org Aliases: Set up meaningful org aliases with sf org login for easier reference
4. Path Flexibility: You can use both absolute paths and paths relative to your project root

Troubleshooting

Common Issues

1. "Command not found":
   • Unix/Linux/macOS: Ensure the scripts are executable and in your PATH
   • Windows: Check PowerShell execution policy and script location
2. "No default org found": Specify the org parameter or set a default org with sf config set target-org
3. "Source path not found": Verify file paths are correct relative to your project root
4. Windows PowerShell Execution Policy: If scripts won't run, check execution policy with Get-ExecutionPolicy

Debug Mode

To see exactly what command is being executed, look for the ">>> Running:" output that each script prints before execution.

Contributing

Feel free to extend these scripts or create additional wrappers for other Salesforce CLI commands. The scripts follow a consistent pattern:

Bash Scripts:

1. Help function with usage examples
2. Argument parsing with getopts
3. Command array building
4. Command execution with exec

PowerShell Scripts:

1. Parameter definitions with validation
2. Help function with usage examples
3. Parameter validation and processing
4. Command array building and execution

License

These scripts are provided as-is for convenience. Modify and distribute as needed for your projects.