m365ctl

An admin CLI for Microsoft 365 — OneDrive, SharePoint, and Exchange Mail — built on Microsoft Graph.

Safe by default: dry-run, plan-file workflow, scope allow-lists, audit log, and undo on every mutation.

Table of contents

• Highlights
• Installation
• Quickstart
• Features
• Safety model
• Configuration
• Documentation
• Contributing
• License
• Disclaimer

Highlights

• Read-only by default. Mutating verbs require --confirm and are logged.
• Local catalog. DuckDB mirrors of files and mail enable offline queries.
• Plan / replay. Bulk operations produce reviewable plan files before execution.
• Undoable. Every mutation records before/after state for m365ctl undo.
• Scope guards. allow_drives / allow_mailboxes / deny_paths enforced on every call.
• App-only auth. Certificate-based auth against your Entra app registration.

Installation

Requires Python 3.11+. Install with uv:

# Standalone CLI (recommended for end users):
uv tool install m365ctl

# Or as a project dependency:
uv add m365ctl

# Or with pipx / pip:
pipx install m365ctl

This installs the m365ctl console script. Verify with m365ctl --help.

For local development from source:

git clone https://github.com/aren13/m365ctl
cd m365ctl
uv sync --all-extras
# The repo's bin/*.sh shims (./bin/od-auth, ./bin/mail-list, ...) are
# convenience aliases for `uv run m365ctl <domain> <verb>`.

Quickstart

1. Register an Entra app and grant Graph permissions — see docs/setup/azure-app-registration.md.

2. Generate a client certificate — see docs/setup/certificate-auth.md.

3. Configure the CLI:

   # Grab the template from the repo or copy from `m365ctl --help` output.
   curl -O https://raw.githubusercontent.com/aren13/m365ctl/main/config.toml.example
   mv config.toml.example config.toml
   # Edit config.toml: tenant id, app id, cert path, allow-lists.
   

4. Authenticate and verify:

   m365ctl od auth login
   m365ctl od auth whoami
   m365ctl mail whoami
   

Full walkthrough: docs/setup/first-run.md (≤ 20 minutes from install to whoami).

Features

OneDrive and SharePoint

Mail

Each verb supports --help. See docs/mail/convenience-commands.md for the convenience-verb reference.

Safety model

Configuration

config.toml controls auth, scopes, paths, and feature flags. Start from config.toml.example:

[auth]
tenant_id   = "..."
client_id   = "..."
cert_path   = "~/.m365ctl/cert.pem"

[scope]
allow_drives    = ["..."]
allow_mailboxes = ["user@example.com"]
deny_paths      = ["/Confidential"]

[mail]
schedule_send_enabled = false

Catalog files, plan files, and the audit log default to cache/, plans/, and logs/ under the project root — override per config.toml.

Documentation

Contributing

Issues and pull requests welcome. Before opening a PR, please read CONTRIBUTING.md and run the test suite:

uv run pytest
uv run ruff check .
uv run mypy src

License

Apache-2.0. See LICENSE.

Disclaimer

This is an independent open-source project. Not affiliated with, endorsed by, or supported by Microsoft. "Microsoft 365", "OneDrive", "SharePoint", and "Exchange" are trademarks of Microsoft Corporation.