Minimal Path to Awesome

The shortest way to prepare your local copy of the project for development and testing.

Install prerequisites

Before you start contributing to this project, you will need Node.js@18 and npm@9 installed.

Get the local version of the CLI

1. Fork this repository
2. Clone your fork to your local machine
3. In the root of the project, run the following commands in your command line:
   1. npm i: restore all dependencies of the project
   2. npm run build: build the entire project
   3. npm link: create a link/reference to your local project. This allows you to reference your locally installed CLI instead of the npm-hosted package.

If you installed the CLI globally using the npm i -g @pnp/cli-microsoft365 command, we recommend that you uninstall it first, before running npm link

That's it! If you now run m365 version you will see that you are now using the beta version of CLI for Microsoft 365 in your shell!

Setting up your IDE

It doesn't really matter which IDE you are using. We recommend using Visual Studio Code. When using VS Code, the following extensions will come in handy:

Extension	Why is it useful?
Mocha Test Explorer	This extension will help you when writing tests. It is capable of running individual tests and debugging. You will also get a nice overview of all tests within the project.
ESLint	We use ESLint to monitor consistency within the project. By installing this extension, you are notified of problems while writing code.

Npm scripts

CLI for Microsoft 365 comes with a set of commands that you will need during development.

Command	Description
npm run build	Builds the entire project.
npm run watch	Builds the entire project first. After this, a watcher will make sure that every time a file is saved, an incremental build is triggered. This means that not the entire project is rebuilt but only the changed files. You typically use this command while developing.
npm run clean	Clean the output directory. All built files will be deleted.
npm run test	Run all tests, check all ESLint rules, ... This is a combination of npm run test:cov and npm run lint. This is what happens in our GitHub workflows when creating a PR.
npm run test:cov	Run all tests and create a coverage report.
npm run test:test	Run all tests.
npm run lint	Run all ESLint rules.

Documentation

CLI for Microsoft 365 uses MkDocs to publish documentation pages. For simplicity, we recommend using the MkDocs Material Docker container which contains all dependencies installed.

Preview docs using the Docker container

If you're using Visual Studio Code and have the Docker extension installed, you can run preview the docs using the container either by executing the Run docs container task, or if you have pulled the image previously, from the Images pane by running the MkDocs container interactively. This article explains working with Docker containers using VSCode in more detail.

Alternatively, you can run the container in the command-line:

• on macOS:
  • run cd ./docs to change the directory to where the docs are stored
  • run docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:8.3.6 to start the local web server with MkDocs and view the documentation in the web browser
• on Windows:
  • run docker run --rm -it -p 8000:8000 -v c:/projects/cli-microsoft365/docs:/docs squidfunk/mkdocs-material:8.3.6 to start the local web server with MkDocs and view the documentation in the web browser

Preview docs using MkDocs installed on your machine.

If you want, you can also install MkDocs on your machine. See more information about installing MkDocs on your operating system at http://www.mkdocs.org/#installation.

CLI for Microsoft 365 documentation currently uses mkdocs-material theme v8.3.6. See more information about installing mkdocs-material on your operating system at https://squidfunk.github.io/mkdocs-material.

In order to run documentation locally, you can install MkDocs with pip (the Python package manager) then install the appropriate mkdocs-material version:

pip install mkdocs mkdocs-material==8.3.6 pymdown-extensions==9.5 pygments==2.12

Once you have MkDocs installed on your machine, in the command line:

run cd ./docs to change the directory to where the docs are stored run mkdocs serve to start the local web server with MkDocs and view the documentation in the web browser