Salesforce CLI Operations (sf v2)

Salesforce CLI v2 ships as @salesforce/cli; the sfdx executable is an alias of sf, and every sfdx invocation resolves to the same v2 command with the same flags. sfdx (v7) must be uninstalled before installing v2 or npm fails with EEXIST.

When to use

Deployment mechanics live in skill sf-deployment-strategies; org creation and sandbox lifecycle in skill sf-scratch-orgs-sandboxes; data commands in skill sf-data-management; static analysis in skill sf-code-analyzer-quality.

Topic map

Global flags

There is no --loglevel flag in v2. Set SF_LOG_LEVEL=error|warn|info|debug|trace|fatal; logs go to ~/.sf/sf-<YYYY-MM-DD>.log, rotate daily, and are deleted after seven days.

apiVersion vs sourceApiVersion precedence

vibe-force pins one value: apiVersion in config/vibe-force.defaults.json (67.0). Project setup writes the same value to sourceApiVersion in sfdx-project.json, so sf doctor's sourceApiVersion matches apiVersion test passes.

Core patterns

1. Authorize non-interactively, then alias everything

# CI: JWT bearer flow. Requires a connected app / external client app with the cert uploaded.
sf org login jwt \
  --client-id "$SF_CONSUMER_KEY" \
  --jwt-key-file "$PWD/server.key" \
  --username "$SF_USERNAME" \
  --instance-url https://mydomain.my.salesforce.com \
  --alias vf-int --set-default

# CI alternative: reuse an authorization captured on a workstation.
sf org auth show-sfdx-auth-url --target-org vf-int --no-prompt --json > auth.json
sf org login sfdx-url --sfdx-url-file auth.json --alias vf-int --set-default

sf org login web is for humans only; it opens http://localhost:1717/OauthRedirect. High-assurance (stepped-up) authentication makes the JWT flow unusable for that org. Dev Hub orgs that must run sf org create scratch|sandbox need a connected app, not an external client app.

2. Make the org selection explicit and reviewable

sf alias set vf-dev=test-3k9x@example.com vf-prod=release@acme.com
sf config set target-org vf-dev                  # project-local (.sf/config.json)
sf config set --global org-api-version 67.0
sf config list

Resolution order for any config-backed value: command-line flag, then local project config, then global config. vibe-force commands and checks always pass --target-org so no run depends on the ambient default; productionAliases in .vibeforce/config.json is matched against that value by the vibe-force hooks before a deploy or destructive data command is allowed.

3. Script against --json, never against human output

# Which API version does the org actually run?
sf org display --target-org vf-dev --json | jq -r '.result.apiVersion'

# Fail the job when the org is not connected.
status=$(sf org display --target-org vf-dev --json | jq -r '.result.connectedStatus')
[ "$status" = "Connected" ] || { echo "org not connected: $status"; exit 3; }

# Row count guard after a data load.
sf data query --target-org vf-dev --json \
  --query "SELECT COUNT() FROM Account WHERE Industry='Energy'" \
  | jq -e '.result.totalSize >= 100' >/dev/null

Salesforce guarantees only additive changes to --json shapes; breaking changes go through a deprecation period behind an environment variable. Human-readable output carries no such guarantee, so grep on tables is not a contract. Per-command schemas live in each plugin repo under schemas/<command-with-hyphens>.json; sf which <command> names the owning plugin.

4. Treat exit codes as the gate signal

With --json, a failure still prints JSON on stderr with status non-zero plus name, message, and often data; SF_JSON_TO_STDOUT=true moves it to stdout, which is what a wrapper that pipes into jq needs.

5. Install plugins explicitly; understand JIT

sf plugins                                   # installed (and JIT-installed) plugins with versions
sf plugins install @salesforce/plugin-code-analyzer
sf plugins install @salesforce/plugin-lightning-dev
sf plugins link ./my-local-plugin            # dev only: linked plugins are never auto-updated
sf plugins inspect @salesforce/plugin-data
sf plugins update

These plugins ship as just-in-time (JIT) entries in the CLI manifest and install on first use of one of their commands: @salesforce/plugin-code-analyzer, @salesforce/plugin-community, @salesforce/plugin-custom-metadata, @salesforce/plugin-dev, @salesforce/plugin-devops-center, @salesforce/plugin-flow, @salesforce/plugin-lightning-dev, @salesforce/plugin-signups, @salesforce/plugin-ui-bundle-dev, @salesforce/sfdx-plugin-lwc-test. A CI container should install them up front — the first-use install writes to the CLI cache and adds latency (and a network dependency) to the job that needs the command. sf update does not update JIT or user-installed plugins.

6. Diagnose with doctor, logs, and which

sf doctor --output-dir .vibeforce/reports/doctor
sf doctor --command "org list --all"          # runs it in debug mode, writes stdout+stderr logs
sf doctor --plugin @salesforce/plugin-deploy-retrieve
SF_LOG_LEVEL=debug sf project deploy start --target-org vf-dev --dry-run

sf doctor always runs three built-in tests: salesforcedx plugin not installed (uninstall it if it fails), no linked plugins, and sourceApiVersion matches apiVersion.

Anti-patterns

Verification

sf version                                    # expect @salesforce/cli/2.x
sf config list                                # target-org, org-api-version resolved as intended
sf org list --all --json | jq -r '.result.nonScratchOrgs[]?.alias'
sf org display --target-org vf-dev --json | jq '{api:.result.apiVersion, status:.result.connectedStatus}'
sf org list limits --target-org vf-dev --json | jq '.result[] | select(.name|test("DailyApiRequests|DataStorageMB"))'

# vibe-force gates that exercise the CLI end to end
node "$VF_ROOT/scripts/checks/vf-check.mjs" local
node "$VF_ROOT/scripts/checks/vf-check.mjs" apex --target-org vf-dev
node "$VF_ROOT/scripts/checks/vf-check.mjs" deploy-validate --target-org vf-int

vf-check analyzer requires @salesforce/plugin-code-analyzer; vf-check apex, deploy-validate, deploy-quick, smoke, and verify all require a working authorization for the alias they are given, and exit 3 when the CLI reports an org or network failure rather than a gate failure.

References

• references/command-matrix.md — topic → command → key flags → purpose, plus the retired sfdx force:* → sf migration table.
• references/auth-and-ci.md — JWT setup end to end, connected app configuration, sfdx-url files, GitHub Actions/Jenkins/CircleCI snippets.
• references/json-automation.md — --json shapes for org display, org list, project deploy start|validate, apex run test, data query, data import bulk, with jq extraction recipes.
• references/env-vars.md — SF_* environment variables, config variables, and their precedence.
• Salesforce CLI Command Reference (generated): https://github.com/salesforcecli/cli/blob/main/README.md
• Salesforce CLI Setup Guide: https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm
• Salesforce DX Developer Guide, Authorization: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth.htm
• Environment variable definitions (@salesforce/core): https://github.com/forcedotcom/sfdx-core/blob/main/src/config/envVars.ts