06.b ~ Standard Commands

retrieve

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

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"

deploy

Command: mcdev deploy [business unit] [metadata type] [metadata key] [--fromRetrieve] [--refresh] [--changeKeyValue=yourNewKey] [--changeKeyField=otherFieldInJson] [--execute] [--schedule] [--fixShared]

Alias: mcdev d

Deploys metadata to the specified Business Unit. Example:

mcdev deploy MyProject/DEV

Only metadata that you copied into the deploy directory will be deployed. Please keep in mind that the folder structure needs to be similar to what the retrieve command creates in the retrieve folder, including the credentials and Business Unit name.

Similarly to mcdev retrieve you can also use the interactive mode to select credential and/or Business Unit.

deploy sepcific type:

If you want to deploy only a certain metadata type, let's say dataExtension, then pass this type in as a second parameter. If there are other types in the current BU's deploy folder, these will be ignored and hence not uploaded.

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 deploy MyProject/DEV dataExtension
mcdev deploy MyProject/DEV "script,dataExtension,importFile"

deploy specific type and key:

If you wish you may also specify the exact keys that need to be deployed, filtering down on what's in your deploy 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 deploy MyProject/DEV dataExtension "key1"
mcdev deploy MyProject/DEV dataExtension "key1,key2"
mcdev deploy MyProject/DEV "script,dataExtension,importFile" "key1,key2"

deploy from retrieve folder:

Sometimes it's convenient to deploy right from the retrieve folder when you are using mcdev as a developer tool rather than only for deployments to other BUs. For this scenario we added the 4th parameter. In that case, it does not look into deploy/ but into retrieve/ finding what it needs to deploy. Example:

mcdev deploy MyProject/DEV dataExtension "key1" --fromRetrieve
mcdev deploy MyProject/DEV dataExtension "key1,key2" --fromRetrieve
mcdev deploy MyProject/DEV "script,dataExtension,importFile" "key1,key2" --fromRetrieve

deploy and change key:

Because of the special nature of the key field (with its various names across the metadata types) it cannot be simply updated by changing the value in the JSON. A deployment would otherwise trigger creating a new entry instead of updating the existing one. To still allow you to change the key value, like you could in the GUI, you have to use the optional parameters --changeKeyValue or --changeKeyField

Examples:

# changeKeyField
mcdev deploy MyProject/DEV dataExtension --changeKeyField=Name
mcdev deploy MyProject/DEV dataExtension key2 --changeKeyField=Name
mcdev deploy MyProject/DEV dataExtension "key2,key3" --changeKeyField=Name

# changeKeyValue
mcdev deploy MyProject/DEV dataExtension key1 --changeKeyValue=key2

The first of the 2 commands using --changeKeyField will deploy all dataExtensions in the deploy folder (optionally limited to the keys you specify) and try to overwrite their respective key with their name. Please ensure you check how that other field is spelled including upper-/lower-cased letters.

The second command uses --changeKeyValue can only be used if type AND key are specified. You pass along the exact new key value that we want to end up with. Therefore, in this example, your dataExtension with key "key1" will be updated to have the key "key2".

Note: Not every type allows updating the key. Please check our Metadata Type Support page for a full list.

deploy and refresh:

This is a special combination that will only work if you UPDATE an asset that happens to be an e-mail that is used in a triggeredSend. In that case, after the asset(s) were updated it will automatically invoke the refresh command for any triggeredSend that uses one of the updated e-mails.

Examples:

mcdev deploy --refresh
mcdev deploy MyProject/DEV "asset,dataExtension" "key1,key2" --refresh
mcdev deploy MyProject/DEV asset "key1" --fromRetrieve --refresh

deploy & execute:

This special combination will execute/start items after creating or updating them on the server. For Automations, you can choose to execute (runOnce) or schedule it.

Example:

mcdev deploy MyProject/DEV query --execute
mcdev deploy MyProject/DEV query "key1,key2" --execute
mcdev deploy MyProject/DEV query "key1" --fromRetrieve --execute

mcdev deploy MyProject/DEV automation --schedule
mcdev deploy MyProject/DEV automation --execute
mcdev deploy MyProject/DEV automation --execute=schedule
mcdev deploy MyProject/DEV automation "key1,key2" --execute
mcdev deploy MyProject/DEV automation "key1" --fromRetrieve --execute

