salesforce

What this skill does

# Salesforce Skill

Use the Salesforce CLI (`sf`) to interact with Salesforce orgs. The CLI must be authenticated before use. Always add `--json` for structured output.

If the `sf` binary is not available, stop and ask the user to install the Salesforce CLI using the repo's declared install metadata or the official Salesforce CLI guide. After the CLI is available, authenticate with `sf org login web` before touching org data.

## Safety Boundaries

- Do not create, update, delete, deploy, or execute Apex without explicit user confirmation.
- Do not reveal access tokens, auth URLs, refresh tokens, or verbose org-display output in chat.
- Do not export data to files unless the user asked for a saved artifact or bulk workflow.
- Do not target a production org by default when sandbox or staging access is available.

## Authentication and Org Management

### Log in (opens browser)
```bash
sf org login web --alias my-org
```

Other login methods:
```bash
# JWT-based login (CI/automation)
sf org login jwt --client-id <consumer-key> --jwt-key-file server.key --username [email protected] --alias my-org

# Login with an existing access token
sf org login access-token --instance-url https://mycompany.my.salesforce.com

# Login via SFDX auth URL (from a file)
sf org login sfdx-url --sfdx-url-file authUrl.txt --alias my-org
```

### Manage orgs
```bash
# List all authenticated orgs
sf org list --json

# Display info about the default org (access token, instance URL, username)
sf org display --json

# Display info about a specific org
sf org display --target-org my-org --json

# Display with SFDX auth URL (sensitive - contains refresh token)
sf org display --target-org my-org --verbose --json

# Open org in browser
sf org open
sf org open --target-org my-org

# Log out
sf org logout --target-org my-org
```

### Configuration and aliases
```bash
# Set default target org
sf config set target-org my-org

# List all config variables
sf config list

# Get a specific config value
sf config get target-org

# Set an alias
sf alias set [email protected]

# List aliases
sf alias list
```

## Querying Data (SOQL)

Standard SOQL queries via the default API:
```bash
# Basic query
sf data query --query "SELECT Id, Name, Email FROM Contact LIMIT 10" --json

# WHERE clause
sf data query --query "SELECT Id, Name, Amount, StageName FROM Opportunity WHERE StageName = 'Closed Won'" --json

# Relationship queries (parent-to-child)
sf data query --query "SELECT Id, Name, (SELECT LastName, Email FROM Contacts) FROM Account LIMIT 5" --json

# Relationship queries (child-to-parent)
sf data query --query "SELECT Id, Name, Account.Name FROM Contact" --json

# LIKE for text search
sf data query --query "SELECT Id, Name FROM Account WHERE Name LIKE '%Acme%'" --json

# Date filtering
sf data query --query "SELECT Id, Name, CreatedDate FROM Lead WHERE CreatedDate = TODAY" --json

# ORDER BY + LIMIT
sf data query --query "SELECT Id, Name, Amount FROM Opportunity ORDER BY Amount DESC LIMIT 20" --json

# Include deleted/archived records
sf data query --query "SELECT Id, Name FROM Account" --all-rows --json

# Query from a file
sf data query --file query.soql --json

# Tooling API queries (metadata objects like ApexClass, ApexTrigger)
sf data query --query "SELECT Id, Name, Status FROM ApexClass" --use-tooling-api --json

# Output to CSV file
sf data query --query "SELECT Id, Name, Email FROM Contact" --result-format csv --output-file contacts.csv

# Target a specific org
sf data query --query "SELECT Id, Name FROM Account" --target-org my-org --json
```

For queries returning more than 10,000 records, use Bulk API instead:
```bash
sf data export bulk --query "SELECT Id, Name, Email FROM Contact" --output-file contacts.csv --result-format csv --wait 10
sf data export bulk --query "SELECT Id, Name FROM Account" --output-file accounts.json --result-format json --wait 10
```

## Text Search (SOSL)

