Metadata#retrieve(options) examples

Could you please provide an example on how to use the Metadata#retrieve(options)? Assuming I have a manifest file (e.g. package.xml), how do I tell the Metadata#retrieve(options) to retrieve the metadata based on the package.xml? I’m not quite sure what the packageNames stands for in the request options { packageNames: [ 'My Test Package' ] }.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>MyCustomObject__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>*</members>
        <name>CustomTab</name>
    </types>
    <types>
        <members>Standard</members>
        <name>Profile</name>
    </types>
    <version>30.0</version>
</Package>

Thanks in advance!

obs: You could label this as question and not a issue.

[0cv]

For clarity, unpackaged expects the package.XML formatted as JS object (and not as file). That would be a valid request:

conn.metadata.retrieve({
    apiVersion: '38.0',
    singlePackage: true,
    unpackaged: {
      types: [{
        'members': ['Account', 'Contact'],
        'name': 'CustomObject'
      }, {
        'members': ['*'],
        'name': 'ApexClass'
      }]
    }
  })

[gonardfreeman]

Thanks @Krisa ! Why there is no info about that in docs? How dev need to understand that he could repeat xml structure in js object? Please update docs. Your tool is real powerfull 😉