Currently supported types for deploy & execute:

Name	CLI Argument	Effect
Automation	automation	Schedules automation according to already existing (but paused) schedule
Query	query	Starts query execution

deploy & --fixShared:

If you deploy Shared Data Extensions, mcdev will force you to do that via Parent BU to avoid issues with SFMC APIs. Due to another bug, if one of these shared data extensions is used in an attribute group on a child BU, SFMC fails to update the field information on the attribute group and as a result you cannot select added or renamed fields in places like journey builder.

Example: user will be asked to select which BUs should be checked & potentially fixed

mcdev deploy MyProject/DEV dataExtension --fixShared
mcdev deploy MyProject/DEV dataExtension "key1,key2" --fixShared

Example: user will be asked to select which BUs should be checked & potentially fixed, but the BUs "buName1" and "buName2" are pre-selected

mcdev deploy MyProject/DEV dataExtension "key1" --fixShared="buName1,buName2"

Example: user will be asked to select which BUs should be checked & potentially fixed, but all BUs are pre-selected

mcdev deploy MyProject/DEV dataExtension "key1" --fixShared=*

Example: user will NOT be asked to select BUs; the BUs "buName1" and "buName2" are selected to be checked & potentially fixed

mcdev deploy MyProject/DEV dataExtension "key1,key2" --fixShared="buName1,buName2" --y
mcdev deploy MyProject/DEV dataExtension "key1" --fixShared=* --y

Supported types for deploy & fixShared:

Name	CLI Argument	Effect
DataExtension	dataExtension	Triggers update of relevant attribute groups on selected BUs

deploy all BUs:

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

