sf-agent-framework/sf-core/data/sf-cli-reference.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Salesforce CLI (sf) Command Reference

## Overview

This document provides the complete reference for Salesforce CLI (`sf`) commands, replacing the deprecated `sfdx` commands. All agents and tasks should use these commands for Salesforce operations.

**Last Updated:** Dynamic - Always check latest Salesforce CLI documentation
**CLI Version:** sf (v2.x) - Unified Salesforce CLI
**API Version:** Read from `sfdx-project.json` in project root

## Important Notes

- Always use `sf` instead of `sfdx`
- API version should be read from `sfdx-project.json`
- Project structure follows `sfdx-project.json` configuration
- Default source directory is typically `force-app/main/default`

## Command Migration Guide

### Authentication & Org Management

#### Login to Org

```bash
# Old: sfdx force:auth:web:login
# New:
sf org login web --alias <alias> --instance-url <url>

# Login to sandbox
sf org login web --alias <alias> --instance-url https://test.salesforce.com

# Login to production
sf org login web --alias <alias> --instance-url https://login.salesforce.com

# Login using access token
sf org login access-token --instance-url <url> --access-token <token>
```

#### List Orgs

```bash
# Old: sfdx force:org:list
# New:
sf org list
sf org list --all
sf org list --clean
```

#### Display Org Details

```bash
# Old: sfdx force:org:display
# New:
sf org display --target-org <alias>
sf org display --target-org <alias> --json
```

#### Open Org

```bash
# Old: sfdx force:org:open
# New:
sf org open --target-org <alias>
sf org open --target-org <alias> --path <path>
```

### Project & Source Management

#### Create Project

```bash
# Old: sfdx force:project:create
# New:
sf project generate --name <name>
sf project generate --name <name> --template standard
sf project generate --name <name> --manifest
```

#### Deploy Source

```bash
# Old: sfdx force:source:deploy
# New:
sf project deploy start --target-org <alias>
sf project deploy start --source-dir force-app
sf project deploy start --metadata <type>:<name>
sf project deploy start --manifest manifest/package.xml

# Deploy with tests
sf project deploy start --test-level RunLocalTests
sf project deploy start --test-level RunSpecifiedTests --tests TestClass1,TestClass2
sf project deploy start --test-level RunAllTestsInOrg
```

#### Retrieve Source

```bash
# Old: sfdx force:source:retrieve
# New:
sf project retrieve start --target-org <alias>
sf project retrieve start --source-dir force-app
sf project retrieve start --metadata <type>:<name>
sf project retrieve start --manifest manifest/package.xml
```

#### Pull Changes

```bash
# Old: sfdx force:source:pull
# New:
sf project retrieve start --target-org <alias>
```

#### Push Changes

```bash
# Old: sfdx force:source:push
# New:
sf project deploy start --target-org <alias>
```

#### Validate Deployment

```bash
# Old: sfdx force:source:deploy --checkonly
# New:
sf project deploy validate --target-org <alias>
sf project deploy validate --source-dir force-app
sf project deploy validate --test-level RunLocalTests
```

### Apex Development

#### Execute Anonymous Apex

```bash
# Old: sfdx force:apex:execute
# New:
sf apex run --target-org <alias> --file <filepath>
sf apex run --target-org <alias> --apex-code "<code>"
```

#### Run Apex Tests

```bash
# Old: sfdx force:apex:test:run
# New:
sf apex test run --target-org <alias>
sf apex test run --test-level RunLocalTests
sf apex test run --class-names TestClass1,TestClass2
sf apex test run --suite-names TestSuite1
sf apex test run --code-coverage
sf apex test run --result-format json
```

#### Get Test Results

```bash
# Old: sfdx force:apex:test:report
# New:
sf apex test report --test-run-id <id>
sf apex test report --test-run-id <id> --code-coverage
```

#### View Logs

```bash
# Old: sfdx force:apex:log:list
# New:
sf apex log list --target-org <alias>

# Old: sfdx force:apex:log:get
# New:
sf apex log get --log-id <id>
sf apex log tail --target-org <alias>
```

### Data Management

#### Execute SOQL Query

```bash
# Old: sfdx force:data:soql:query
# New:
sf data query --query "<SOQL>" --target-org <alias>
sf data query --query "<SOQL>" --use-tooling-api
sf data query --query "<SOQL>" --result-format csv
```

#### Export Data

```bash
# Old: sfdx force:data:tree:export
# New:
sf data export tree --query "<SOQL>" --target-org <alias>
sf data export tree --plan --output-dir data
```

#### Import Data

```bash
# Old: sfdx force:data:tree:import
# New:
sf data import tree --files <filepath> --target-org <alias>
sf data import tree --plan <planfile>
```

#### Bulk Upsert

```bash
# Old: sfdx force:data:bulk:upsert
# New:
sf data upsert bulk --sobject <object> --file <csv> --external-id <field>
```

### Package Management

#### Create Package

```bash
# Old: sfdx force:package:create
# New:
sf package create --name <name> --package-type Unlocked
sf package create --name <name> --package-type Managed
```

#### Create Package Version

```bash
# Old: sfdx force:package:version:create
# New:
sf package version create --package <package> --installation-key <key>
sf package version create --package <package> --wait 30
```

#### Install Package

```bash
# Old: sfdx force:package:install
# New:
sf package install --package <packageId> --target-org <alias>
sf package install --package <packageId> --wait 30
```

### Lightning Web Components

#### Create LWC

```bash
# Old: sfdx force:lightning:component:create
# New:
sf lightning generate component --name <name> --output-dir force-app/main/default/lwc
```

#### Create Aura Component

```bash
# Old: sfdx force:lightning:component:create --type aura
# New:
sf lightning generate component --name <name> --type aura
```

