Files

app d6c55ce0b3 Add PowerShell version: sf-org-lic.ps1

- Complete PowerShell implementation of the license reporting tool
- Full PowerShell parameter handling with Get-Help integration
- Error handling consistent with PowerShell patterns
- Color-coded output using PowerShell Write-Host
- Updated README.md to document both Unix and PowerShell versions
- Added PowerShell examples and installation instructions
- Maintains feature parity with Bash version

Cross-platform support:
- sf-org-lic (Bash/Unix)
- sf-org-lic.ps1 (PowerShell/Windows)

2025-09-01 23:43:26 +08:00

29 KiB

Raw Permalink 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

Authentication:

sf-web-login / sf-web-login.ps1 - Web-based org authentication for sf org login web
sf-web-logout / sf-web-logout.ps1 - Org logout wrapper for sf org logout

Org and metadata:

sf-org-create / sf-org-create.ps1 - Smart scratch org creation
sf-org-lic / sf-org-lic.ps1 - Salesforce org license utilization report
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
-hp - HelP
-ve - VerBose

File & I/O Options

-fl - FiLe
-ot - OuTput
-fm - ForMat

Data & Query Options

-qy - QuerY
-so - S-Object
-bk - BulK

Operation & Control Options

-op - Operation
-wt - WaiT
-lv - LeVel
-lm - LiMits (show org limits)
-ls - LiSt (list orgs)

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 two-character option always has the same meaning 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)

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-web-login sf-web-logout sf-check \
  sf-org-create sf-org-lic 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-web-login /usr/local/bin/sf-web-login ln -s /path/to/sf-cli-wrapper/sf-web-logout /usr/local/bin/sf-web-logout 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-lic /usr/local/bin/sf-org-lic 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-web-login "C:\path\to\sf-cli-wrapper\sf-web-login.ps1" Set-Alias sf-web-logout "C:\path\to\sf-cli-wrapper\sf-web-logout.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

---

### <a id="sf-org-create"></a>[🏠](#salesforce-cli-wrapper-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] [-nn] [-hp]

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

Options:

-al - Alias for the new scratch org (required)
-dd - Duration in days (1-30, required)
-df - Path to scratch org definition file (optional)
-nn - No namespace (disable managed package namespace)
-hp - Show help

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

# Create without namespace
sf-org-create -al TestOrg -dd 5 -nn

🏠 sf-org-lic / sf-org-lic.ps1

Generate comprehensive Salesforce license utilization reports.

Usage:

sf-org-lic -to ORG [-hp]

sf-org-lic.ps1 -to "PROD-ORG"

Options:

-to - Target org alias or username (required)
-hp - Show help message

Examples:

# Generate license report for production org
sf-org-lic -to PROD-ORG

# Generate report for specific user
sf-org-lic -to admin@company.com

# Show help
sf-org-lic -hp

Features:

User Licenses - Core Salesforce user license utilization
Permission Set Licenses - Add-on feature license usage
Comprehensive totals - Overall usage summary with remaining capacity
Clean formatting - Professional tabular output
Error handling - Clear messages for invalid orgs with suggestions

Output includes:

License name, total allocated, used count, and remaining capacity
Color-coded totals summary
Professional formatting suitable for reports

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

Display org information, limits, and list authenticated orgs.

Usage:

sf-org-info [-to ORG] [-lm] [-ls] [-ve] [-hp]

sf-org-info.ps1 -to "myorg" -lm -ve

Options:

-to - Target org alias or username (optional, uses default if not specified)
-lm - Show detailed org limits information
-ls - List all authenticated orgs
-ve - Enable verbose output with additional details
-hp - Show help

Examples:

# Show default org info
sf-org-info

# Show specific org info with limits
sf-org-info -to DEMO-ORG -lm

# List all authenticated orgs
sf-org-info -ls

# Show detailed org information
sf-org-info -to MyOrg -ve

🏠 sf-retrieve / sf-retrieve.ps1

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

Usage:

sf-retrieve -to ORG (-tp TYPES | -mn MANIFEST | -pk PACKAGE) [-nm NAMES] [-dr DIR] [-hp]

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

Options:

-to - Org alias or username to retrieve from (required)
-tp - Comma-separated metadata types (ApexClass, CustomObject, Flow, etc.)
-mn - Path to manifest file (package.xml)
-pk - Package name to retrieve
-nm - Comma-separated component names (optional, works with -tp)
-dr - Target directory for retrieved metadata (default: force-app)
-hp - Show help

Examples:

# Retrieve all Apex classes
sf-retrieve -to PROD-ORG -tp "ApexClass"

