[FEATURE] harmonize how type/key combos are passed in with sf-cli

[JoernBerkefeld]

instead of requiring positionals like in mcdev retrieve cred/bu type key we could use "options":

Examples:

• how to retrieve all items of metadata-type "dataExtension"

mcdev retrieve MyProject/DEV --metadata dataExtension
mcdev retrieve MyProject/DEV -m dataExtension

• how to retrieve items of metadata-type "dataExtension" that have the key "myKey"

mcdev retrieve MyProject/DEV --metadata dataExtension:myKey
mcdev retrieve MyProject/DEV --metadata dataExtension:k:myKey
mcdev retrieve MyProject/DEV --metadata dataExtension:key:myKey

mcdev retrieve MyProject/DEV -m dataExtension:myKey
mcdev retrieve MyProject/DEV -m dataExtension:key:myKey
mcdev retrieve MyProject/DEV -m dataExtension:k:myKey

• how to retrieve items of metadata-type "dataExtension" that have the id "myId"

mcdev retrieve MyProject/DEV --metadata dataExtension:i:myId
mcdev retrieve MyProject/DEV --metadata dataExtension:id:myId

mcdev retrieve MyProject/DEV -m dataExtension:i:myId
mcdev retrieve MyProject/DEV -m dataExtension:id:myId

• how to retrieve items of metadata-type "dataExtension" that have the name "myName"

mcdev retrieve MyProject/DEV --metadata dataExtension:n:myName
mcdev retrieve MyProject/DEV --metadata dataExtension:name:myName

mcdev retrieve MyProject/DEV -m dataExtension:n:myName
mcdev retrieve MyProject/DEV -m dataExtension:name:myName

• how to retrieve items of metadata-type "dataExtension" with varies identifies and all scripts (omitting the longer versions here but shall also work):

mcdev retrieve MyProject/DEV -m dataExtension:myKey  -m dataExtension:myKey2  -m dataExtension:i:myId -m script

[github-actions]

Closed by #1274.

[JoernBerkefeld]

https://github.com/Accenture/sfmc-devtools/wiki/06.b-~-Standard-Commands/_edit

retrieve

Command: mcdev retrieve [business unit] [metadata type] [metadata key] [--like] [--metadata]

Alias: mcdev r

Retrieves all metadata from the specified Business Unit. You can limit what types are retrieved by default using the mcdev selectTypes command or by changing the list in the config file directly.

Example:

mcdev retrieve MyProject/DEV

You can omit the Business Unit which will trigger an interactive mode based on your config:

Example:

mcdev retrieve

If you already know the credentials name but want to only select the Business Unit interactively try this
Example:

mcdev retrieve MyProject

retrieve specific type:

If you want to retrieve only a certain metadata type, let's say script, then pass this type in as a second parameter. The other types will remain untouched and in place, if you've previously retrieved them.

Similarly, you can pass in multiple comma-separated types but make sure to put them in double quotes to work on all systems.

Example:

mcdev retrieve MyProject/DEV script
mcdev retrieve MyProject/DEV "script,query,automation"

retrieve specific type and key:

If you wish you may also specify the exact keys that need to be retrieved, filtering down on what's in your retrieve folder even further. Specified keys apply as a filter for all types you specify. If your naming convention does not allow for such an aggregation then please run separate commands for each type.

Example:

mcdev retrieve MyProject/DEV dataExtension "key1"
mcdev retrieve MyProject/DEV dataExtension "key1,key2"
mcdev retrieve MyProject/DEV "script,dataExtension,importFile" "key1,key2"

Note: This is not supported by types discovery and folder.

retrieve all BUs:

A special variant of this command allows you to retrieve all Business Units of a given credential at once.
Example:

mcdev retrieve MyProject/*

or even

mcdev retrieve "*"

Note: retrieve-all will fail in some CLIs if you do not wrap the asterix (*) in quotes. This is due to the special meaning of * as a parameter in these CLIs.

retrieve specific type and key via --like option:

Example:

mcdev retrieve MyProject/DEV dataExtension --like.key "key1%"
mcdev retrieve MyProject/DEV asset --like.steps.activities.name "a%o"
mcdev retrieve MyProject/DEV asset --like.key "key1%" --like.steps.activities.name "a%o"

How does it work? There are two wildcards often used in conjunction with the LIKE operator:

• The percent sign (%) represents zero, one, or multiple characters
• The underscore sign (_) represents one, single character

LIKE Operator	Description
--like.Name "a%"	Finds any values that start with "a"
--like.key "%a"	Finds any values that end with "a"
--like.name "%or%"	Finds any values that have "or" in any position
--like.CustomerKey "_r%"	Finds any values that have "r" in the second position
--like.Description "a_%"	Finds any values that start with "a" and are at least 2 characters in length
--like.customerKey "a__%"	Finds any values that start with "a" and are at least 3 characters in length
--like.steps.activities.name "a%o"	Finds any values that start with "a" AND ends with "o"
--like.key "a%,%o"	Finds any values that start with "a" OR ends with "o"

retrieve specific type and key via --metadata option:

This option is exceptionally flexible because it allows you to specify multiple type-key combos simultaneously. If set, it overrides the type or key you specified the old-fashioned way.
If the respective type features it, you can combine keys, IDs, and names in your selection. If you specify multiple --metadata parameters (or -m as an abbreviated version), the keys/ids/names are looked for separately, similar to an OR-search in SQL.

Examples:

• how to retrieve all items of metadata-type "dataExtension"

mcdev retrieve MyProject/DEV --metadata dataExtension
mcdev retrieve MyProject/DEV -m dataExtension

• how to retrieve items of metadata-type "dataExtension" that have the key "myKey"

mcdev retrieve MyProject/DEV --metadata dataExtension:myKey
mcdev retrieve MyProject/DEV --metadata dataExtension:k:myKey
mcdev retrieve MyProject/DEV --metadata dataExtension:key:myKey

mcdev retrieve MyProject/DEV -m dataExtension:myKey
mcdev retrieve MyProject/DEV -m dataExtension:key:myKey
mcdev retrieve MyProject/DEV -m dataExtension:k:myKey

• how to retrieve items of metadata-type "dataExtension" that have the id "myId"

mcdev retrieve MyProject/DEV --metadata dataExtension:i:myId
mcdev retrieve MyProject/DEV --metadata dataExtension:id:myId

mcdev retrieve MyProject/DEV -m dataExtension:i:myId
mcdev retrieve MyProject/DEV -m dataExtension:id:myId

• how to retrieve items of metadata-type "dataExtension" that have the name "myName"

mcdev retrieve MyProject/DEV --metadata dataExtension:n:myName
mcdev retrieve MyProject/DEV --metadata dataExtension:name:myName

mcdev retrieve MyProject/DEV -m dataExtension:n:myName
mcdev retrieve MyProject/DEV -m dataExtension:name:myName

• how to retrieve items of metadata-type "dataExtension" with varies identifies and all scripts (omitting the longer versions here but shall also work):

mcdev retrieve MyProject/DEV -m dataExtension:myKey  -m dataExtension:myKey2  -m dataExtension:i:myId -m script