Hotmail CLI
A small read-only CLI for Hotmail and Outlook.com mailboxes. It uses Microsoft Graph to search messages and download file attachments from your mailbox.
中文文档: README.zh-CN.md
Why Use This
- Works with personal Microsoft accounts such as Hotmail and Outlook.com.
- Uses Microsoft device code login, so the CLI never sees your password.
- Requests only
Mail.Read. - Downloads attachments from matching messages.
- Stores the OAuth token locally with
0600file permissions.
This tool is intentionally narrow. It does not send email, delete messages, mark messages, or manage calendars.
Installation
uvx hotmail-cli --help
Or install it into an environment:
uv tool install hotmail-cli
hotmail --help
Microsoft App Setup
You need your own Microsoft Entra app registration. This is free and lets Microsoft show you exactly what the CLI is allowed to access.
- Open the Microsoft Entra admin center.
- Go to App registrations -> New registration.
- Name it
hotmail-clior any name you prefer. - For Supported account types, choose Personal Microsoft accounts only for Hotmail/Outlook.com.
- Leave Redirect URI empty.
- Create the app.
- Open Authentication -> Settings.
- Enable Allow public client flows and save.
- Copy the Application (client) ID.
Sign In
export HOTMAIL_CLIENT_ID="your Microsoft app client id"
hotmail auth
The command prints a URL and code. Open the URL in your browser, enter the code, sign in to Microsoft, and approve the requested Mail.Read access.
The token cache is saved to:
~/.hotmail-cli/token.json
You can also pass the client id directly:
hotmail --client-id "your Microsoft app client id" auth
Search Messages
Search by subject:
hotmail search --subject "statement" --top 10
Search by subject, sender, and date range:
hotmail search \
--subject "invoice" \
--sender "billing@example.com" \
--since 2026-06-01 \
--until 2026-06-27 \
--top 10
The output is Microsoft Graph message JSON. Each message includes an id that can be used with fetch and attachments.
Microsoft Graph message $search cannot be reliably combined with $filter or $orderby, so Hotmail CLI searches by subject server-side first, then applies sender and date filters locally.
Fetch One Message
hotmail fetch MESSAGE_ID
Download Attachments
hotmail attachments MESSAGE_ID --output-dir downloads
Only Microsoft Graph fileAttachment items are saved. Inline items and reference attachments are ignored.
Local Development
uv sync
uv run pytest
uv run hotmail --help
Build the package:
uv build
Security Notes
- Do not commit
~/.hotmail-cli/token.json. - Do not share message IDs or downloaded attachments publicly.
- Revoke access anytime from your Microsoft account security page or from the app registration.
License
MIT
Metadata
Release files for hotmail-cli 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hotmail_cli-0.1.1.tar.gz | 11.3 kB | Without provenance | Details for hotmail_cli-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hotmail_cli-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for hotmail_cli-0.1.1-py3-none-any.whl |
Total release size: 19.5 kB
Release files / hotmail_cli-0.1.1.tar.gz
| Download URL | hotmail_cli-0.1.1.tar.gz |
|---|---|
| Size | 11.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1dfefde76a50ef5f0296199d229561062fe262a529137c8b24600b4aa3f2b462
|
|
BLAKE2b-256 checksum How to use checksums |
305848f151ab8f5a82eb334c88a4aaff1ea3581134a74e113685cb44cc4cc393
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / hotmail_cli-0.1.1-py3-none-any.whl
| Download URL | hotmail_cli-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e7b9caab5be9e0e2995d17262f55145eaa1981964f0b18c8c7e169bf265ca514
|
|
BLAKE2b-256 checksum How to use checksums |
d2169a98cb36f498aa7423bb6b52debe3da44a4350bb5b7eeef0fbb60bce211a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.25 {"installer":{"name":"uv","version":"0.11.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for hotmail-cli 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.