06.b ~ Standard Commands

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

deploy

Command: mcdev deploy [business unit] [metadata type] [metadata key] [--metadata] [--fromRetrieve] [--refresh] [--keySuffix] [--noMidSuffix] [--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"

mcdev deploy MyProject/DEV -m "dataExtension:key1"
mcdev deploy MyProject/DEV -m "dataExtension:key1" -m "dataExtension:key2"
mcdev deploy MyProject/DEV -m "script:key1" -m "script:key2" -m "dataExtension:key3" -m "dataExtension:key4" -m "importFile:key5" -m "importFile:key6"

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.

In some scenarios, all you want is to append a suffix (e.g. for assets because they share the key across BUs or for shared DataExtensions). For that, we've added --keySuffix. You can use it stand-alone or together with --changeKeyField. Be aware that if the maximum key-length is exhausted already, --keySuffix will automatically cut of the end of your existing key to add the suffix you specified!

Lastly, there is the option --noMidSuffix which deactivates automatically adding the MID suffix when you try to clone an asset to another BU. If you want to specify your own suffix to prevent the unique-key error during creation, this is your friend. Make sure to use this command together with --keySuffix or after applying a suffix via templating (buildTemplate/buildDefinition).

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

# keySuffix
mcdev deploy MyProject/DEV dataExtension --changeKeyField=Name --keySuffix "_DEV"
mcdev deploy MyProject/DEV dataExtension myKey --keySuffix "_DEV"
mcdev deploy MyProject/DEV dataExtension --keySuffix "_DEV"

# noMidSuffix
mcdev deploy MyProject/DEV asset--changeKeyField=name --noMidSuffix --keySuffix "_DEV"
mcdev deploy MyProject/DEV asset myKey --noMidSuffix --keySuffix "_DEV"
mcdev deploy MyProject/DEV asset --noMidSuffix --keySuffix "_DEV"

# noMidSuffix with templating
# - step 1 (create template with market that replaces for "_DEV")
mcdev buildTemplate MyProject/DEV asset myKey_DEV myMarketDEV
# - step 2 (filename stays unchanged after template creation for easier execution of buildDefinition)
mcdev buildDefinition MyProject/PROD asset myKey_DEV myMarketPROD
# - step 3 (key was changed to "myKey_PROD" by buildDefinition applying your prod market)
mcdev deploy MyProject/PROD asset myKey_PROD --noMidSuffix

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> [--metadata]

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_ -m 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] [--metadata] [--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
mcdev fixKeys MyProject/DEV dataExtension
mcdev fixKeys MyProject/DEV query
mcdev fixKeys MyProject/DEV "dataExtension,query"
mcdev fixKeys MyProject/DEV -m dataExtension -m query
mcdev fixKeys MyProject/DEV -m query:key1 
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

replaceContentBlock

Command: mcdev replaceContentBlock <--bu business unit> <--to 'key' | 'name' | 'id'> [--metadata type] [--from 'key' | 'name' | 'id'] [--skipRetrieve] [--skipDeploy] [--refresh]

Alias: mcdev rcb

This replaces ContentBlockByName, ContentBlockById, or ContentBlockByKey with your chosen method. It works for Ampscript and the "Platform.Function."-prefixed SSJS alternatives. It retrieves specified metadata to ensure it parses the latest server versions, prepares the update locally, and then redeploys the metadata.

--bu Contrary to older methods, replaceContentBlock requires you to define the target BU via the --bu parameter instead of just naming it directly after the command itself. That gives you a bit more flexibility in how you write your commands, but it makes no difference otherwise.

--to This defines which function you want your code to be converted to use. Possible values: "name", "id", "key".

--metadata (optional) Set the types (or even type and keys/ids/names) that you want to fix. If omitted, all supported types will be updated - unless they are not listed in your mcdev config for retrieval.

--from (optional) You may choose to limit what methods get swapped out by defining the --from parameter in case you want to keep one but swap out the other. By default, --from is set to whatever you did not choose for --to. Example: --to key means that --from is auto-set to "name id" and hence ContentBlockByName and ContentBlockById will be replaced with ContentBlockByKey. Any other combination, of course, also works. Possible values: "name", "id", "key".

--skipRetrieve (optional) If you are absolutely sure you have the latest version of the code already downloaded or you want to override the server versions for some other reason then this option allows you to run rcb directly on your local code and skip the otherwise mandatory retrieve in the beginning. You will however still see that caching is conducted from the server, because Ids/ObjectIds are typically not saved in your downloaded JSONs.

--skipDeploy (optional) With this option you enable dry-run mode, allowing you to review the deployment package carefully. Keep in mind that changes are made to your files in the retrieve-folder and not in the deploy-folder. At the end of execution, rcb will acknowledge dry-run mode and provide you with a one-liner to execute the targeted deploy for changed files once you are ready.

--refresh (optional)

This is the same option already available for deploy. It only works if you did not use the --skipDeploy option. See deploy docs for more details.

Example:

mcdev rcb --bu MyProject/DEV --to key
mcdev rcb --bu MyProject/DEV --to key -m senderProfile
mcdev rcb --bu MyProject/DEV --to name -m journey --skipDeploy
mcdev rcb --bu * --to id -m triggeredSend -m script -m asset 
mcdev rcb --bu * --to key --from name -m asset --refresh
mcdev rcb --bu * --to key -m "asset:key1" --refresh
mcdev rcb --bu MyProject/DEV --to key automation --skipRetrieve --skipDeploy
mcdev rcb --bu MyProject/* --to key journey --skipRetrieve