Files

reynold d919e5cfb8 updated README

2025-08-28 16:42:15 +08:00

19 KiB

Raw Blame History

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

Installation

Unix/Linux/macOS (Bash)

Clone or download this repository to your preferred tools directory

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

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

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

Smart scratch org creation with templates and intelligent defaults.

Usage (bash):
```bash
sf-org-create [-a ALIAS] [-d DAYS] [-t TEMPLATE] [--no-namespace]

Usage (PowerShell):

sf-org-create.ps1 -Alias "MySO" -DurationDays 7 -Template "config/project-scratch-def.json"

Examples:

Create with alias and duration: sf-org-create -a SO -d 7
Use a specific template: sf-org-create -t config/project-scratch-def.json

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

Quick org information display with optional limits and listing authenticated orgs.

Usage:

sf-org-info [-o ORG] [--limits] [--list]

sf-org-info.ps1 -TargetOrg "myorg" -Limits -Verbose

sf-retrieve / sf-retrieve.ps1

Streamlined metadata retrieval supporting metadata types, manifest, and package name.

Usage:

sf-retrieve --types "ApexClass,CustomObject" | --manifest manifest/package.xml | --package-name MyPkg [--target-org ORG] [--output-dir DIR]

sf-retrieve.ps1 -MetadataTypes "ApexClass,CustomObject" -TargetOrg myorg -OutputDir retrieved

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

Focused Apex test execution with better formatting, coverage, and wait control.

Usage:

sf-test-run --classes "A,B" | --methods "A.m1,B.m2" | --level RunLocalTests [--coverage] [--wait 15] [--target-org ORG]

sf-test-run.ps1 -TestClasses "ApexTest1,ApexTest2" -Coverage -Wait 15

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

Execute anonymous Apex from file or inline code.

Usage:

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

sf-apex-run.ps1 -File "scripts/setup.apex" -TargetOrg dev

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

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

Usage:

sf-data-export --query "SELECT Id, Name FROM Account" | --file query.soql | --sobject Account [--format csv|json] [--bulk] [--output out.csv]

sf-data-export.ps1 -Query "SELECT Id FROM User" -Format json -Output users.json

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

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

Usage:

sf-data-import --file data.csv --sobject Account --operation insert|update|upsert [--external-id Field] [--bulk]

sf-data-import.ps1 -File data.json -SObject Contact -Operation upsert -ExternalId Email

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

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

Usage:

sf-logs-tail [--target-org 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 -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 (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 -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

Additional helpers (PowerShell):

# Org creation
sf-org-create.ps1 -Alias "SO" -DurationDays 7

# Retrieve metadata
sf-retrieve.ps1 -Manifest "manifest/package.xml" -TargetOrg "dev"

# Run tests with coverage
sf-test-run.ps1 -TestLevel RunLocalTests -Coverage -Wait 15

# Execute anonymous Apex
sf-apex-run.ps1 -Code "System.debug('Hello');" -TargetOrg dev

# Data export and import
sf-data-export.ps1 -SObject Account -Format csv -Output accounts.csv
sf-data-import.ps1 -File accounts.csv -SObject Account -Operation insert

# Tail logs
sf-logs-tail.ps1 -Level DEBUG -Duration 30 -ApexOnly

# 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: 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

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

Troubleshooting

Common Issues

"Command not found":
- Unix/Linux/macOS: Ensure the scripts are executable and in your PATH
- Windows: Check PowerShell execution policy and script location
"No default org found": Specify the org parameter or set a default org with sf config set target-org
"Source path not found": Verify file paths are correct relative to your project root
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:

Help function with usage examples
Argument parsing with getopts
Command array building
Command execution with exec

PowerShell Scripts:

Parameter definitions with validation
Help function with usage examples
Parameter validation and processing
Command array building and execution

License

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

19 KiB Raw Blame History

Salesforce CLI Wrapper Scripts

Overview

Installation

Unix/Linux/macOS (Bash)

Option 2: Create symlinks

Option 2: Create PowerShell aliases (add to your $PROFILE)

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

sf-retrieve / sf-retrieve.ps1

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

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

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

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

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

sf-deploy

sf-dry-run

sf-web-open

sf-check

Automatic Environment Verification

✅ When SF CLI is installed (normal operation):

❌ When SF CLI is missing:

How It Works:

Windows PowerShell Examples

sf-deploy.ps1

sf-dry-run.ps1

sf-web-open.ps1

Windows Common Workflows

Prerequisites

Common Workflows

Deployment with Validation

Working with Multiple Files

Testing Specific Classes

Features

Tips

Troubleshooting

Common Issues

Debug Mode

Contributing

License

19 KiB

Raw Blame History