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 a suite of cross-platform wrappers to streamline common Salesforce CLI workflows:

Core:

• 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

Org and metadata:

• sf-org-create / sf-org-create.ps1 - Smart scratch org creation
• sf-org-info / sf-org-info.ps1 - Quick org info, limits, and context
• sf-retrieve / sf-retrieve.ps1 - Streamlined metadata retrieval (types, manifest, packages)

Apex and tests:

• sf-test-run / sf-test-run.ps1 - Focused Apex test execution with coverage
• sf-apex-run / sf-apex-run.ps1 - Anonymous Apex execution (file or inline)

Data and logs:

• sf-data-export / sf-data-export.ps1 - Export data via SOQL to CSV/JSON, optional Bulk API
• sf-data-import / sf-data-import.ps1 - Import CSV/JSON with insert/update/upsert
• sf-logs-tail / sf-logs-tail.ps1 - Real-time debug logs tail with filtering

Two-Character Option Scheme

All scripts use an innovative two-character option scheme based on syllables, making options more memorable and self-documenting than traditional single-character flags:

Core Options (consistent across scripts)

• -to, --target-org - Target Org
• -hp, --help - HelP
• -vb, --verbose - VerBose

File & I/O Options

• -fl, --file - FiLe
• -ot, --output - OuTput
• -fm, --format - ForMat

Data & Query Options

• -qy, --query - QuerY
• -so, --sobject - S-Object
• -bk, --bulk - BulK

Operation & Control Options

• -op, --operation - Operation
• -wt, --wait - WaiT
• -lv, --level - LeVel

Benefits

• More Memorable: -to for target-org is intuitive vs cryptic -o
• Self-Documenting: Users can often guess what -fm means (format)
• No Conflicts: Two characters eliminates option conflicts between scripts
• Consistent: Same long option always maps to same short option across all scripts
• Scalable: Room for many more options without running out of meaningful combinations

Example Usage

# Traditional approach would be:
# sf-data-export -q "SELECT Id FROM Account" -o myorg -f csv

# Our approach:
sf-data-export -qy "SELECT Id FROM Account" -to myorg -fm csv

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 \
     sf-org-create sf-org-info sf-retrieve sf-test-run sf-apex-run \
     sf-data-export sf-data-import sf-logs-tail
   

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 ln -s /path/to/sf-cli-wrapper/sf-org-create /usr/local/bin/sf-org-create ln -s /path/to/sf-cli-wrapper/sf-org-info /usr/local/bin/sf-org-info ln -s /path/to/sf-cli-wrapper/sf-retrieve /usr/local/bin/sf-retrieve ln -s /path/to/sf-cli-wrapper/sf-test-run /usr/local/bin/sf-test-run ln -s /path/to/sf-cli-wrapper/sf-apex-run /usr/local/bin/sf-apex-run ln -s /path/to/sf-cli-wrapper/sf-data-export /usr/local/bin/sf-data-export ln -s /path/to/sf-cli-wrapper/sf-data-import /usr/local/bin/sf-data-import ln -s /path/to/sf-cli-wrapper/sf-logs-tail /usr/local/bin/sf-logs-tail

### 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):
   ```powershell
   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" Set-Alias sf-org-create "C:\path\to\sf-cli-wrapper\sf-org-create.ps1" Set-Alias sf-org-info "C:\path\to\sf-cli-wrapper\sf-org-info.ps1" Set-Alias sf-retrieve "C:\path\to\sf-cli-wrapper\sf-retrieve.ps1" Set-Alias sf-test-run "C:\path\to\sf-cli-wrapper\sf-test-run.ps1" Set-Alias sf-apex-run "C:\path\to\sf-cli-wrapper\sf-apex-run.ps1" Set-Alias sf-data-export "C:\path\to\sf-cli-wrapper\sf-data-export.ps1" Set-Alias sf-data-import "C:\path\to\sf-cli-wrapper\sf-data-import.ps1" Set-Alias sf-logs-tail "C:\path\to\sf-cli-wrapper\sf-logs-tail.ps1"

## Scripts

### sf-org-create / sf-org-create.ps1

Smart scratch org creation with templates and intelligent defaults.

**Usage:**
```bash
sf-org-create -al ALIAS -dd DAYS -df TEMPLATE [--no-namespace]

sf-org-create.ps1 -al "MySO" -dd 7 -df "config/project-scratch-def.json"

Examples:

# Create scratch org with alias and 7-day duration
sf-org-create -al MyScratch -dd 7

# Use specific definition file
sf-org-create -al DevOrg -df config/project-scratch-def.json

sf-org-info / sf-org-info.ps1

Display org information, limits, and list authenticated orgs.

Usage:

sf-org-info -to ORG [--limits] [--list] [-vb]

sf-org-info.ps1 -to "myorg" -Limits -vb

Examples:

# Show org info for specific org
sf-org-info -to MyOrg

# Show limits and verbose info
sf-org-info -to MyOrg --limits -vb

sf-retrieve / sf-retrieve.ps1

Retrieve metadata from orgs using types, manifests, or package names.

Usage:

sf-retrieve -tp "ApexClass,CustomObject" | -mn manifest/package.xml | -pn MyPkg [-to ORG] [-od DIR]

sf-retrieve.ps1 -tp "ApexClass,CustomObject" -to myorg -od retrieved

Examples:

# Retrieve specific metadata types
sf-retrieve -tp "ApexClass,CustomObject" -to MyOrg

# Use manifest file
sf-retrieve -mn manifest/package.xml -to MyOrg -od ./metadata

sf-test-run / sf-test-run.ps1

Run Apex tests with coverage reporting and flexible targeting.

Usage:

sf-test-run -to ORG [-cn "Class1,Class2"] [-lv RunLocalTests] [-cv] [-wt 15]

sf-test-run.ps1 -to MyOrg -cn "ApexTest1,ApexTest2" -cv -wt 15

Examples:

# Run specific test classes with coverage
sf-test-run -to MyOrg -cn "MyTest,AnotherTest" -cv

# Run all local tests
sf-test-run -to MyOrg -lv RunLocalTests

sf-apex-run / sf-apex-run.ps1

Execute anonymous Apex code from files or inline.

Usage:

sf-apex-run -fl scripts/setup.apex | --code "System.debug('hi');" [-to ORG]

sf-apex-run.ps1 -fl "scripts/setup.apex" -to dev

Examples:

# Execute Apex from file
sf-apex-run -fl scripts/data-setup.apex -to MyOrg

# Execute inline code
sf-apex-run --code "System.debug('Hello World');" -to MyOrg

sf-data-export / sf-data-export.ps1

Export data via SOQL to CSV/JSON with optional Bulk API.

Usage:

sf-data-export -qy "SELECT Id, Name FROM Account" | -fl query.soql | -so Account [-to ORG] [-fm csv|json] [-bk] [-ot out.csv]

sf-data-export.ps1 -qy "SELECT Id FROM User" -fm json -ot users.json

sf-data-import / sf-data-import.ps1

Import CSV/JSON with insert/update/upsert operations.

Usage:

sf-data-import -fl data.csv -so Account [-to ORG] [-op insert|update|upsert] [-ei Field] [-bk]

sf-data-import.ps1 -fl data.json -so Contact -op upsert -ei Email

sf-logs-tail / sf-logs-tail.ps1

Real-time debug logs tail with filtering, levels, and Apex-only mode.

Usage:

sf-logs-tail [-to ORG] [--user-id USER] [--level DEBUG] [--duration 60] [--filter PATTERN] [--apex-only]

sf-logs-tail.ps1 -TargetOrg sandbox -Level DEBUG -Duration 60 -ApexOnly -Filter "MyClass"

sf-deploy

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

Usage:

sf-deploy -to <ORG_ALIAS_OR_USERNAME> (-sr "<src1>,<src2>[,...]" | -dr <DIRECTORY>) [-ts "<Test1>,<Test2>[,...]"]

Options:

• -to, --target-org - Org alias or username for --target-org
• -sr, --sources - Comma-separated list of --source-dir paths
• -dr, --directory - Single directory path to deploy (alternative to -sr)
• -ts, --tests - Comma-separated list of --tests (enables --test-level RunSpecifiedTests)
• -hp, --help - Show help

Examples:

# Deploy multiple flexipages (specific files)
sf-deploy -to DEMO-ORG \
  -sr "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 -to DEMO-ORG -dr "force-app/main/default/classes"

# Deploy with specific tests
sf-deploy -to DEMO-ORG \
  -sr "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" \
  -ts "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 -to <ORG_ALIAS_OR_USERNAME> (-sr "<src1>,<src2>[,...]" | -dr <DIRECTORY>) [-ts "<Test1>,<Test2>[,...]"]

Options:

• -to, --target-org - Org alias or username for --target-org
• -sr, --sources - Comma-separated list of --source-dir paths
• -dr, --directory - Single directory path to validate (alternative to -sr)
• -ts, --tests - Comma-separated list of --tests (enables --test-level RunSpecifiedTests)
• -hp, --help - Show help

Examples:

# Validate multiple flexipages (specific files)
sf-dry-run -to DEMO-ORG \
  -sr "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 -to DEMO-ORG -dr "force-app/main/default/classes"

# Validate with specific tests
sf-dry-run -to DEMO-ORG \
  -sr "force-app/main/default/flexipages/Demo_Page.flexipage-meta.xml,force-app/main/default/flexipages/Demo_Page_Backup_With_SalesNavigator.flexipage-meta.xml" \
  -ts "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 [-to <ORG_ALIAS_OR_USERNAME>] [-pt <RELATIVE_PATH>] [-ur]

Options:

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

Examples:

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

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

# Get just the URL for scripting
sf-web-open -to NUSHUB-DR2 -ur

# 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 [-vb] [-hp]

Options:

• -vb, --verbose - Verbose output (show detailed information)
• -hp, --help - Show help

Examples:

# Basic environment check
sf-check

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

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 (deploy, dry-run, web-open, org-create, org-info, retrieve, test-run, apex-run, data-export, data-import, logs-tail) include built-in environment verification:

✅ When SF CLI is installed (normal operation):

$ sf-deploy -to DEMO-ORG -dr "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 -to DEMO-ORG -dr "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

Quick Start Examples

Data Operations

# Export Account data to CSV with two-character options
sf-data-export -qy "SELECT Id, Name FROM Account LIMIT 100" -to MyOrg -fm csv

# Import CSV data using bulk API
sf-data-import -fl accounts.csv -so Account -to MyOrg -bk

# Upsert contacts with external ID
sf-data-import -fl contacts.csv -so Contact -op upsert -ei Email -to MyOrg

Development Workflow

# 1. Create scratch org
sf-org-create -al MyScratch -dd 7

# 2. Deploy and test
sf-deploy -to MyScratch -d "force-app/main/default/classes"
sf-test-run -to MyScratch -lv RunLocalTests -cv

# 3. Retrieve changes
sf-retrieve -tp "ApexClass" -to MyScratch

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 -to DEMO-ORG -sr "force-app/main/default/classes/MyClass.cls"

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

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

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

Working with Multiple Files

# Deploy multiple related components (specific files)
sf-deploy -to DEMO-ORG \
  -sr "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 -to DEMO-ORG -dr "force-app/main/default/aura"
sf-deploy -to DEMO-ORG -dr "force-app/main/default/lwc"

Testing Specific Classes

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

Features

• Cross-Platform: Available for both Unix/Linux/macOS (Bash) and Windows (PowerShell)
• Automatic Environment Verification: All wrappers auto-check SF CLI and run diagnostics when missing
• Consistent UX: Arguments and output styling are aligned across Bash and PowerShell
• Error Handling: Robust input validation and actionable errors
• Help Documentation: Each script includes comprehensive help (-h or -Help)
• Flexible Input: Supports absolute and repository-relative paths
• Command Echo: Shows the actual sf command being executed for transparency
• Focused Workflows: Deploy, validate, retrieve, test, run Apex, manage orgs, data import/export, and tail logs

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.

Testing

Comprehensive test suites are available to validate all wrapper scripts:

Quick Validation

# Bash version (Linux/macOS)
./quick-test.sh

# PowerShell version (cross-platform)
pwsh ./quick-test.ps1

Comprehensive Testing

# Bash version (Linux/macOS)
./test-wrapper-suite.sh

# PowerShell version (cross-platform)
pwsh ./test-wrapper-suite.ps1

Test Features

• 100% Coverage: All 12 wrapper scripts tested
• Option Validation: Two-character option recognition
• Error Handling: Invalid option and missing parameter testing
• Cross-Platform: Equivalent Bash and PowerShell test suites
• Detailed Reporting: Individual test outputs and comprehensive logs

Test Requirements:

• Target org: PWC-TEAM-DEV (must be authenticated)
• SF CLI properly installed and configured
• Execute permissions on test scripts

For detailed testing documentation, see TESTING.md.

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.