SOSL searches across multiple objects at once:
```bash
# Search for text across objects
sf data search --query "FIND {John Smith} IN ALL FIELDS RETURNING Contact(Name, Email), Lead(Name, Email)" --json

# Search in name fields only
sf data search --query "FIND {Acme} IN NAME FIELDS RETURNING Account(Name, Industry), Contact(Name)" --json

# Search from a file
sf data search --file search.sosl --json

# Output to CSV
sf data search --query "FIND {test} RETURNING Contact(Name)" --result-format csv
```

## Single Record Operations

### Get a record
```bash
# By record ID
sf data get record --sobject Contact --record-id 003XXXXXXXXXXXX --json

# By field match (WHERE-like)
sf data get record --sobject Account --where "Name=Acme" --json

# By multiple fields (values with spaces need single quotes)
sf data get record --sobject Account --where "Name='Universal Containers' Phone='(123) 456-7890'" --json
```

### Create a record (confirm with user first)
```bash
sf data create record --sobject Contact --values "FirstName='Jane' LastName='Doe' Email='[email protected]'" --json

sf data create record --sobject Account --values "Name='New Company' Website=www.example.com Industry='Technology'" --json

# Tooling API object
sf data create record --sobject TraceFlag --use-tooling-api --values "DebugLevelId=7dl... LogType=CLASS_TRACING" --json
```

### Update a record (confirm with user first)
```bash
# By ID
sf data update record --sobject Contact --record-id 003XXXXXXXXXXXX --values "Email='[email protected]'" --json

# By field match
sf data update record --sobject Account --where "Name='Old Acme'" --values "Name='New Acme'" --json

# Multiple fields
sf data update record --sobject Account --record-id 001XXXXXXXXXXXX --values "Name='Acme III' Website=www.example.com" --json
```

### Delete a record (require explicit user confirmation)
```bash
# By ID
sf data delete record --sobject Account --record-id 001XXXXXXXXXXXX --json

# By field match
sf data delete record --sobject Account --where "Name=Acme" --json
```

## Bulk Data Operations (Bulk API 2.0)

For large datasets (thousands to millions of records):

### Bulk export
```bash
# Export to CSV
sf data export bulk --query "SELECT Id, Name, Email FROM Contact" --output-file contacts.csv --result-format csv --wait 10

# Export to JSON
sf data export bulk --query "SELECT Id, Name FROM Account" --output-file accounts.json --result-format json --wait 10

# Include soft-deleted records
sf data export bulk --query "SELECT Id, Name FROM Account" --output-file accounts.csv --result-format csv --all-rows --wait 10

# Resume a timed-out export
sf data export resume --job-id 750XXXXXXXXXXXX --json
```

### Bulk import
```bash
# Import from CSV
sf data import bulk --file accounts.csv --sobject Account --wait 10

# Resume a timed-out import
sf data import resume --job-id 750XXXXXXXXXXXX --json
```

### Bulk upsert
```bash
sf data upsert bulk --file contacts.csv --sobject Contact --external-id Email --wait 10
```

### Bulk delete
```bash
# Delete records listed in CSV (CSV must have an Id column)
sf data delete bulk --file records-to-delete.csv --sobject Contact --wait 10
```

### Tree export/import (for related records)
```bash
# Export with relationships into JSON tree format
sf data export tree --query "SELECT Id, Name, (SELECT Name, Email FROM Contacts) FROM Account" --json

# Export with a plan file (for multiple objects)
sf data export tree --query "SELECT Id, Name FROM Account" --plan --output-dir export-data

# Import from tree JSON files
sf data import tree --files Account.json,Contact.json

# Import using a plan definition file
sf data import tree --plan Account-Contact-plan.json
```

## Schema Inspection

```bash
# Describe an object (fields, relationships, picklist values)
sf sobject describe --sobject Account --json

# Describe a custom object
sf sobject describe --sobject MyCustomObject__c --json

# Describe a Tooling API object
sf sobject describe --sobject ApexClass --use-tooling-api --json

# List all objects
sf sobject list --json

# List only custom objects