Salesforce/sf-cli-wrapper
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhanced README.md with improved formatting and detailed option descriptions

Browse Source 
- 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.
This commit is contained in:
reynold
2025-08-28 22:12:23 +08:00
parent 1ae8df8561
commit 833eb9448a
1 changed files with 205 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
README.md
View File

@@ -131,18 +131,27 @@ Set-Alias sf-logs-tail "C:\\path\\to\\sf-cli-wrapper\\sf-logs-tail.ps1"
## Scripts ## Scripts
---
### sf-org-create / sf-org-create.ps1 ### sf-org-create / sf-org-create.ps1
Smart scratch org creation with templates and intelligent defaults. Smart scratch org creation with templates and intelligent defaults.
**Usage:** **Usage:**
```bash ```bash
sf-org-create -al ALIAS -dd DAYS -df TEMPLATE [--no-namespace] sf-org-create -al ALIAS -dd DAYS [-df TEMPLATE] [-nn] [-hp]
``` ```
```powershell ```powershell
sf-org-create.ps1 -al "MySO" -dd 7 -df "config/project-scratch-def.json" 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:** **Examples:**
```bash ```bash
# Create scratch org with alias and 7-day duration # Create scratch org with alias and 7-day duration
@@ -150,145 +159,296 @@ sf-org-create -al MyScratch -dd 7
# Use specific definition file # Use specific definition file
sf-org-create -al DevOrg -df config/project-scratch-def.json 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 ### sf-org-info / sf-org-info.ps1
Display org information, limits, and list authenticated orgs. Display org information, limits, and list authenticated orgs.
**Usage:** **Usage:**
```bash ```bash
sf-org-info -to ORG [-lm] [-ls] [-ve] sf-org-info [-to ORG] [-lm] [-ls] [-ve] [-hp]
``` ```
```powershell ```powershell
sf-org-info.ps1 -to "myorg" -lm -ve 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:** **Examples:**
```bash ```bash
# Show org info for specific org # Show default org info
sf-org-info -to MyOrg sf-org-info
# Show limits and verbose info # Show specific org info with limits
sf-org-info -to MyOrg -lm -ve sf-org-info -to DEMO-ORG -lm
# List all authenticated orgs # List all authenticated orgs
sf-org-info -ls sf-org-info -ls
# Show detailed org information
sf-org-info -to MyOrg -ve
``` ```
---
### sf-retrieve / sf-retrieve.ps1 ### sf-retrieve / sf-retrieve.ps1
Retrieve metadata from orgs using types, manifests, or package names. Retrieve metadata from orgs using types, manifests, or package names.
**Usage:** **Usage:**
```bash ```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 ```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:** **Examples:**
```bash ```bash
# Retrieve specific metadata types # Retrieve all Apex classes
sf-retrieve -tp "ApexClass,CustomObject" -to MyOrg sf-retrieve -to PROD-ORG -tp "ApexClass"
# Retrieve specific classes
sf-retrieve -to PROD-ORG -tp "ApexClass" -nm "MyClass,AnotherClass"
# Use manifest file # 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 ### sf-test-run / sf-test-run.ps1
Run Apex tests with coverage reporting and flexible targeting. Run Apex tests with coverage reporting and flexible targeting.
**Usage:** **Usage:**
```bash ```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 ```powershell
sf-test-run.ps1 -to MyOrg -cn "ApexTest1,ApexTest2" -cv -wt 15 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:** **Examples:**
```bash ```bash
# Run specific test classes with coverage # 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 # 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 ### sf-apex-run / sf-apex-run.ps1
Execute anonymous Apex code from files or inline. Execute anonymous Apex code from files or inline.
**Usage:** **Usage:**
```bash ```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 ```powershell
sf-apex-run.ps1 -fl "scripts/setup.apex" -to dev 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:** **Examples:**
```bash ```bash
# Execute Apex from file # Execute Apex from file
sf-apex-run -fl scripts/data-setup.apex -to MyOrg sf-apex-run -fl scripts/data-setup.apex -to MyOrg
# Execute inline code # 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 ### sf-data-export / sf-data-export.ps1
Export data via SOQL to CSV/JSON with optional Bulk API. Export data via SOQL to CSV/JSON with optional Bulk API.
Usage: **Usage:**
```bash ```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 ```powershell
sf-data-export.ps1 -qy "SELECT Id FROM User" -fm json -ot users.json 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 ### sf-data-import / sf-data-import.ps1
Import CSV/JSON with insert/update/upsert operations. Import CSV/JSON with insert/update/upsert operations.
Usage: **Usage:**
```bash ```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 ```powershell
sf-data-import.ps1 -fl data.json -so Contact -op upsert -ei Email 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 ### sf-logs-tail / sf-logs-tail.ps1
Real-time debug logs tail with filtering, levels, and Apex-only mode. Real-time debug logs tail with filtering, levels, and Apex-only mode.
Usage: **Usage:**
```bash ```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 ```powershell
sf-logs-tail.ps1 -TargetOrg sandbox -Level DEBUG -Duration 60 -ApexOnly -Filter "MyClass" 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 ### sf-deploy
Wrapper for `sf project deploy start` that simplifies deploying multiple source files with optional test execution. Wrapper for `sf project deploy start` that simplifies deploying multiple source files with optional test execution.
**Usage:** **Usage:**
```bash ```bash
sf-deploy -to <ORG_ALIAS_OR_USERNAME> (-sr "<src1>,<src2>[,...]" | -dr <DIRECTORY>) [-ts "<Test1>,<Test2>[,...]"] sf-deploy -to ORG (-sr SOURCES | -dr DIRECTORY) [-ts TESTS] [-hp]
``` ```
**Options:** **Options:**
- `-to` - Org alias or username for --target-org - `-to` - Target org alias or username (required)
- `-sr` - Comma-separated list of --source-dir paths - `-sr` - Comma-separated list of source file paths
- `-dr` - Single directory path to deploy (alternative to -sr) - `-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 - `-hp` - Show help
**Examples:** **Examples:**
@@ -306,20 +466,22 @@ sf-deploy -to DEMO-ORG \
-ts "SelectorOpportunity_Test,SelectorOpportunity2_Test" -ts "SelectorOpportunity_Test,SelectorOpportunity2_Test"
``` ```
---
### sf-dry-run ### sf-dry-run
Wrapper for `sf project deploy start --dry-run` that validates deployments without actually deploying. Wrapper for `sf project deploy start --dry-run` that validates deployments without actually deploying.
**Usage:** **Usage:**
```bash ```bash
sf-dry-run -to <ORG_ALIAS_OR_USERNAME> (-sr "<src1>,<src2>[,...]" | -dr <DIRECTORY>) [-ts "<Test1>,<Test2>[,...]"] sf-dry-run -to ORG (-sr SOURCES | -dr DIRECTORY) [-ts TESTS] [-hp]
``` ```
**Options:** **Options:**
- `-to` - Org alias or username for --target-org - `-to` - Target org alias or username (required)
- `-sr` - Comma-separated list of --source-dir paths - `-sr` - Comma-separated list of source file paths to validate
- `-dr` - Single directory path to validate (alternative to -sr) - `-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 - `-hp` - Show help
**Examples:** **Examples:**
@@ -337,23 +499,28 @@ sf-dry-run -to DEMO-ORG \
-ts "SelectorOpportunity_Test,SelectorOpportunity2_Test" -ts "SelectorOpportunity_Test,SelectorOpportunity2_Test"
``` ```
---
### sf-web-open ### sf-web-open
Wrapper for `sf org open` that provides quick access to Salesforce orgs with optional path navigation. Wrapper for `sf org open` that provides quick access to Salesforce orgs with optional path navigation.
**Usage:** **Usage:**
```bash ```bash
sf-web-open [-to <ORG_ALIAS_OR_USERNAME>] [-pt <RELATIVE_PATH>] [-ur] sf-web-open [-to ORG] [-pt PATH] [-ur] [-hp]
``` ```
**Options:** **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") - `-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 - `-hp` - Show help
**Examples:** **Examples:**
```bash ```bash
# Open the current default org
sf-web-open
# Open a specific org (default home) # Open a specific org (default home)
sf-web-open -to DEMO-ORG 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 # Get just the URL for scripting
sf-web-open -to NUSHUB-DR2 -ur sf-web-open -to NUSHUB-DR2 -ur
# Open the current default org
sf-web-open
``` ```
---
### sf-check ### sf-check
Environment verification tool that checks if the Salesforce CLI is properly installed and configured. Environment verification tool that checks if the Salesforce CLI is properly installed and configured.
@@ -377,7 +543,7 @@ sf-check [-ve] [-hp]
``` ```
**Options:** **Options:**
- `-ve` - Verbose output (show detailed information) - `-ve` - Enable verbose output with detailed system information
- `-hp` - Show help - `-hp` - Show help
**Examples:** **Examples:**
@@ -396,6 +562,8 @@ sf-check -ve
- SF CLI plugins and diagnostics - SF CLI plugins and diagnostics
- Common configuration issues - Common configuration issues
---
## Automatic Environment Verification ## 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: 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: