30-second answer

setup sets the machine up for you. In a terminal it installs what is missing, asks for your SharePoint address, obtains the application registration, and writes the target down once so that nothing is retyped afterwards.

PowerShell
m365-governance setup

From an empty machine to a report is three commands: setup, then connect, then run. You do not need to know what Entra ID, PnP.PowerShell or an application registration is.

What it does, in order

  1. It checks this machine, with the same checks as doctor, and stops with exit 2 if the environment is not sound.
  2. It installs or updates PowerShell 7 and PnP.PowerShell to their latest stable release, after asking. PnP.PowerShell is installed for you only, so no administrator is needed for it. On macOS PowerShell comes from Homebrew and on Windows from winget; on Linux setup names Microsoft's installation page, because the command differs by distribution.
  3. It asks for your SharePoint address: contoso, or any address on https://contoso.sharepoint.com. It derives the admin centre, the root site and the tenant's contoso.onmicrosoft.com domain from it.
  4. It obtains the application registration. Every connection needs one, and PnP.PowerShell has shipped no application of its own since 2.12.0. One registration serves the whole organisation. setup asks which case is yours:
    • you are an administrator: it registers the application, after you agree. A browser opens; you sign in and consent;
    • it already exists: you enter its id;
    • you are not an administrator: it writes m365-governance-admin-request.txt, which tells an administrator what to run and why. When they send the id back, run setup --client-id <id>. If you choose to register and the directory refuses because you lack the right, setup writes the same request.
  5. It writes m365-governance.toml and offers to run connect straight away.

The one write

Registering the application is the only write this engine makes to a tenant. It happens only in setup, only when you agree, and only under your own sign-in in a browser. Collection, evaluation and every other command still have no write path under any flag, and the engine stores no token or secret.

It asks for two permissions and nothing more:

  • SharePoint AllSites.FullControl, delegated. The collectors call only PnP Get- cmdlets, but SharePoint answers its permission and tenant-setting reads only under AllSites.FullControl, and refuses them under AllSites.Read.
  • Microsoft Graph User.Read, to sign in.

PnP's own default would also ask for Group.ReadWrite.All, User.ReadWrite.All and TermStore.ReadWrite.All, which nothing here uses. If you register the application yourself, in PowerShell 7 with PnP.PowerShell, use the same single line setup uses:

PowerShell
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "M365 Governance" -Tenant <your-tenant>.onmicrosoft.com -SharePointDelegatePermissions AllSites.FullControl -GraphDelegatePermissions User.Read

The project file

TOML
[target]
tenant_url = "https://contoso-admin.sharepoint.com"
site_url = "https://contoso.sharepoint.com"

[identity]
client_id = "…"

Every later command reads it, and says which file it read. A value arriving from a file nobody knew about would be the ambient configuration this exists instead of.

No secret belongs in that file. It is committed, copied into tickets and pasted into chats. A certificate password is named there by the environment variable that holds it, never by its value. A key that names a credential is refused rather than ignored, because ignoring it would leave the password in the file while the run carried on looking correct.

Without a terminal

In a pipeline nothing is asked and nothing is agreed. setup prints the report and the registration command, writes nothing, and exits 0, unless a flag says yes in advance:

PowerShell
m365-governance setup --install --register --tenant-url https://contoso-admin.sharepoint.com

Options

--client-id is the id of an existing registration. With it, setup writes the project file and asks for nothing else.

--tenant-url is the admin centre, https://<tenant>-admin.sharepoint.com. --site-url is one site. A project file needs at least one of them, because a file with no target names nothing to assess. In a terminal, setup asks for the address instead.

--install installs or updates PowerShell 7 and PnP.PowerShell without asking. --register registers the application without asking; it still needs an administrator, who signs in and consents in a browser. --application-name is what the registration is called, M365 Governance by default. --device-login registers with a device code, for hosts with no browser.

--tenant-id, --certificate-path and --certificate-password-env describe an application that signs in with a certificate instead of a person, for runs nobody attends. A person running it interactively needs only the id.

--out is where the file is written, m365-governance.toml here by default. --force replaces an existing one. Without it, setup refuses to overwrite a target somebody chose, because that would repoint every later run.

Exit codes

0 the machine is set up: the project file was written, the request for an administrator was written, or there was no terminal and setup said what to do. 1 the registration was attempted and failed for a reason other than missing rights. 2 refused: the environment is not sound, PowerShell is not ready, an input cannot be used, there is no address, a registration with that name already exists, or the file exists and --force was not given.

What it does not establish

That anybody can read anything with the registration. setup prepares a machine and obtains an identity. Whether that identity can reach the tenant, and whether it is allowed to read what the rules need, is connect, and it is a separate question on purpose.