How to replicate deployment errors using Salesforce CLI

Sometimes it's hard to tell if a validation or deployment error has come from Gearset or from the Salesforce Metadata API directly. Replicating the error with another tool can rule out Gearset as the cause.

This article also applies if no error was received, but the deployment result in the org doesn't match what the deployment package zip contains.

You can also follow these steps using Workbench if you prefer a browser-based tool.

Why Salesforce CLI?

Salesforce CLI is Salesforce's official command-line tool for deploying metadata. Like Gearset, it talks to Salesforce via the Metadata API.

If the same deployment errors appear when deploying through the CLI, that confirms the issue is with the Salesforce org rejecting the deployment, not something Gearset is doing.

Note: Salesforce recommends using Salesforce CLI instead of Workbench. Workbench is an open-source community tool that Salesforce does not maintain.

Prerequisites

You'll need Salesforce CLI installed.

Check the CLI is available and up to date:

sf --version
sf update

You can run these commands from any terminal (Terminal on macOS, Command Prompt or PowerShell on Windows, or the integrated terminal in VS Code if you use it).

Step 1: Download the deployment package from Gearset

There are a few ways to download the deployment package .zip that Gearset uploads to your Salesforce org:

From the Download package button on the deployment summary page before the validation or deployment
From the Deployment History page
From the Download package button in the CI job History page (if the CI job failed, you'll need to create the same comparison manually via Compare and Deploy)

Step 2: Set up the CLI and authenticate

The CLI needs a Salesforce project to work from, even for simple operations. To create one:

sf project generate --name my-project
cd my-project

Then authenticate with the org you want to investigate:

sf org login web --alias my-org --set-default

This opens a browser window. Log in with the same credentials you use in Gearset. This is important for an accurate comparison.

Tip: If you hit login or redirect issues, specify the instance URL:

sf org login web \
  --instance-url https://my-sandbox.my.salesforce.com \
  --alias my-org \
  --set-default

Step 3: Deploy (or validate) the package

Extract the deployment .zip you downloaded from Gearset to a folder (e.g. gearset-package/).

To validate only (check-only, no changes saved to the org):

sf project deploy start \
  --metadata-dir gearset-package/ \
  --dry-run \
  --test-level NoTestRun

Note: If deploying to a production org, you can't use NoTestRun. Use RunLocalTests instead:

sf project deploy start \
  --metadata-dir gearset-package/ \
  --dry-run \
  --test-level RunLocalTests

To deploy (push changes to the org):

sf project deploy start \
  --metadata-dir gearset-package/ \
  --test-level NoTestRun

For production orgs, add --test-level RunLocalTests.

Step 4: Compare the results

Once the deployment or validation finishes, the CLI displays any errors in the terminal output.

You should see the same validation or deployment errors that appeared in Gearset. If the errors match, this confirms the issue comes from the Salesforce Metadata API, not from Gearset.

Conclusion

If the CLI shows the same errors as Gearset, you can focus on finding out why the Salesforce Metadata API is returning those errors. You can open a Salesforce support case to investigate.

Tip: When raising a case with Salesforce, only mention Salesforce CLI and don't bring Gearset into the conversation. Salesforce won't support third-party tools, but because the CLI is their own tool, they can help you directly.