feat: support retrieves in metadata format

command-snapshot.json

@@ -91,9 +91,13 @@
       "manifest",
       "metadata",
       "package-name",
+      "single-package",
       "source-dir",
+      "target-metadata-dir",
       "target-org",
-      "wait"
+      "unzip",
+      "wait",
+      "zip-file-name"
     ],
     "alias": []
   },

messages/retrieve.metadata.md

@@ -51,6 +51,14 @@ To retrieve multiple metadata components, either use multiple --metadata <name>
   <%= config.bin %> <%= command.id %> --package-name Package1 "PackageName With Spaces" Package3
   <%= config.bin %> <%= command.id %> --package-name Package1 --package-name "PackageName With Spaces" --package-name Package3
 
+- Retrieve using Metadata API
+
+  <%= config.bin %> <%= command.id %> --source-dir force-app --target-metadata-dir output
+
+- Retrieve using Metadata API and automatically unzip the contents
+
+  <%= config.bin %> <%= command.id %> --source-dir force-app --target-metadata-dir output --unzip
+
 # flags.api-version.summary
 
 Target API version for the retrieve.
@@ -65,7 +73,7 @@ Ignore conflicts and retrieve and save files to your local filesystem, even if t
 
 # flags.ignore-conflicts.description
 
-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. 
+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.
 
 # flags.manifest.summary
 
@@ -107,6 +115,26 @@ Number of minutes to wait for the command to complete and display results to the
 
 If the command continues to run after the wait period, the CLI returns control of the terminal window to you.
 
+# flags.metadata-dir.summary
+
+Root of directory or zip file of metadata formatted files to retrieve.
+
+# flags.single-package.summary
+
+Indicates that the zip file points to a directory structure for a single package.
+
+# flags.target-metadata-dir.summary
+
+Directory root for the retrieved files.
+
+# flags.unzip.summary
+
+Extract all files from the retrieved zip file.
+
+# flags.zip-file-name.summary
+
+File name to use for the retrieved zip file.
+
 # spinner.start
 
 Preparing retrieve request
@@ -128,3 +156,11 @@ There are changes in your local files that conflict with the org changes you're
 - To overwrite the local changes, rerun this command with the --ignore-conflicts flag.
 
 - To overwrite the remote changes, run the "sf deploy metadata" command with the --ignore-conflicts flag.
+
+# info.WroteZipFile
+
+Wrote retrieve zip file to %s.
+
+# info.ExtractedZipFile
+
+Extracted %s to %s.

messages/validation.md

@@ -0,0 +1,11 @@
+# error.InvalidFlagPath
+
+Invalid path specified: %s. %s
+
+# error.ExpectedDirectory
+
+Expected a directory but found a file.
+
+# error.ExpectedFileOrDirToExist
+
+Expected a file or directory to exist.

package.json

