From 833eb9448a683e2906281ee1c166731bbe01850f Mon Sep 17 00:00:00 2001 From: reynold Date: Thu, 28 Aug 2025 22:12:23 +0800 Subject: [PATCH] Enhanced README.md with improved formatting and detailed option descriptions - Added horizontal separators (---) between each wrapper command for better visual separation - Added comprehensive **Options:** sections for each command with detailed descriptions - Updated all usage examples to be more concise and consistent - Provided brief descriptions for every two-character option across all commands - Improved readability by organizing content in a more structured format - Made the documentation consistent with the help text format from the actual scripts - Enhanced user experience by making it easier to find and understand each command's options This makes the README much more readable and provides users with clear, detailed information about each option similar to the built-in help text. --- README.md | 242 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 205 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 7d23382..23f992d 100644 --- a/README.md +++ b/README.md @@ -131,18 +131,27 @@ 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] +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 @@ -150,145 +159,296 @@ 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-info / sf-org-info.ps1 Display org information, limits, and list authenticated orgs. **Usage:** ```bash -sf-org-info -to ORG [-lm] [-ls] [-ve] +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 org info for specific org -sf-org-info -to MyOrg +# Show default org info +sf-org-info -# Show limits and verbose info -sf-org-info -to MyOrg -lm -ve +# 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:** ```bash -sf-retrieve -tp "ApexClass,CustomObject" | -mn manifest/package.xml | -pn MyPkg [-to ORG] [-od DIR] +sf-retrieve -to ORG (-tp TYPES | -mn MANIFEST | -pk PACKAGE) [-nm NAMES] [-dr DIR] [-hp] ``` ```powershell -sf-retrieve.ps1 -tp "ApexClass,CustomObject" -to myorg -od retrieved +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 specific metadata types -sf-retrieve -tp "ApexClass,CustomObject" -to MyOrg +# 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 -mn manifest/package.xml -to MyOrg -od ./metadata +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:** ```bash -sf-test-run -to ORG [-cn "Class1,Class2"] [-lv RunLocalTests] [-cv] [-wt 15] +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 MyOrg -cn "MyTest,AnotherTest" -cv +sf-test-run -to DEMO-ORG -cn "MyTestClass,AnotherTestClass" -cv # Run all local tests -sf-test-run -to MyOrg -lv RunLocalTests +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:** ```bash -sf-apex-run -fl scripts/setup.apex | --code "System.debug('hi');" [-to ORG] +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 --code "System.debug('Hello World');" -to MyOrg +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: +**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] +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 +``` + +--- + ### sf-data-import / sf-data-import.ps1 Import CSV/JSON with insert/update/upsert operations. -Usage: +**Usage:** ```bash -sf-data-import -fl data.csv -so Account [-to ORG] [-op insert|update|upsert] [-ei Field] [-bk] +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 +``` + +--- + ### sf-logs-tail / sf-logs-tail.ps1 Real-time debug logs tail with filtering, levels, and Apex-only mode. -Usage: +**Usage:** ```bash -sf-logs-tail [-to ORG] [-ui USER] [-lv DEBUG] [-dr 60] [-ft PATTERN] [-ax] +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 +- `-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 for default org +sf-logs-tail + +# Debug level for 1 hour +sf-logs-tail -lv DEBUG -dr 60 + +# Filter Apex logs for specific class +sf-logs-tail -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:** ```bash -sf-deploy -to (-sr ",[,...]" | -dr ) [-ts ",[,...]"] +sf-deploy -to ORG (-sr SOURCES | -dr DIRECTORY) [-ts TESTS] [-hp] ``` **Options:** -- `-to` - Org alias or username for --target-org -- `-sr` - Comma-separated list of --source-dir paths +- `-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 --tests (enables --test-level RunSpecifiedTests) +- `-ts` - Comma-separated list of test class names (enables RunSpecifiedTests) - `-hp` - Show help **Examples:** @@ -306,20 +466,22 @@ sf-deploy -to DEMO-ORG \ -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 (-sr ",[,...]" | -dr ) [-ts ",[,...]"] +sf-dry-run -to ORG (-sr SOURCES | -dr DIRECTORY) [-ts TESTS] [-hp] ``` **Options:** -- `-to` - Org alias or username for --target-org -- `-sr` - Comma-separated list of --source-dir paths +- `-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 --tests (enables --test-level RunSpecifiedTests) +- `-ts` - Comma-separated list of test class names (enables RunSpecifiedTests) - `-hp` - Show help **Examples:** @@ -337,23 +499,28 @@ sf-dry-run -to DEMO-ORG \ -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 ] [-pt ] [-ur] +sf-web-open [-to ORG] [-pt PATH] [-ur] [-hp] ``` **Options:** -- `-to` - Org alias or username to pass as --target-org +- `-to` - Target org alias or username (optional, uses default if not specified) - `-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 (passes --url-only) +- `-ur` - URL-only: print the URL instead of opening a browser - `-hp` - Show help **Examples:** ```bash +# Open the current default org +sf-web-open + # Open a specific org (default home) sf-web-open -to DEMO-ORG @@ -362,11 +529,10 @@ 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. @@ -377,7 +543,7 @@ sf-check [-ve] [-hp] ``` **Options:** -- `-ve` - Verbose output (show detailed information) +- `-ve` - Enable verbose output with detailed system information - `-hp` - Show help **Examples:** @@ -396,6 +562,8 @@ sf-check -ve - 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: