We’ve just published a new version of the CLI for Microsoft 365 with new commands for working with and managing Microsoft 365 tenants and SharePoint Framework projects on any platform.
Manage Microsoft 365 and SharePoint Framework projects on any platform
CLI for Microsoft 365 is a cross-platform CLI that allows you to manage various configuration settings of Microsoft 365 and SharePoint Framework projects no matter which operating system or shell you use.
While building solutions for Microsoft 365 expands beyond the Windows operating system, managing many of the platform settings is possible only through PowerShell on Windows. As more and more users work on non-Windows machines, it’s inconvenient for them to have to use a Windows virtual machine to configure their tenants. With the CLI for Microsoft 365, you can configure your tenant no matter which operating system you use. Additionally, using CLI for Microsoft 365, you can manage your SharePoint Framework projects.
New version of CLI for Microsoft 365 – v3.3
Following our monthly release cadence, we’ve released a new version of the CLI for Microsoft 365 with some new capabilities. Here are a few of the most noteworthy additions.
Changes
We’ve continued improving CLI building upon the changes we’ve introduced in the previous version.
Consistent and richer command help
In the previous version of CLI for Microsoft 365, we have removed the no longer maintained Vorpal package with code that we can maintain ourselves. A part of this migration, was consolidation of commands’ help.
In the past, each command implemented help in its code as well in a separate markdown file that we use to generate docs on the CLI’s website. This setup required our contributors to double the work and sometimes led to inconsistencies between the two help documents.
With help of Stefan Bauer, who provided us with the markshell package, we can now display command’s help in the terminal using the same markdown file as we do for generating docs on the website! Not only it saves us a lot of work maintaining two different help files, but also offers you a richer help output.
Separation of primary and secondary command output
In the past, when working with CLI for Microsoft 365, you might have noticed that all CLI’s output was sent to stdout. If you used CLI in verbose or debug mode, there wasn’t an easy way for you to separate the secondary information from the primary output of the command that you have ran.
Thanks to the recent refactoring in the core of the CLI that we have done recently, we were able to separate the primary output of each command you run from the auxiliary information it produces. Starting from this version, the primary output is written to stdout, while all secondary information is sent to stderr. With this, it’s up to you to decide how you want to handle the output.
With this change, you can keep detailed logging of all command execution in your scripts to a separate log file, while not needing to worry about extra parsing of the command output in your scripts.
Fixed output trimming in PowerShell
A while ago we have noticed, that in some cases, longer command output was trimmed when using CLI for Microsoft 365 in PowerShell.
It took us quite a while to figure it out, but we realized, that in some cases, console.log statement, which we use to write commands’ output to the terminal, is asynchronous. Because of this, sometimes, CLI would exit while not all of the output was yet printed in the terminal, leaving you with only a part of the data you requested.
With a small adjustment in this version, we’ve been able to make console.log be always synchronous, allowing you to rely on the output from CLI for Microsoft 365 when used in PowerShell.
Simplified managing Teams
When we introduced commands for managing Microsoft Teams in CLI for Microsoft 365, we were closely following the structure of the underlying API requiring you to specify the ID of the channel or team which you wanted to manage. As you can imagine, this isn’t very convenient as you’re unlikely to know these IDs by heart.
To simplify managing teams using CLI for Microsoft 365, we’ve been working on extending related commands to support not only objects’ IDs but also their names. In this version we have updated the teams channel list and teams channel get commands, and you can expend to see other commands being updated in the future as well.
New Commands
Manage Microsoft To Dos
Recently, Microsoft To Do APIs reached general availability on the v1.0 endpoint in Microsoft Graph. With that milestone, we have introduced a number of commands to help you manage Microsoft To Do tasks.
To add a new task in Microsoft To Do, execute:
m365 todo task add --title "New task" --listName "My task list"
To update a task, execute:
m365 todo task set --id "AAMkADU3Y2E0OTMxLTllYTQtNGFlZS1hZGM0LWI1NjZjY2FhM2RhMABGAAAAAADhr7P77n9xS6PdtDemRwpHBwCin1tvQMXzRKN1hQDz2S3VAAAXXsleAACin1tvQMXzRKN1hQDz2S3VAAAXXzr9AAA=" --title "Update doco" --listName "My task list"
To see which tasks you have, execute:
m365 todo task list --listName "My task list"
Finally, if you need to remove a task, execute:
m365 todo task remove --id "BBMkAGI3NDhlZmQzLWQxYjAtNGJjNy04NmYwLWQ0M2IzZTNlMDUwNAAuAAAAAACQ1l2jfH6VSZraktP8Z7auAQCbV93BagWITZhL3J6BMqhjAAD9pHIhBBB=" --listName "Tasks"
If you use Microsoft To Do, we’d love to hear from you, what you think of the commands we have in CLI for Microsoft 365 and what we could improve. For more information about the commands we currently have available for managing Microsoft To Do, see the documentation.
Generate file sharing information report
Being able to share files with others is key to successful collaboration. Unfortunately, as you share files over time, you can easily lose track of which files are shared with whom. To help you, we have introduced a command that generates file sharing information report for the specified file.
To get a file sharing information report, execute:
m365 spo file sharinginfo get --webUrl https://contoso.sharepoint.com/sites/project-x --url "/sites/M365CLI/Shared Documents/SharedFile.docx"
Combining this command with other commands in CLI for Microsoft 365, you could build a script that enumerates sites you own for files that have been shared and presents you with a complete report of how these files are shared with others in and outside of your organization.
Manage deleted SharePoint sites
When you delete a SharePoint site, by default it’s not removed permanently. Instead, it’s moved to the recycle bin, from which you can either restore it or, if you don’t need the site anymore, permanently remove it.
In this version we have introduced two commands to manage deleted SharePoint sites.
To restore a deleted SharePoint site from the recycle bin, execute:
m365 spo tenant recyclebinitem restore --url https://contoso.sharepoint.com/sites/team
To permanently delete a SharePoint site, execute:
m365 spo tenant recyclebinitem remove --url https://contoso.sharepoint.com/sites/team
For more information about managing deleted sites, see the documentation at aka.ms/cli-m365.
Cancel flow runs
Microsoft Power Automate offers organizations a great way to automate business processes and repeatable tasks. By building flows, you can automate tedious work and save precious time to spend on what truly matters.
As you start building more and more flows, you will likely need something to help you automate them. In this release, we have extended CLI’s support for managing flows with a command that allows you to cancel a specific flow run.
To get the list of flow runs, execute:
m365 flow run list --environment Default-d87a7535-dd31-4437-bfe1-95340acd55c5 --flow 5923cb07-ce1a-4a5c-ab81-257ce820109a
Then, to cancel the particular run, execute:
m365 flow run cancel --environment Default-d87a7535-dd31-4437-bfe1-95340acd55c5 --flow 5923cb07-ce1a-4a5c-ab81-257ce820109a --name 08586653536760200319026785874CU62
For more information about managing flows using CLI for Microsoft 365, see the documentation at aka.ms/cli-m365.
Update web part data and properties
Many organizations use SharePoint as the centerpiece of their communication and content management. With modern pages and SharePoint Framework web parts, they compose rich dashboards and landing pages providing employees with quick access to information.
In this version, we’ve introduced a command that allows you to update data and properties of a specific control on a modern SharePoint page. This is invaluable, if you need to update a number of pages quickly and consistently.
To update properties of a web part, execute:
m365 spo page control set --id 3ede60d3-dc2c-438b-b5bf-cc40bb2351e1 --webUrl https://contoso.sharepoint.com/sites/team-a --name home.aspx --webPartData '{"title":"New WP Title","properties": {"description": "New description"}}'
For more information about managing modern pages and their contents using CLI for Microsoft 365, see the documentation at aka.ms/cli-m365.
New script samples
CLI for Microsoft 365 is a great tool both for quick adjustments to the configuration of your Microsoft 365 tenant as well as automating more complex tasks. Because CLI for Microsoft 365 is cross-platform you can use it on any OS and in any shell. To help you get started using the CLI for Microsoft 365 for automation scenarios, we started gathering some sample scripts. Here are the latest additions to the collection.
Analyze User Profile Photos using Azure Computer Vision API
This script, contributed by Joseph Velliah, uses Azure Cognitive Service API and Microsoft 365 CLI to analyze user profile pictures and assess whether they meet the standards placed by the organization. It can be customized to ban content within an org channel or collaboration network where employees post pictures, memes, etc.
If you have any scripts that you use frequently, please share them with us so that we can learn more about the common automation scenarios.
Contributors
This release wouldn’t be possible without the help of (in alphabetical order) Stefan Bauer, Aakash Bhardwaj, Patrick Lamber, Sébastien Levert, Michaël Maillot, Waldek Mastykarz, Arjun U Menon, Abderahman Moujahid, Nanddeep Nachan, Albert-Jan Schot, Elio Struyf, Joseph Velliah and Rabia Williams. Thank you all for the time you chose to spend on the CLI for Microsoft 365 and your help to advance it!
Work in progress
Here are some things that we’re currently working on.
More commands, what else
Microsoft 365 is evolving and new capabilities are being released every day. With CLI for Microsoft 365, we aim to help you manage your tenant on any platform in a consistent way, no matter which part of Microsoft 365 you interact with. While we keep adding new commands to CLI for Microsoft 365 each release, we still barely scratched the surface with what’s possible in Microsoft 365. In the upcoming versions of the CLI for Microsoft, you can expect us to add more commands across the different workloads in Microsoft 365.
Friendlier commands
While there are now over 350 commands available to use in CLI for Microsoft 365 to help you manage your Microsoft 365 tenant, a lot of commands expect you to provide object ids to perform actions.
We understand that this is not as intuitive as being able to provide a the name of an object and the command work out what the required object ids for you based on the object name given.
We are actively creating new issues to address this, updating our commands to be more user friendly and provide a better user experience.
We’ll start to implement new name options on our Microsoft Teams commands and will start to appear in the next release.
Another thing that we’re working on in the context of simplification is allowing you to easily register applications in Azure AD. Creating Azure AD applications is a prerequisite in developing on Microsoft 365. We believe, that being able to do it with just one command would significantly improve the development process.
Quicker and easier developer onboarding
CLI for Microsoft 365 is a community project and it relies upon contributions from developers around the world to help add new commands and enhance existing commands in every release.
As part of our ongoing improvements to the project, we want to make the onboarding process of new developers to the project as quick and easy as possible.
We will be looking to release a Remote Development container, that will provide a one click approach for developers to configure a development environment with all dependencies and tools required to contribute to the project.
The release will also support use of GitHub Codespaces, enabling developers to spin up dedicated development environments in the cloud and contribute to the project using nothing but a web browser.
Run CLI for Microsoft 365 in a Docker container
The CLI for Microsoft 365 has been designed from the beginning to be platform agnostic, continuing on this theme we will be looking to publish a Docker image to the Docker Hub registry.
This will enable administrators and developer to run an isolated Linux container with the CLI for Microsoft 365 pre-installed and ready to use.
Script examples
In every release of the CLI for Microsoft 365, we introduce new commands for managing Microsoft 365. With 360 commands across the different Microsoft 365 services, the CLI for Microsoft 365 has become a powerful tool, not just for managing your tenant but also for automating your daily work.
We’d love to show you how you can use the CLI for Microsoft 365 to build automation scripts in PowerShell Core and Bash. If you have any scripts using SPO or PnP PowerShell that you use frequently, please share them with us so that we can learn more about the common automation scenarios.
ensure commands
Currently, CLI for Microsoft 365 has dedicated commands for retrieving, creating and updating resources. If you were to create a script that ensures a specific configuration, for each resource you’d need to see if it exists, create it if it doesn’t or update it if it does.
We’re thinking about simplifying this scenario by introducing commands with a new verb named ensure. For example, to ensure that a particular site collection exists, instead of executing a combination of spo site list/spo site get, spo site add and spo site set, you’d execute spo site ensure with the necessary parameters which would automatically verify if the particular site exists and matches your configuration. If the site doesn’t exist, it would create it. If it does, the command would check if the properties you specified match the retrieved site and update them if necessary.
We’ll start to implement this idea on the spo site commands. We’d love to hear from you if it’s something that you’d find helpful and what other objects we should take into account.
Try it today
Get the latest release of the CLI for Microsoft 365 from npm by executing in the command line:
npm i -g @pnp/cli-microsoft365
If you need more help getting started or want more details about the commands, the architecture or the project, go to aka.ms/cli-m365. If you see any room for improvement, please, don’t hesitate to reach out to us either on GitHub or twitter.
