Salesforce/sf-cli-wrapper
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d919e5cfb8df9c41ee1f1894cd5f276392ff78e1
sf-cli-wrapper/README.md
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:

Apex and tests:

Data and logs:

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
  1. 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

  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.

Reference in New Issue View Git Blame Copy Permalink