sf-cli-wrapper/README.md

# 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`](#sf-deploy)** - Streamlined wrapper for `sf project deploy start`
- **[`sf-dry-run`](#sf-dry-run)** - Validation wrapper for `sf project deploy start --dry-run`
- **[`sf-web-open`](#sf-web-open)** - Quick org browser opener for `sf org open`
- **[`sf-check`](#sf-check)** - Environment verification tool to check SF CLI installation and configuration

Org and metadata:
- **[`sf-org-create` / `sf-org-create.ps1`](#sf-org-create)** - Smart scratch org creation
- **[`sf-org-info` / `sf-org-info.ps1`](#sf-org-info--sf-org-infops1)** - Quick org info, limits, and context
- **[`sf-retrieve` / `sf-retrieve.ps1`](#sf-retrieve--sf-retrieveps1)** - Streamlined metadata retrieval (types, manifest, packages)

Apex and tests:
- **[`sf-test-run` / `sf-test-run.ps1`](#sf-test-run--sf-test-runps1)** - Focused Apex test execution with coverage
- **[`sf-apex-run` / `sf-apex-run.ps1`](#sf-apex-run--sf-apex-runps1)** - Anonymous Apex execution (file or inline)

Data and logs:
- **[`sf-data-export` / `sf-data-export.ps1`](#sf-data-export--sf-data-exportps1)** - Export data via SOQL to CSV/JSON, optional Bulk API
- **[`sf-data-import` / `sf-data-import.ps1`](#sf-data-import--sf-data-importps1)** - Import CSV/JSON with insert/update/upsert
- **[`sf-logs-tail` / `sf-logs-tail.ps1`](#sf-logs-tail--sf-logs-tailps1)** - 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` - **T**arget **O**rg
- `-hp, --help` - **H**el**P**
- `-ve, --verbose` - **V**er**B**ose

### File & I/O Options
- `-fl, --file` - **F**i**L**e
- `-ot, --output` - **O**u**T**put
- `-fm, --format` - **F**or**M**at

### Data & Query Options
- `-qy, --query` - **Q**uer**Y**
- `-so, --sobject` - **S**-**O**bject
- `-bk, --bulk` - **B**ul**K**

### Operation & Control Options
- `-op, --operation` - **Op**eration
- `-wt, --wait` - **W**ai**T**
- `-lv, --level` - **L**e**V**el

### 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
```bash
# 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:
   ```bash
   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:
   ```bash
   # 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:
   ```powershell
   # 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]
```
```powershell
sf-org-create.ps1 -al "MySO" -dd 7 -df "config/project-scratch-def.json"
```

**Examples:**
```bash
# 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:**
```bash
sf-org-info -to ORG [--limits] [--list] [-ve]
```
```powershell
sf-org-info.ps1 -to "myorg" -Limits -ve
```

**Examples:**
```bash
# Show org info for specific org
sf-org-info -to MyOrg

# Show limits and verbose info
sf-org-info -to MyOrg --limits -ve
```

### sf-retrieve / sf-retrieve.ps1

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

**Usage:**
```bash
sf-retrieve -tp "ApexClass,CustomObject" | -mn manifest/package.xml | -pn MyPkg [-to ORG] [-od DIR]
```
```powershell
sf-retrieve.ps1 -tp "ApexClass,CustomObject" -to myorg -od retrieved
```

**Examples:**
```bash
# 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:**
```bash
sf-test-run -to ORG [-cn "Class1,Class2"] [-lv RunLocalTests] [-cv] [-wt 15]
```
```powershell
sf-test-run.ps1 -to MyOrg -cn "ApexTest1,ApexTest2" -cv -wt 15
```

**Examples:**
```bash
# 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:**
```bash
sf-apex-run -fl scripts/setup.apex | --code "System.debug('hi');" [-to ORG]
```
```powershell
sf-apex-run.ps1 -fl "scripts/setup.apex" -to dev
```

**Examples:**
```bash
# 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:
```bash
sf-data-export -qy "SELECT Id, Name FROM Account" | -fl query.soql | -so Account [-to ORG] [-fm csv|json] [-bk] [-ot out.csv]
```
```powershell
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:
```bash
sf-data-import -fl data.csv -so Account [-to ORG] [-op insert|update|upsert] [-ei Field] [-bk]
```
```powershell
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:
```bash
sf-logs-tail [-to ORG] [--user-id USER] [--level DEBUG] [--duration 60] [--filter PATTERN] [--apex-only]
```
```powershell
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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
sf-check [-ve] [-hp]
```

**Options:**
- `-ve, --verbose` - Verbose output (show detailed information)
- `-hp, --help` - Show help

**Examples:**
```bash
# 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):**
```bash
$ 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:**
```bash
$ 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
# Bash version (Linux/macOS)
./quick-test.sh

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

### Comprehensive Testing
```bash
# 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.