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: