The Office 365 CLI: a new administration paradigm

Since the latter end of 2018, a new way of managing Office 365 tenants has become available, the Common Line Interface (CLI). If you’re a Microsoft administrator or developer, you may have been habitually using PowerShell to complete your daily tasks and automation. But, if you want to work from different operating systems, you need to constantly switch between PowerShell and Bash, to Cmder, or whichever shell you use. The CLI is an attempt to manage Office 365 from any system you use, with the same tool and similar syntax.

CLI is a command line framework that accepts text input to execute operations in the operating system or any other kind of software that admits text instructions. The origins of CLI are rooted in the Unix systems from the 1960s, and it was extensively used in PC systems like MS-DOS and Apple DOS. Although today, most users never use a command-line interface, they are more popular for system administrators and developers because CLI enables you to access the systems in an efficient way and can automate almost any kind of process without the use of formal programming.

The CLI is an open standard developed by Microsoft and standardized by ISO (International Organization for Standardization) and ECMA (European Computer Manufacturers Association) in 2000. Microsoft has several products with a CLI such as Azure, DotNet Core, PowerApps and Office 365. The Office 365 CLI is approaching version 2.0 which will be released in August 2019, and, at the same time, reaching the necessary maturity to become the preferred shell in your toolbox. The project is open sourced as part of the Office Office Patterns and Practices (PnP) initiative but closely watched by Microsoft.

Installing the Office 365 CLI

The Office 365 CLI is offered only as a Node Package Manager (Npm) package. Npm is the software packager and installer of Node.js. To download and install the LTS version of Node.js (around 17mb) follow this link. After installation, open your command-line tool, PowerShell for example in Windows systems, and execute the command npm i -g @pnp/office365-cli to install the Office 365 CLI.

If you’re curious about the new functionality that is coming in the CLI and want to give it a try, you can install the beta version. Use the command npm i -g @pnp/office365-cli@next to install the beta version; to review the information about the latest beta, run the command npm view @pnp/office365-cli. For production, stay working with the official release.

To review the version installed, run the command o365 version, and check if the currently installed version is the latest not only for the CLI but for all npm packages installed, then use the command npm outdated -g. To update the currently installed version, use the command npm install -g @pnp/office365-cli@latest. Finally, if you want to uninstall the Office 365 CLI, run the command npm uninstall @pnp/office365-cli

Using the Office 365 CLI

You can call the Office 365 CLI using the new Microsoft Windows Terminal command-line tool (still in beta, but used for the examples in this article), PowerShell or any other modern command-line you want to use inside Windows, macOS or Linux.

Start the Office 365 CLI running the command office365, which starts the immersive CLI prompt, pointed out as o365 on the screen:

To exit the immersive CLI prompt, type exit, and you will return to the normal prompt.

Commands are grouped in six categories in the CLI:

Each group has its own set of commands, having the current 1.2 version 189 of them, for example, for SharePoint Online. To get the list of commands of a group, use help [group], for example, for SharePoint Online, help spo:

Repeating the operation, you can get the list of commands for each sub-command. For example, to get the list of commands (and sub-commands) for the SharePoint Site Collections, run help spo site:

Finally, if you call the help function on a command help spo site add, for example, you will get all information needed to use the command, such as syntax, options, examples and important remarks.

To be able to interact with SharePoint Online, you need to login first. Use the command spo login https://[tenant].sharepoint.com to start the interactive login process. CLI will respond with an URL and code that you need to use to login through a browser:

Use the code, user account and password to login in the required SharePoint site. If the login succeeds, the CLI prompt will return and you can start firing commands. Another way to login is by using the URL and credentials directly from the command-line, following the syntax:

spo login "https://[domain].sharepoint.com"
--authType password --userName "user@[domain].sharepoint.com"
--password "mypassword"

At any moment you can call the command spo status to see if you are still connected to SharePoint, the account used and the Site Collection for the context.

After being logged in, explore the commands that you need to use, write some scripts if necessary, and automate your requirements with the Office 365 CLI. For example, to create a new modern Teams Site Collection in SharePoint, use the spo site add command with the following parameters:

spo site add --type TeamSite --alias "ClITeamSite" --title "Test CLI" --url "https://[domain].sharepoint.com/sites/Test_CLI" --description "Site Collection created with CLI"

Remember that the account used needs to be a SharePoint administrator to be able to create Site Collections.

To enumerate the Site Collections in the SharePoint tenant, use the spo site list command. You need first to login in the administration site of the tenant, https://[domain]-admin.sharepoint.com, with a SharePoint administrators account, otherwise you’ll get an error. Using spo site list without other parameters, the command will return all Site Collections in the tenant; but you can filter it to get only the sites of one type TeamSite or CommunicationSite, or by a specified parameter, such as a part of the URL, or a combination of both. The following example enumerates all Site Collections of the Team Site type, where the URL contains CLI:

spo site list --type TeamSite --filter "Url -like 'cli'"

To log-out from SharePoint, just use the spo logout command.

Conclusions

The Office 365 CLI is becoming complete enough to be a useable tool for SharePoint Online administrators and developers. Although the number of commands is reaching an acceptable point, it still misses the versatility of PowerShell, where you can use not only the native commands created by Microsoft but also the PnP and SPO cmdlets, interact with the server using CSOM (Client Server Object Model), and even create your own cmdlets. Additionally, you need to learn a new syntax and commandos set. The big advantage is that, if you work with a mix of operating systems, you can reuse the same scripts everywhere.

If you’re looking for more effective ways of managing your Office 365, check out this technical review.