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

Authentication:
- **[`sf-web-login` / `sf-web-login.ps1`](#sf-web-login--sf-web-loginps1)** - Web-based org authentication for `sf org login web`
- **[`sf-web-logout` / `sf-web-logout.ps1`](#sf-web-logout--sf-web-logoutps1)** - Org logout wrapper for `sf org logout`

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` - **T**arget **O**rg
- `-hp` - **H**el**P**
- `-ve` - **V**er**B**ose

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

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

### Operation & Control Options
- `-op` - **Op**eration
- `-wt` - **W**ai**T**
- `-lv` - **L**e**V**el
- `-lm` - **L**i**M**its (show org limits)
- `-ls` - **L**i**S**t (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
```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-web-login sf-web-logout 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-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-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-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]
```
```powershell
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:**
```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

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

---

### <a id="sf-org-info--sf-org-infops1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-org-info / sf-org-info.ps1

Display org information, limits, and list authenticated orgs.

**Usage:**
```bash
sf-org-info [-to ORG] [-lm] [-ls] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-retrieve--sf-retrieveps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-retrieve / sf-retrieve.ps1

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

**Usage:**
```bash
sf-retrieve -to ORG (-tp TYPES | -mn MANIFEST | -pk PACKAGE) [-nm NAMES] [-dr DIR] [-hp]
```
```powershell
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:**
```bash
# 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"
```

---

### <a id="sf-test-run--sf-test-runps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-test-run / sf-test-run.ps1

Run Apex tests with coverage reporting and flexible targeting.

**Usage:**
```bash
sf-test-run -to ORG (-cn CLASSES | -sn SUITES | -al | -lv LEVEL) [-cv] [-wt WAIT] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-apex-run--sf-apex-runps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-apex-run / sf-apex-run.ps1

Execute anonymous Apex code from files or inline.

**Usage:**
```bash
sf-apex-run (-fl FILE | -cd CODE) [-to ORG] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-data-export--sf-data-exportps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-data-export / sf-data-export.ps1

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

**Usage:**
```bash
sf-data-export (-qy QUERY | -fl FILE | -so OBJECT) [-to ORG] [-fm FORMAT] [-bk] [-ot OUTPUT] [-wt WAIT] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-data-import--sf-data-importps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-data-import / sf-data-import.ps1

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

**Usage:**
```bash
sf-data-import -fl FILE -so OBJECT [-to ORG] [-op OPERATION] [-ei FIELD] [-bk] [-wt WAIT] [-bs SIZE] [-ie] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-logs-tail--sf-logs-tailps1"></a>[🏠](#salesforce-cli-wrapper-scripts) 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 [-ui USER] [-lv LEVEL] [-dr DURATION] [-ft PATTERN] [-ax] [-nc] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-deploy"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-deploy

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

**Usage:**
```bash
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:**
```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"
```

---

### <a id="sf-dry-run"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-dry-run

Wrapper for `sf project deploy start --dry-run` that validates deployments without actually deploying.

**Usage:**
```bash
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:**
```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"
```

---

### <a id="sf-web-open"></a>[🏠](#salesforce-cli-wrapper-scripts) 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] [-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:**
```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
```

---

### <a id="sf-web-login--sf-web-loginps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-web-login / sf-web-login.ps1

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

**Usage:**
```bash
sf-web-login [-al ALIAS] [-in INSTANCE_URL] [-ud] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-web-logout--sf-web-logoutps1"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-web-logout / sf-web-logout.ps1

Org logout wrapper for `sf org logout`.

**Usage:**
```bash
sf-web-logout [-to ORG_ALIAS_OR_USERNAME] [-al] [-ve] [-hp]
```
```powershell
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:**
```bash
# 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
```

---

### <a id="sf-check"></a>[🏠](#salesforce-cli-wrapper-scripts) sf-check

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

**Usage:**
```bash
sf-check [-ve] [-hp]
```

**Options:**
- `-ve` - Enable verbose output with detailed system information
- `-hp` - 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 -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
```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 (-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:
1. `timeout` command (Linux/GNU systems)
2. `gtimeout` command (macOS with GNU coreutils)
3. Built-in fallback implementation (pure Bash for macOS)

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

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