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

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

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):
```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:
```bash
sf-org-info [-o ORG] [--limits] [--list]
```
```powershell
sf-org-info.ps1 -TargetOrg "myorg" -Limits -Verbose
```

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

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

Usage:
```bash
sf-retrieve --types "ApexClass,CustomObject" | --manifest manifest/package.xml | --package-name MyPkg [--target-org ORG] [--output-dir DIR]
```
```powershell
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:
```bash
sf-test-run --classes "A,B" | --methods "A.m1,B.m2" | --level RunLocalTests [--coverage] [--wait 15] [--target-org ORG]
```
```powershell
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:
```bash
sf-apex-run --file scripts/setup.apex | --code "System.debug('hi');" [--target-org ORG]
```
```powershell
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:
```bash
sf-data-export --query "SELECT Id, Name FROM Account" | --file query.soql | --sobject Account [--format csv|json] [--bulk] [--output out.csv]
```
```powershell
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:
```bash
sf-data-import --file data.csv --sobject Account --operation insert|update|upsert [--external-id Field] [--bulk]
```
```powershell
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:
```bash
sf-logs-tail [--target-org 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 -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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
sf-check [-v] [-h]
```

**Options:**
- `-v` - Verbose output (show detailed information)
- `-h` - Show help

**Examples:**
```bash
# 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):**
```bash
$ 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:**
```bash
$ 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

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

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

```powershell
# 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):
```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
```

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