Run CLI for Microsoft 365 in Docker

Microsoft 365 PnP Team

We are delighted to announce that CLI for Microsoft 365 Docker images are now available to download and use from the Docker Hub.

If this doesn’t mean a lot to you right now, then let me explain why we feel this is a big deal.

Docker enables us to bundle a pre-configured version of CLI for Microsoft 365 together with all its required dependencies into a publicly downloadable image, which you can then use to create an isolated environment on your local machine, called a container, where you can use the CLI for Microsoft 365 without cluttering your machine with dependencies, and all performed by executing just a single command.

Sounds great, right? So how do you get started?

Firstly, you will need to have Docker installed and running on your host machine, to do that, checkout the guides over in the Docker documentation, its free and can be installed on any operating system. Once you have Docker running on your machine, open up your command prompt of choice and run the below command.

docker run --rm -it m365pnp/cli-microsoft365:latest

This command will instruct the Docker engine running on your host machine to start a container using an image called m365pnp/cli-microsoft365, as the :latest tag is specified we are also telling the engine to get the image which contains the latest stable version of the CLI.

As the image won’t exist on your host machine yet, Docker will automatically download the image from the Docker Hub, where our images are publicly available, then start a new container which invoking an interactive terminal session inside the container, this is determined by the presence of the -it switch in the docker run command.

Terminal displaying a bash interactive terminal session inside a docker container using m365pnp/cli-microsoft365:latest image after being downloaded for the first time

By default, the interactive terminal that is opened is a bash shell, however if you prefer using PowerShell then thats fine, we have you covered as we also bundle PowerShell 7 as part of the image.

If you want to use PowerShell, simply add pwsh to the end of the docker run command and you will get a PowerShell session instead.

docker run --rm -it m365pnp/cli-microsoft365:latest pwsh

Terminal displaying a PowerShell interactive terminal session inside a docker container using m365pnp/cli-microsoft365:latest image

Now that you are at the interactive terminal, you can now invoke any CLI for Microsoft 365 command using the m365 prefix as it is already installed, to help you, we have even pre-configured tab command completion for you in both bash and PowerShell. Neat right.

Terminal displaying a PowerShell interactive terminal session inside a docker container using m365pnp/cli-microsoft365:latest image, the prompt is displaying command completion options for m365 command

When you are done with your session, just type exit and your interactive terminal will be closed and with that, the isolated container will also be stopped and removed, freeing up resources on your host machine, this is determined by the presence of the --rm switch in the docker run command.

Terminal displaying a PowerShell interactive terminal session inside a docker container using m365pnp/cli-microsoft365:latest image, the prompt is at the host machine level after exit has been executed inside the container

This doesn’t mean that the image you just downloaded has been removed as well, this remains on your machine, we just removed the container instance that was started, so when you run the docker run command again, this time you won’t need to download the image and just head straight for the interactive terminal.

As the container is removed after exiting the interactive terminal, everything stored in the container is removed, this includes any authentication information, therefore when you start a new container you will need to re-authenticate with Microsoft 365.

Checkout our guide for more details on how to use these images, including how to get the latest beta releases, update existing images, execute scripts stored on your local machine inside the running container and how to use your own Azure AD identity for connecting to Microsoft 365 from the running container.

We will be releasing new beta and stable versions as part of our regular release cadence, so you will be able to use the new version of the CLI for Microsoft 365 in Docker immediately after our release to npm.

For a list of available tags, checkout the m365pnp/cli-microsoft365 repository on Docker Hub for the latest images.

CLI for Microsoft 365 is associated with the Microsoft 365 Patterns and Practices (PnP) organisation, which is a virtual team consisting of Microsoft employees and community members focused on helping the community make the best use of Microsoft products.

Feedback usabilla icon