# Retrieve specific classes
sf-retrieve -to PROD-ORG -tp "ApexClass" -nm "MyClass,AnotherClass"

# Use manifest file
sf-retrieve -to PROD-ORG -mn "manifest/package.xml"

# Retrieve to specific directory
sf-retrieve -to PROD-ORG -tp "ApexClass" -dr "retrieved-metadata"

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

Run Apex tests with coverage reporting and flexible targeting.

Usage:

sf-test-run -to ORG (-cn CLASSES | -sn SUITES | -al | -lv LEVEL) [-cv] [-wt WAIT] [-hp]

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

Options:

-to - Target org alias or username to run tests in (required)
-cn - Comma-separated test class names
-sn - Comma-separated test suite names
-al - Run all tests in the org
-lv - Test level (RunLocalTests, RunAllTestsInOrg, RunSpecifiedTests)
-cv - Generate code coverage report
-wt - Wait time in minutes (default: 10)
-hp - Show help

Examples:

# Run specific test classes with coverage
sf-test-run -to DEMO-ORG -cn "MyTestClass,AnotherTestClass" -cv

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

# Run test suites
sf-test-run -to DEMO-ORG -sn "UnitTests,IntegrationTests"

# Run all tests with extended wait time
sf-test-run -to DEMO-ORG -al -wt 30

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

Execute anonymous Apex code from files or inline.

Usage:

sf-apex-run (-fl FILE | -cd CODE) [-to ORG] [-ve] [-hp]

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

Options:

-fl - Path to Apex file to execute
-cd - Inline Apex code to execute (alternative to -fl)
-to - Target org username or alias (optional, uses default if not specified)
-ve - Enable verbose output showing execution details
-hp - Show help

Examples:

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

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

# Execute with verbose output
sf-apex-run -fl test.apex -ve

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

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

Usage:

sf-data-export (-qy QUERY | -fl FILE | -so OBJECT) [-to ORG] [-fm FORMAT] [-bk] [-ot OUTPUT] [-wt WAIT] [-ve] [-hp]

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

Options:

-qy - SOQL query to export data
-fl - File containing SOQL query
-so - Standard object query (exports all records for common objects)
-to - Target org username or alias
-ot - Output file path (default: export.csv)
-fm - Output format: csv, json (default: csv)
-bk - Use bulk API for large datasets
-wt - Wait time in minutes (default: 10)
-ve - Enable verbose output
-hp - Show help

Examples:

# Export with inline query
sf-data-export -qy "SELECT Id, Name FROM Account LIMIT 100"

# Export standard object to JSON
sf-data-export -so Account -fm json -ot accounts.json

# Export from query file using Bulk API
sf-data-export -fl queries/contacts.soql -bk -wt 15

# Export to specific org
sf-data-export -qy "SELECT Id FROM User" -to production

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

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

Usage:

sf-data-import -fl FILE -so OBJECT [-to ORG] [-op OPERATION] [-ei FIELD] [-bk] [-wt WAIT] [-bs SIZE] [-ie] [-ve] [-hp]

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

Options:

-fl - CSV or JSON file to import (required)
-so - Target sObject type (required)
-to - Target org username or alias
-op - Operation: insert, update, upsert (default: insert)
-ei - External ID field for upsert/update operations
-bk - Use bulk API for large datasets
-wt - Wait time in minutes (default: 10)
-bs - Batch size for bulk operations (default: 10000)
-ie - Continue on errors (don't fail entire job)
-ve - Enable verbose output
-hp - Show help

Examples:

# Import CSV data
sf-data-import -fl accounts.csv -so Account

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

# Bulk import with custom batch size
sf-data-import -fl leads.csv -so Lead -bk -bs 5000

# Update records
sf-data-import -fl updates.csv -so Account -op update -ei AccountNumber

🏠 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 [-ui USER] [-lv LEVEL] [-dr DURATION] [-ft PATTERN] [-ax] [-nc] [-ve] [-hp]

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

Options:

-to - Target org username or alias (required)
-ui - Specific user ID to monitor (default: current user)
-lv - Log level: ERROR, WARN, INFO, DEBUG, FINE, FINER, FINEST
-dr - How long to tail logs in minutes (default: 30)
-ft - Filter log entries containing pattern
-ax - Show only Apex-related log entries
-nc - Disable colored output
-ve - Enable verbose output with timestamps
-hp - Show help

Examples:

# Tail logs with debug level for 1 hour
sf-logs-tail -to MYORG -lv DEBUG -dr 60

# Filter Apex logs for specific class
sf-logs-tail -to MYORG -ft "MyClass" -ax

# Specific org and user
sf-logs-tail -to sandbox -ui USER123

🏠 sf-deploy

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

Usage:

sf-deploy -to ORG (-sr SOURCES | -dr DIRECTORY) [-ts TESTS] [-hp]

Options:

-to - Target org alias or username (required)
-sr - Comma-separated list of source file paths
-dr - Single directory path to deploy (alternative to -sr)
-ts - Comma-separated list of test class names (enables RunSpecifiedTests)
-hp - 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 (-sr SOURCES | -dr DIRECTORY) [-ts TESTS] [-hp]

Options:

-to - Target org alias or username (required)
-sr - Comma-separated list of source file paths to validate
-dr - Single directory path to validate (alternative to -sr)
-ts - Comma-separated list of test class names (enables RunSpecifiedTests)
-hp - 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] [-pt PATH] [-ur] [-hp]