### Metadata API

#### List Metadata

```bash
# Old: sfdx force:mdapi:listmetadata
# New:
sf org list metadata --metadata-type <type> --target-org <alias>
```

#### Deploy Metadata

```bash
# Old: sfdx force:mdapi:deploy
# New:
sf project deploy start --metadata-dir <dir> --target-org <alias>
```

#### Retrieve Metadata

```bash
# Old: sfdx force:mdapi:retrieve
# New:
sf project retrieve start --metadata <type> --target-org <alias>
```

### Schema & Object Management

#### Describe Object

```bash
# Old: sfdx force:schema:sobject:describe
# New:
sf sobject describe --sobject <object> --target-org <alias>
```

#### List Objects

```bash
# Old: sfdx force:schema:sobject:list
# New:
sf sobject list --target-org <alias>
```

### User Management

#### Create User

```bash
# Old: sfdx force:user:create
# New:
sf org create user --target-org <alias>
sf org create user --definition-file config/user-def.json
```

#### Assign Permission Set

```bash
# Old: sfdx force:user:permset:assign
# New:
sf org assign permset --name <permset> --target-org <alias>
sf org assign permset --name <permset> --on-behalf-of <username>
```

### Environment Management

#### Create Scratch Org

```bash
# Old: sfdx force:org:create
# New:
sf org create scratch --definition-file config/project-scratch-def.json
sf org create scratch --alias <alias> --duration-days 30
sf org create scratch --edition developer --set-default
```

#### Delete Scratch Org

```bash
# Old: sfdx force:org:delete
# New:
sf org delete scratch --target-org <alias>
sf org delete scratch --target-org <alias> --no-prompt
```

### Configuration & Settings

#### Set Default Org

```bash
# Old: sfdx force:config:set defaultusername=<alias>
# New:
sf config set target-org=<alias>
```

#### Set Default Dev Hub

```bash
# Old: sfdx force:config:set defaultdevhubusername=<alias>
# New:
sf config set target-dev-hub=<alias>
```

#### List Configuration

```bash
# Old: sfdx force:config:list
# New:
sf config list
```

## Reading Project Configuration

### Get API Version from sfdx-project.json

```javascript
// Read sfdx-project.json
const fs = require('fs');
const projectConfig = JSON.parse(fs.readFileSync('sfdx-project.json', 'utf8'));
const apiVersion = projectConfig.sourceApiVersion;

// Use in commands
`sf project deploy start --api-version ${apiVersion}`;
```

### Get Package Directories

```javascript
const packageDirectories = projectConfig.packageDirectories;
// Default is usually:
// [{ "path": "force-app", "default": true }]
```

## Best Practices

### 1. Always Check for sfdx-project.json

```bash
# Before running any command, verify project
if [ ! -f "sfdx-project.json" ]; then
  echo "Error: Not a Salesforce DX project directory"
  exit 1
fi
```

### 2. Use Dynamic API Version

```bash
# Extract API version from sfdx-project.json
API_VERSION=$(cat sfdx-project.json | grep sourceApiVersion | cut -d'"' -f4)
sf project deploy start --api-version $API_VERSION
```

### 3. Follow Project Structure

```bash
# Read package directories from sfdx-project.json
PACKAGE_DIR=$(cat sfdx-project.json | jq -r '.packageDirectories[0].path')
sf project deploy start --source-dir $PACKAGE_DIR
```

### 4. Error Handling

```bash
# Always check command results
if sf project deploy start --target-org myorg; then
  echo "Deployment successful"
else
  echo "Deployment failed"
  exit 1
fi
```

### 5. JSON Output for Automation

```bash
# Use --json flag for parsing results
RESULT=$(sf org display --json)
ORG_ID=$(echo $RESULT | jq -r '.result.id')
```

## Common Workflows

### Deploy to Production

```bash
# Validate first
sf project deploy validate --source-dir force-app --test-level RunLocalTests --target-org prod

# Deploy if validation passes
sf project deploy start --source-dir force-app --test-level RunLocalTests --target-org prod
```

### Quick Deploy After Validation

```bash
# Get validation ID from validate command
VALIDATION_ID=$(sf project deploy validate --json | jq -r '.result.id')

# Quick deploy using validation ID
sf project deploy quick --job-id $VALIDATION_ID --target-org prod
```

### CI/CD Pipeline Commands

```bash
# Authenticate using SFDX Auth URL
echo $SFDX_AUTH_URL | sf org login sfdx-url --sfdx-url-stdin --alias ci-org

# Run tests and capture coverage
sf apex test run --test-level RunLocalTests --code-coverage --result-format json --wait 30

# Deploy with specific tests
sf project deploy start --test-level RunSpecifiedTests --tests MyTest1,MyTest2
```

## Migration Checklist

When migrating from `sfdx` to `sf`:

1. ✅ Replace all `sfdx` commands with `sf` equivalents
2. ✅ Remove `force:` namespace from commands
3. ✅ Update `--targetusername` to `--target-org`
4. ✅ Update `--targetdevhubusername` to `--target-dev-hub`
5. ✅ Use `sfdx-project.json` for API version
6. ✅ Use `sfdx-project.json` for package directories
7. ✅ Update CI/CD scripts with new commands
8. ✅ Update documentation with new commands
9. ✅ Test all workflows with new CLI

## Additional Resources

- [Salesforce CLI Command Reference](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_unified.htm)
- [Migration from SFDX to SF](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_move_to_sf_v2.htm)
- [Salesforce DX Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_intro.htm)

## Notes

- This reference uses the unified `sf` CLI (v2)
- All deprecated `sfdx` commands should be replaced
- API versions should always be read from `sfdx-project.json`
- Project structure is defined in `sfdx-project.json`
- Always use dynamic dates and current system time