Skip to content

hardis:scratch:pull

Description

Command Behavior

Pulls metadata changes from your scratch org or source-tracked sandbox into your local project files.

This command is essential for synchronizing your local development environment with the changes you've made directly in your Salesforce org. After pulling, you can then stage and commit the relevant files to your version control system.

Key features and considerations:

  • Underlying Command: Internally, this command executes sf project retrieve start to fetch the metadata.
  • Error Handling: If the pull operation encounters errors, it offers to automatically add the problematic items to your .forceignore file and then attempts to pull again, helping you resolve conflicts and ignore unwanted metadata.
  • Missing Updates: If you don't see certain updated items in the pull results, you might need to manually retrieve them using the Salesforce Extension's Org Browser or the Salesforce CLI directly. Refer to the Retrieve Metadatas documentation for more details.
  • Automatic Retrieval: You can configure the autoRetrieveWhenPull property in your .sfdx-hardis.yml file to always retrieve specific metadata types (e.g., CustomApplication) that might not always be detected as updates by project:retrieve:start.

Example .sfdx-hardis.yml configuration for autoRetrieveWhenPull: 

autoRetrieveWhenPull:
  - CustomApplication:MyCustomApplication
  - CustomApplication:MyOtherCustomApplication
  - CustomApplication:MyThirdCustomApp

For a visual explanation of the process, watch this video:

Technical explanations

The command's technical implementation focuses on robust metadata synchronization:

  • Salesforce CLI Wrapper: It acts as a wrapper around the standard Salesforce CLI sf project retrieve start command, providing enhanced error handling and configuration options.
  • Force Source Pull Utility: The core logic resides in the forceSourcePull utility function, which orchestrates the retrieval process, including handling .forceignore updates.
  • Configuration Integration: It reads the autoRetrieveWhenPull setting from the project's .sfdx-hardis.yml to determine additional metadata to retrieve automatically.
  • User Feedback: Provides clear messages to the user regarding the pull status and guidance for troubleshooting.

Parameters

Name Type Description Default Required Options
debug
-d		 boolean Activate debug mode (more logs)
flags-dir option undefined
json boolean Format output as json.
skipauth boolean Skip authentication check when a default username is required
target-org
-o		 option undefined
websocket option Websocket host:port for VsCode SFDX Hardis UI integration

Examples

$ sf hardis:scratch:pull