Options:

-to - Target org alias or username (recommended)
-pt - Relative path to open inside the org (e.g., "/lightning/setup/SetupOneHome/home")
-ur - URL-only: print the URL instead of opening a browser
-hp - 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

Web-based org authentication wrapper for sf org login web.

Usage:

sf-web-login [-al ALIAS] [-in INSTANCE_URL] [-ud] [-ve] [-hp]

sf-web-login.ps1 -al "NUSHUB-PROD" -ve

Options:

-al - Alias for the authenticated org (passes --alias)
-in - Instance URL to authenticate against (passes --instance-url)
-ud - Update default org after login (passes --set-default)
-ve - Enable verbose output showing login details
-hp - Show help

Examples:

# Login to production with alias
sf-web-login -al NUSHUB-PROD

# Login to specific instance with alias and set as default
sf-web-login -al MySandbox -in https://test.my-domain.my.salesforce.com -ud

# Login with verbose output
sf-web-login -al TestOrg -ve

🏠 sf-web-logout / sf-web-logout.ps1

Org logout wrapper for sf org logout.

Usage:

sf-web-logout [-to ORG_ALIAS_OR_USERNAME] [-al] [-ve] [-hp]

sf-web-logout.ps1 -to "DEMO" -ve

Options:

-to - Org alias or username to logout from (passes --target-org)
-al - Logout from all authenticated orgs (passes --all)
-ve - Enable verbose output showing logout details
-hp - Show help

Examples:

# Logout from specific org
sf-web-logout -to DEMO

# Logout from all orgs
sf-web-logout -al

# Logout with verbose output
sf-web-logout -to NUSHUB-PROD -ve

🏠 sf-check

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

Usage:

sf-check [-ve] [-hp]

Options:

-ve - Enable verbose output with detailed system information
-hp - Show help

Examples:

# Basic environment check
sf-check

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

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 -dr "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 (-hp 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
macOS Compatibility: Full compatibility with macOS using portable timeout implementation

macOS Compatibility

The wrapper scripts include a utils.sh helper that provides cross-platform timeout functionality. This ensures that scripts requiring timed execution (like sf-logs-tail) work correctly on macOS without requiring GNU coreutils.

The timeout helper automatically detects and uses:

timeout command (Linux/GNU systems)
gtimeout command (macOS with GNU coreutils)
Built-in fallback implementation (pure Bash for macOS)

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.

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:

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

Credits

Author: Reynold
Project: Salesforce CLI Wrapper Scripts
Description: A comprehensive collection of cross-platform wrapper scripts that simplify and streamline common Salesforce CLI operations with an innovative two-character option scheme.

License

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

29 KiB Raw Permalink Blame History

Salesforce CLI Wrapper Scripts

Overview

Two-Character Option Scheme

Core Options (consistent across scripts)

File & I/O Options

Data & Query Options

Operation & Control Options

Benefits

Example Usage

Installation

Unix/Linux/macOS (Bash)

Option 2: Create symlinks

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

🏠 sf-org-lic / sf-org-lic.ps1

🏠 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-web-login / sf-web-login.ps1

🏠 sf-web-logout / sf-web-logout.ps1

🏠 sf-check

Automatic Environment Verification

✅ When SF CLI is installed (normal operation):

❌ When SF CLI is missing:

How It Works:

Quick Start Examples

Data Operations

Development Workflow

Prerequisites

Common Workflows

Deployment with Validation

Working with Multiple Files

Testing Specific Classes

Features

macOS Compatibility

Tips

Troubleshooting

Common Issues

Debug Mode

Testing

Quick Validation

Comprehensive Testing

Test Features

Contributing

Credits

License

29 KiB

Raw Permalink Blame History