@@ -5,7 +5,7 @@
   "author": "Salesforce",
   "bugs": "https://github.com/forcedotcom/cli/issues",
   "dependencies": {
-    "@oclif/core": "^1.15.0",
+    "@oclif/core": "^1.16.0",
     "@salesforce/core": "^3.26.1",
     "@salesforce/kit": "^1.5.45",
     "@salesforce/sf-plugins-core": "1.14.0",
@@ -33,8 +33,8 @@
     "@types/archiver": "^5.3.1",
     "@types/fs-extra": "^9.0.13",
     "@types/shelljs": "^0.8.11",
-    "@typescript-eslint/eslint-plugin": "^5.32.0",
-    "@typescript-eslint/parser": "^5.32.0",
+    "@typescript-eslint/eslint-plugin": "^5.36.2",
+    "@typescript-eslint/parser": "^5.36.2",
     "archiver": "^5.3.1",
     "chai": "^4.3.6",
     "cross-env": "^7.0.3",

schemas/retrieve-metadata.json

@@ -3,66 +3,73 @@
   "$ref": "#/definitions/RetrieveResultJson",
   "definitions": {
     "RetrieveResultJson": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "files": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/FileResponse"
-          }
-        },
-        "done": {
-          "type": "boolean"
-        },
-        "fileProperties": {
-          "anyOf": [
-            {
-              "$ref": "#/definitions/FileProperties"
-            },
-            {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/FileProperties"
-              }
-            }
-          ]
-        },
-        "id": {
-          "type": "string"
-        },
-        "status": {
-          "$ref": "#/definitions/RequestStatus"
-        },
-        "success": {
-          "type": "boolean"
-        },
-        "messages": {
-          "anyOf": [
-            {
+      "anyOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "files": {
               "type": "array",
               "items": {
-                "$ref": "#/definitions/RetrieveMessage"
+                "$ref": "#/definitions/FileResponse"
               }
             },
-            {
-              "$ref": "#/definitions/RetrieveMessage"
+            "done": {
+              "type": "boolean"
+            },
+            "fileProperties": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/FileProperties"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/FileProperties"
+                  }
+                }
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "status": {
+              "$ref": "#/definitions/RequestStatus"
+            },
+            "success": {
+              "type": "boolean"
+            },
+            "messages": {
+              "anyOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/RetrieveMessage"
+                  }
+                },
+                {
+                  "$ref": "#/definitions/RetrieveMessage"
+                }
+              ]
+            },
+            "zipFile": {
+              "type": "string",
+              "description": "`base64` encoded string"
             }
+          },
+          "required": [
+            "done",
+            "fileProperties",
+            "files",
+            "id",
+            "status",
+            "success",
+            "zipFile"
           ]
         },
-        "zipFile": {
-          "type": "string",
-          "description": "`base64` encoded string"
+        {
+          "$ref": "#/definitions/MetadataRetrieveResultJson"
         }
-      },
-      "required": [
-        "done",
-        "fileProperties",
-        "files",
-        "id",
-        "status",
-        "success",
-        "zipFile"
       ]
     },
     "FileResponse": {
@@ -231,6 +238,68 @@
         "problem"
       ],
       "additionalProperties": false
+    },
+    "MetadataRetrieveResultJson": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "zipFilePath": {
+          "type": "string"
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FileResponse"
+          }
+        },
+        "done": {
+          "type": "boolean"
+        },
+        "fileProperties": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/FileProperties"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/FileProperties"
+              }
+            }
+          ]
+        },
+        "id": {
+          "type": "string"
+        },
+        "status": {
+          "$ref": "#/definitions/RequestStatus"
+        },
+        "success": {
+          "type": "boolean"
+        },
+        "messages": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/RetrieveMessage"
+              }
+            },
+            {
+              "$ref": "#/definitions/RetrieveMessage"
+            }
+          ]
+        }
+      },
+      "required": [
+        "done",
+        "fileProperties",
+        "files",
+        "id",
+        "status",
+        "success",
+        "zipFilePath"
+      ]
     }
   }
 }

src/commands/deploy.ts

@@ -25,13 +25,13 @@ export default class Deploy extends SfCommand<void> {
   public static summary = messages.getMessage('summary');
   public static description = messages.getMessage('description');
   public static examples = messages.getMessages('examples');
+  public static enableJsonFlag = false;
 
   public static flags = {
     interactive: Flags.boolean({
       summary: messages.getMessage('flags.interactive.summary'),
     }),
   };
-  public static enableJsonFlag = false;
 
   public async run(): Promise<void> {
     process.setMaxListeners(new Env().getNumber('SF_MAX_EVENT_LISTENERS') || 1000);

src/commands/deploy/metadata.ts

@@ -21,6 +21,7 @@ Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/plugin-deploy-retrieve', 'deploy.metadata');
 
 const exclusiveFlags = ['manifest', 'source-dir', 'metadata', 'metadata-dir'];
+
 export default class DeployMetadata extends SfCommand<DeployResultJson> {
   public static readonly description = messages.getMessage('description');
   public static readonly summary = messages.getMessage('summary');