retrieve Commands

Description for retrieve metadata

You must run this command from within a project.

Metadata components are retrieved in source format by default. Retrieve them in metadata format by specifying the --target-metadata-dir flag, which retrieves the components into a ZIP file in the specified directory.

If your org allows source tracking, then this command tracks the changes in your source. Some orgs, such as production org, never allow source tracking. You can also use the "--no-track-source" flag when you create a scratch or sandbox org to disable source tracking.

To retrieve multiple metadata components, either use multiple --metadata <name> flags or use a single --metadata flag with multiple names separated by spaces. Enclose names that contain spaces in one set of double quotes. The same syntax applies to --manifest and --source-dir.

Examples for retrieve metadata

Retrieve remote changes:

1sf retrieve metadata

Retrieve the source files in a directory:

1sf retrieve metadata --source-dir path/to/source

Retrieve a specific Apex class and the objects whose source is in a directory (both examples are equivalent):

1sf retrieve metadata --source-dir path/to/apex/classes/MyClass.cls path/to/source/objects

1sf retrieve metadata --source-dir path/to/apex/classes/MyClass.cls --source-dir path/to/source/objects

Retrieve all Apex classes:

1sf retrieve metadata --metadata ApexClass

Retrieve a specific Apex class:

1sf retrieve metadata --metadata ApexClass:MyApexClass

Retrieve all custom objects and Apex classes (both examples are equivalent):

1sf retrieve metadata --metadata CustomObject ApexClass

1sf retrieve metadata --metadata CustomObject --metadata ApexClass

Retrieve all metadata components listed in a manifest:

1sf retrieve metadata --manifest path/to/package.xml

Retrieve metadata from a package:

1sf retrieve metadata --package-name MyPackageName

Retrieve metadata from multiple packages, one of which has a space in its name (both examples are equivalent):

1sf retrieve metadata --package-name Package1 "PackageName With Spaces" Package3

1sf retrieve metadata --package-name Package1 --package-name "PackageName With Spaces" --package-name Package3

Retrieve the metadata components listed in the force-app directory, but retrieve them in metadata format into a ZIP file in the "output" directory:

1sf retrieve metadata --source-dir force-app --target-metadata-dir output

Retrieve in metadata format and automatically extract the contents into the "output" directory:

1sf retrieve metadata --source-dir force-app --target-metadata-dir output --unzip

Usage

sf retrieve metadata

[--json]

[-a API-VERSION]

[-c]

[-x MANIFEST]

[-m METADATA]

[-n PACKAGE-NAME]

[--single-package]

[-d SOURCE-DIR]

[-t TARGET-METADATA-DIR]

[-o TARGET-ORG]

[-w WAIT]

[-z]

[--zip-file-name ZIP-FILE-NAME]

Flags

--json

Optional

Format output as json.

Type: boolean

-a | --api-version API-VERSION

Optional

Target API version for the retrieve.

Use this flag to override the default API version, which is the latest version supported the CLI, with the API version in your package.xml file.

Type: option

-c | --ignore-conflicts

Optional

Ignore conflicts and retrieve and save files to your local filesystem, even if they overwrite your local changes.

This flag applies only to orgs that allow source tracking. It has no effect on orgs that don't allow it, such as production orgs.

Type: boolean

-x | --manifest MANIFEST

Optional

File path for the manifest (package.xml) that specifies the components to retrieve.

If you specify this parameter, don’t specify --metadata or --source-dir.

Type: option

-m | --metadata METADATA

Optional

Metadata component names to retrieve.

Type: option

-n | --package-name PACKAGE-NAME

Optional

Package names to retrieve.

Type: option

--single-package

Optional

Indicates that the zip file points to a directory structure for a single package.

Type: boolean

-d | --source-dir SOURCE-DIR

Optional

File paths for source to retrieve from the org.

The supplied paths can be to a single file (in which case the operation is applied to only one file) or to a folder (in which case the operation is applied to all source files in the directory and its subdirectories).

Type: option

-t | --target-metadata-dir TARGET-METADATA-DIR

Optional

Directory that will contain the retrieved metadata format files or ZIP.

Type: option

-o | --target-org TARGET-ORG

Optional

Login username or alias for the target org.

Overrides your default org.

Type: option

-w | --wait WAIT

Optional

Number of minutes to wait for the command to complete and display results to the terminal window.

If the command continues to run after the wait period, the CLI returns control of the terminal window to you.

Type: option

-z | --unzip

Optional

Extract all files from the retrieved zip file.

Type: boolean

--zip-file-name ZIP-FILE-NAME

Optional

File name to use for the retrieved zip file.

Type: option

Description for retrieve metadata preview

You must run this command from within a project.

The command outputs a table that describes what will happen if you run the "sf retrieve metadata" command. The table lists the metadata components that will be retrieved and deleted. The table also lists the current conflicts between files in your local project and components in the org. Finally, the table lists the files that won't be retrieved because they're included in your .forceignore file.

If your org allows source tracking, then this command considers conflicts between the org and local. Some orgs, such as production orgs, never allow source tracking. Use the "--no-track-source" flag when you create a scratch or sandbox org to disable source tracking.

Examples for retrieve metadata preview

Preview the retrieve of all changes from the org:

1sf retrieve metadata preview

Preview the retrieve when ignoring any conflicts:

1sf retrieve metadata preview --ignore-conflicts

Usage

sf retrieve metadata preview

[--json]

[-c]

[-o TARGET-ORG]

Flags

--json

Optional

Format output as json.

Type: boolean

-c | --ignore-conflicts

Optional

Ignore conflicts and preview the retrieve of remote components, even if they will overwrite local changes.

This flag applies only to orgs that allow source tracking. It has no effect on orgs that don't allow it, such as production orgs.

Type: boolean

-o | --target-org TARGET-ORG

Optional

Login username or alias for the target org.

Overrides your default org.

Type: option