v6 Upgrade Guidance¶
The v6 of CLI for Microsoft 365 introduces several breaking changes. To help you upgrade to the latest version of CLI for Microsoft 365, we've listed those changes along with any actions you may need to take.
Consolidated SharePoint Online site commands¶
In CLI for Microsoft 365 we had several commands that were originally targeted at classic SharePoint sites. All functionality in these commands has been merged with the regular SharePoint site commands and deprecated as a result. They have therefore been removed in v6. The commands that were removed are:
| Command | Merged with |
|---|---|
spo site classic add |
spo site add |
spo site classic list |
spo site list |
spo site classic set |
spo site set |
To fix a resulting issue with the spo site list command, the default value of the type option of that command has been removed.
What action do I need to take?¶
Replace references to spo site classic * commands, with the respective spo site * command. The options have not changed and the output of the commands has not changed as well. After updating the references test your scripts as there might be slight differences in how the commands behave.
Removed the executeWithLimitedPermission option in the spo list list command¶
In version 5 of the CLI for Microsoft 365, the spo list list command could only be executed with site owner permissions. To update this without introducing a breaking change, we temporarily added the --executeWithLimitedPermission option to be able to execute it as a site visitor or member as well. In v6 we removed this option while changing the command in such a way that you do not need to be a site owner anymore.
What action do I need to take?¶
Remove the references to the executeWithLimitedPermission option in your scripts. Verify that your scripts work as intended with the new data structure returned by the spo list list command.
Removed deprecated aliases¶
We removed several aliases to align commands with our naming convention. The following aliases were removed:
| Alias | Command | Reason |
|---|---|---|
aad app delete |
aad app remove | Removed to align with the naming convention. |
aad app role delete |
aad app role remove | Removed to align with the naming convention. |
aad o365group restore |
aad o365group recyclebinitem restore | Renamed to better match intention and naming convention. |
outlook sendmail |
outlook mail send | Renamed to better match intention and naming convention. |
planner plan details get |
planner plan get | Functionality merged in a single get-command. |
planner task details get |
planner task get | Functionality merged in a single get-command. |
teams conversationmember add |
teams channel member add | Renamed to better match intention and naming convention. |
teams conversationmember list |
teams channel member list | Renamed to better match intention and naming convention. |
teams conversationmember remove |
teams channel member remove | Renamed to better match intention and naming convention. |
spo hubsite theme sync |
spo site hubsite theme sync | Renamed to better match intention and naming convention. |
spo hubsite connect |
spo site hubsite connect | Renamed to better match intention and naming convention. |
spo hubsite disconnect |
spo site hubsite disconnect | Renamed to better match intention and naming convention. |
What action do I need to take?¶
Replace any of the aliases mentioned above with the corresponding command name. The functionality of the command hasn't changed.
In planner commands, removed the deprecated planName option¶
In several planner commands we renamed the planName option to planTitle to align with the underlying API. Along with introducing the planTitle option, we deprecated the old planName option. In v6 of the CLI we removed the planName option. The following list of commands is affected by this change:
- planner bucket add
- planner bucket get
- planner bucket list
- planner bucket remove
- planner bucket set
- planner plan get
- planner task add
- planner task get
- planner task list
- planner task set
What action do I need to take?¶
Replace the reference to the --planName option with --planTitle.
Removed the deprecated autoOpenBrowserOnLogin configuration key¶
The CLI for Microsoft 365 contains commands that return a link that the user should copy and open in the browser. At first, this was only available in the login command. We introduced the autoOpenBrowserOnLogin configuration key was introduced to have the CLI automatically open the browser, so that you don't have to copy/paste the URL manually. As we introduced this functionality to other commands, we renamed this configuration key to autoOpenLinksInBrowser. In v6 of the CLI, we removed the deprecated autoOpenBrowserOnLogin key.
What action do I need to take?¶
If you have configured the autoOpenBrowserOnLogin key, you'll now need to configure the autoOpenLinksInBrowser key to keep the same behavior. You can do this by running the following script:
m365 cli config set --key autoOpenLinksInBrowser --value true
Updated spo file copy options¶
We updated the spo file copy command. The improved functionality support copying files larger than 2GB and specify the name for the copied file. To support these changes, we had to do several changes to the command's options. When you specify an URL for options webUrl, sourceUrl and targetUrl, make sure that you specify a decoded URL. Specifying an encoded URL will result in a File Not Found error. For example, /sites/IT/Shared%20Documents/Document.pdf will not work while /sites/IT/Shared Documents/Document.pdf will work just fine.
Because of this rework, we were able to add new options, but we also removed existing ones.
Removed options:
--deleteIfAlreadyExists--allowSchemaMismatch
New options:
| Option | Description |
|---|---|
--nameConflictBehavior [nameConflictBehavior] |
Behavior when a document with the same name is already present at the destination. Possible values: fail, replace, rename. Default is fail. |
--newName [newName] |
New name of the destination file. |
--bypassSharedLock |
This indicates whether a file with a share lock can still be copied. Use this option to copy a file that is locked. |
What action do I need to take?¶
Update your scripts with the following:
- Ensure all the URLs you provide are decoded.
- Remove the option
--allowSchemaMismatch. - Replace option
--deleteIfAlreadyExistswith--nameConflictBehavior replace.
In teams channel commands, changed short options¶
In the following commands we've changed some shorts:
The following shorts where changed:
- Where we used
-c, --id, we changed it to-i, --id. - Where we used
-i, --teamId, we changed it to--teamId.
What action do I need to take?¶
Update the reference to the short options in your scripts.
Updated teams app publish command output¶
In the past versions, teams app publish returned just the app ID of the published app, or nothing at all. This has been adjusted, now the command will return the entire result object.
v5 JSON command output:
"fbdfd207-83ee-45d8-9c98-5039a1a01207"
v6 JSON command output:
{
"id": "fbdfd207-83ee-45d8-9c98-5039a1a01207",
"externalId": "b5561ec9-8cab-4aa3-8aa2-d8d7172e4311",
"displayName": "Test App",
"distributionMethod": "organization"
}
What action do I need to take?¶
Update your scripts to read the id property of the command output.
Updated spo eventreceiver get command output¶
In the past versions, spo eventreceiver get returned an array with a single object. This has been adjusted, now the command will only return the object.
v5 JSON command output:
[
{
"ReceiverAssembly": "Microsoft.Office.Server.UserProfiles, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c",
"ReceiverClass": "Microsoft.Office.Server.UserProfiles.ContentFollowingWebEventReceiver",
"ReceiverId": "c5a6444a-9c7f-4a0d-9e29-fc6fe30e34ec",
"ReceiverName": "PnP Test Receiver",
"SequenceNumber": 10000,
"Synchronization": 2,
"EventType": 10204,
"ReceiverUrl": "https://northeurope1-0.pushnp.svc.ms/notifications?token=b4c0def2-a5ea-490a-bb85-c2e423b1384b"
}
]
v6 JSON command output:
{
"ReceiverAssembly": "Microsoft.Office.Server.UserProfiles, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c",
"ReceiverClass": "Microsoft.Office.Server.UserProfiles.ContentFollowingWebEventReceiver",
"ReceiverId": "c5a6444a-9c7f-4a0d-9e29-fc6fe30e34ec",
"ReceiverName": "PnP Test Receiver",
"SequenceNumber": 10000,
"Synchronization": 2,
"EventType": 10204,
"ReceiverUrl": "https://northeurope1-0.pushnp.svc.ms/notifications?token=b4c0def2-a5ea-490a-bb85-c2e423b1384b"
}
What action do I need to take?¶
Update your scripts to expect a single object instead of an array.
Updated spo group user <verb> commands¶
We've renamed the spo group user <verb> commands to spo group member <verb> to better cover all possible scenarios. In the near future we'll be adding support to add Azure AD Groups as group member. Using spo group member better fits the intended situation of adding either users or Azure AD groups.
As a side issue, we've also updated the response output of the spo group member list command in JSON output mode. This returned a member array within a parent value object. In the new situation, the command returns the array without the parent value object.
What action do I need to take?¶
Update your scripts to use the new member noun instead of user. If you are using the output of spo group member list in JSON output mode, update your scripts and remove the value object.
Removed short notation for option asAdmin in pp commands¶
We've decided to remove all short notations for option --asAdmin in pp commands. In previous versions, many commands had the notation -a, --asAdmin. This has been changed to --adAdmin, we removed the short notation to align it with our naming convention.
Affected commands:
- pp card clone
- pp card get
- pp card list
- pp card remove
- pp dataverse table get
- pp dataverse table list
- pp dataverse table remove
- pp environment get
- pp environment list
- pp solution get
- pp solution list
- pp solution remove
- pp solution publisher get
- pp solution publisher list
- pp solution publisher remove
What action do I need to take?¶
Update your scripts to use --asAdmin instead of -a.
Updated teams app list command¶
The logic to list the installed apps in a specified team is moved to a new command teams team app list. As a result, the command teams app list only displays the installed apps from the Microsoft Teams app catalog. The command teams app list does no longer contain the options all, teamId and teamName. In addition, there is a new option for this command that allows you to indicate which installed apps from the Microsoft Teams app catalog you want to list according to the distribution method.
What action do I need to take?¶
Update your scripts to use the teams app list command if you want to list the installed apps in the Microsoft Teams app catalog. If you want to list the installed apps in a specified team, use the teams team app list command instead.
Aligned options with naming convention¶
As we've been adding more commands to the CLI, we noticed that several commands were using inconsistent options names. Our naming convention states that options that refer to the last noun in the command, don't need that noun as a prefix. for example: the option --webUrl for m365 spo web list has been renamed to --url as the last noun is web. In version 6 of the CLI for Microsoft 365, we updated all these options to be consistent and make it easier for you to use the CLI.
We've updated the following commands and options:
What action do I need to take?¶
If you use any of the commands listed above, ensure that you use the new option names.