mcdev deploy MyProject/*

or even

mcdev deploy "*"

Note: deploy-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.

delete

Command: mcdev delete <business unit> <type> <external key>

Alias: mcdev del

Deletes the given metadata from your server. This needs to be run with care as any data stored in the deleted meta-data will be lost.

Currently supported types: Metadata Type Support

Example:

mcdev delete MyProject/_ParentBU_ dataExtension MyUserTable

mcdev delete MyProject/_ParentBU_ dataExtensionField MyUserTable.MyFieldName

mcdev del MyProject/_ParentBU_ interaction id:%235cfb1bcb-9cb7-42c9-81de-033943bbc18c/4
mcdev del MyProject/_ParentBU_ interaction id:5cfb1bcb-9cb7-42c9-81de-033943bbc18c/4

Note: For interaction (Journey) only, you can provide a key or an ID. In addition, you have to supply the version you want to delete by appending "/" and then the version. In the above example, we are trying to delete version 4 of ID "5cfb1bcb-9cb7-42c9-81de-033943bbc18c".

Note for nerds: When copying the ID from the URL, you might notice it's prefixed with "%23". If you do copy that together with the Id, mcdev del will automatically filter it for you. It, therefore, works with or without the leading "%23".

refresh

Command: mcdev refresh <business unit> [type] [external key]

Alias: mcdev re

This commands lets you refresh the metadata of a given type and key. Currently this is only supported for Triggered Sends, therefore, if you do not specify a type, it will default to triggeredSendDefinition.

If you do not specify keys, for triggeredSendDefinition, it will refresh all running ("Active") triggered sends on the given BU. It will also check if all dependencies for that triggered send are available to ensure it can be published & restarted after it was paused. However, if you made changes to the email that cause issues, you might still get an error, which prevents you from restarting it. If you updated lots of emails and want your journeys (and triggered sends) to pick up the changes choose this version of the command.

Currently supported types:

Name	CLI Argument	Effect
Triggered Send	triggeredSendDefinition	Refreshes emails in active triggeredSends and thereby any emails in Journeys.

Example:

mcdev re MyProject/_ParentBU_

mcdev refresh MyProject/_ParentBU_ triggeredSendDefinition myKey

mcdev refresh MyProject/_ParentBU_ triggeredSendDefinition "myKey,myOtherKey"

mcdev refresh MyProject/_ParentBU_ . "myKey,myOtherKey"

execute

Command: mcdev execute <business unit> <type> [key] [--like] [--schedule]

Alias: mcdev exec / mcdev start

This command lets you start / run / execute metadata of a given type and key.

Currently supported types:

Name	CLI Argument	Effect
Automation	automation	RunOnce or Schedules automation according to already existing schedule
Query	query	Starts query execution

Example:

mcdev execute MyProject/DEV automation key1
mcdev execute MyProject/DEV automation "key1,key2,key3"

mcdev execute MyProject/DEV query key1
mcdev execute MyProject/DEV query "key1,key2,key3"

execute with --like operator:

mcdev execute MyProject/DEV automation --like.key "myprefix_%"
mcdev execute MyProject/DEV query --like.key "myprefix_%" --like.r__folder_Path "Query/Testing%"

execute with --schedule operator:

Instead of running an automation once, you can also start it with it's schedule

mcdev execute MyProject/DEV automation key1 --schedule

execute on all BUs:

This is a variation of execute command that allows you to execute specified items on all BUs. mcdev will look for the items of specified types and keys on all BUs and execute them.

Example:

mcdev execute MyProject/* query key1
mcdev execute MyProject/* automation "key1,key2"
mcdev execute MyProject/* query "key1,key2,key3"

schedule

Command: mcdev schedule <business unit> <type> [key] [--like]

Alias: mcdev sched

This command is a shortcut for mcdev execute --schedule.

Currently supported types:

Name	CLI Argument	Effect
Automation	automation	Schedules automation according to already existing (but paused) schedule

Example:

mcdev schedule MyProject/DEV automation key1
mcdev schedule MyProject/DEV automation "key1,key2,key3"

schedule with --like operator:

mcdev schedule MyProject/DEV automation --like.key "myprefix_%"

schedule on all BUs:

This is a variation of execute command that allows you to execute specified items on all BUs. mcdev will look for the items of specified types and keys on all BUs and execute them.

Example:

mcdev schedule MyProject/* automation key1
mcdev schedule MyProject/* automation "key1,key2"

pause

Command: mcdev pause <business unit> <type> [key] [--like]

Alias: mcdev p / mcdev stop

This command lets you pause metadata of a given type and key.

Currently supported types:

Name	CLI Argument	Effect
Automation	automation	pauses scheduled automation

Example:

mcdev pause MyProject/DEV automation key1
mcdev pause MyProject/DEV automation "key1,key2,key3"

pause with --like operator:

mcdev pause MyProject/DEV automation --like.key "myprefix_%"
mcdev pause MyProject/DEV automation --like.key "myprefix_%" --like.r__folder_Path "Query/Testing%"

pause on all BUs:

This is a variation of pause command that allows you to pause specified items on all BUs. mcdev will look for the items of specified types and keys on all BUs and pause them.

Example:

mcdev pause MyProject/* automation key1
mcdev pause MyProject/* automation "key1,key2,key3"

fixKeys

Command: mcdev fixKeys <business unit> <type> [key] [--like] [--execute] [--schedule]

Alias: mcdev fx

Retrieves specified metadata to ensure it works on the latest server version, prepares the update locally to ensure the key matches the name, and redeploys the metadata.

Example:

mcdev fixKeys MyProject/DEV dataExtension
mcdev fixKeys MyProject/DEV query
mcdev fixKeys * query "key1,key2" 
mcdev fixKeys * query "key1,key2" --execute
mcdev fixKeys MyProject/DEV automation
mcdev fixKeys MyProject/DEV automation --execute
mcdev fixKeys MyProject/* automation --like.name="foobar%"
mcdev fixKeys MyProject/* automation --like.name="foobar%" --schedule

Please, note that you might need to retrieve dependent metadata to have up-to-date data in the retrieve-folder. For example, in case of queries after fixing the keys, you should retrieve automations.

Note to CLI experts:

You can run this command without the interactive wizard asking questions using the --skipInteraction (or short--yes/--y) flag. In this case, you need to provide a few values in the command:

mcdev fixKeys MyProject/* query --y.fixKeysReretrieve
mcdev fixKeys MyProject/* query --y.fixKeysReretrieve=false

CLI Argument	Description
--y.fixKeysReretrieve	enable automatic re-retrieval of metadata that's dependant on the fixed type
--y.fixKeysReretrieve=false	skip automatic re-retrieval of metadata that's dependant on the fixed type