owa-tools
Pipe-friendly CLI suite for Outlook and Microsoft 365. Calendar, mail, Graph, OneDrive, scheduling, people lookup, health checks - all from your terminal, all returning JSON by default.
No Azure AD app registration. No third-party runtime dependencies beyond the
auth broker. Auth piggybacks on the OWA browser session via
owa-piggy - separate package, separate
token store, installed as a dependency, never imported.
Every owa-* binary shares one CLI contract - the same output classes, exit
codes, and JSON envelopes - so they behave consistently and compose cleanly in
scripts and pipelines.
Install
Homebrew (recommended):
brew install damsleth/tap/owa-tools
PyPI:
pipx install --include-deps owa-tools
No Homebrew? One line installs owa-tools and owa-piggy with uv (or pipx), asks whether to add owa-tui, and puts them on PATH:
curl -fsSL https://owa-piggy.dv.ms/install.sh | bash
Either path lands twenty binaries on your PATH (owa, owa-cal, owa-mail,
owa-graph, owa-doctor, owa-people, owa-sched, owa-places, owa-drive, owa-todo,
owa-planner, owa-sites, owa-teams, owa-vids, owa-ado, owa-swodp, owa-halo,
owa-kova, owa-gmail, owa-gdrive) plus the
owa-piggy auth broker.
Quickstart
# 1. One-time auth setup (opens Edge, signs you in, captures a refresh token)
owa-piggy setup --profile work --email you@yourcompany.com
# 2. Verify everything's healthy
owa doctor
# 3. Try it
owa-cal events --pretty # today's calendar
owa-mail folders # mail folders
owa-graph me whoami # who am I
owa-drive ls # OneDrive root
owa-people find "ola nordmann" # people lookup
owa-sched availability --who you@example.com --date today
Every binary supports --help and <binary> help for the full command surface.
JSON on stdout, logs on stderr, --pretty when you want a human-readable table.
The owa umbrella also dispatches to any tool, so owa cal events --pretty
is equivalent to owa-cal events --pretty — everything after the tool name is
passed straight through.
What's in the box
| CLI | What it does |
|---|---|
owa-cal |
Calendar CRUD over Outlook REST. Events, categories, recurrence. |
owa-mail |
Mail CRUD: messages, send, reply, forward, folders. |
owa-graph |
Microsoft Graph CLI: verb-first plus 14 resource shortcut groups. |
owa-people |
People, directory, and contacts via Graph. |
owa-sched |
Free/busy and slot finding for one or many attendees. |
owa-places |
Best-effort Outlook room/location lookup via SchedulingB2. |
owa-drive |
OneDrive CRUD plus binary up/download. |
owa-doctor |
Health check across the suite, all profiles, all audiences. |
owa-todo |
Microsoft To Do tasks: lists, create, update, complete, delete. |
owa-planner |
Microsoft Planner (read-only): plans, buckets, tasks, task detail. |
owa-sites |
SharePoint (read-only) via SharePoint REST: site, lists, items, files, search. |
owa-teams |
Microsoft Teams (read-only): joined teams, channels, chats, and channel/chat messages (threaded). |
owa-vids |
Download Teams / OneDrive meeting-recap DASH streams and mux to MP4 (token-only, via ffmpeg). |
owa-ado |
Azure DevOps: work items (WIQL), boards/sprints, repos & pull requests, pipelines & runs, library variable groups, task/deployment groups, environments & releases. Auth via owa-piggy --audience devops. |
owa-swodp |
SWODP ServiceNow timesheets: Edge sidecar auth (the owa-piggy profile with swodp), reads, validated Pending-only writes, prod/UAT isolation. |
owa-halo |
HaloITSM (read-only): ticket, status, metadata, actions/comments, attachments and inline screenshots. Auth via the halo service on an owa-piggy profile (clients add halo=<url>). |
owa-gmail |
Gmail (read-only): list/search messages, show one, raw .eml, attachments, labels. Auth via an owa-piggy Google profile (setup --google). |
owa-gdrive |
Google Drive (read-only): list/search, metadata, download; Docs/Sheets/Slides exported to text/csv. Auth via an owa-piggy Google profile. |
owa-kova |
Kova (Red Cross) schedule (read-only): your duties and the unit's open duties. Session via the kova service on an owa-piggy profile (clients add kova). |
owa |
Umbrella: suite meta (owa list, owa schema, owa version, owa --doctor) plus owa <tool> ... pass-through dispatch (e.g. owa cal events). |
This repo is CLI-only. For interactive TUI frontends (curses agenda browser,
mail reader, Graph explorer), see
owa-tui.
Multi-account / profiles
Microsoft 365 and Azure DevOps tools delegate auth to owa-piggy and inherit
its profile model. owa-swodp is the exception: it reads ServiceNow cookies
from an Edge sidecar (prod: the owa-piggy profile with swodp), selected with
--instance prod|uat. For broker-backed tools, pin a
profile for a tool, switch per call, or set it via env:
owa-cal --profile acme events --pretty # one call
OWA_PROFILE=acme owa-cal events --pretty # one shell session
Repeat --profile to fan out across profiles in one call - results are merged
keyed by profile (exit 0 all ok, 2 mixed, 1 all failed):
owa-mail --profile acme --profile brkh messages --unread # both inboxes, merged
See docs/profile-model.md for the full precedence
rules.
For agents and automation
- JSON on stdout by default.
--prettyis the human opt-in. --agentwraps output for automation tooling;--err-jsonemits structured stderr.owa schemaaggregates per-tool schemas for discovery.- Exit code taxonomy is shared across the suite (
docs/agent-integration.md).
Docs
docs/security.md- token, redaction, threat model, and live-test boundariesdocs/agent-integration.md- schema discovery,--agent,--err-jsondocs/profile-model.md- profiles and audiences- Per-tool:
cal|mail|graph|doctor|people|sched|drive|todo|planner|sites|teams|vids
Maintainer reference:
docs/architecture.md- low-entropy architecture, shared contracts, maintainability testsdocs/testing.md- test layers, coverage gates, data policydocs/new-tool-onboarding.md- process for adding a companion CLI
Releases
- PyPI: https://pypi.org/project/owa-tools/
- GitHub Releases: https://github.com/damsleth/owa-tools/releases
- Homebrew tap: https://github.com/damsleth/homebrew-tap
- Changelog:
CHANGELOG.md
Contributing
See CONTRIBUTING.md for setup, tests, coverage gates,
commit conventions, and code style. The release flow lives in
RELEASING.md, and architecture/agent guidance lives in
AGENTS.md.
License
MIT.
Metadata
Release files for owa-tools 1.10.0
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 |
|---|---|---|---|---|
| owa_tools-1.10.0.tar.gz | 330.9 kB | Without provenance | Details for owa_tools-1.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| owa_tools-1.10.0-py3-none-any.whl | Python 3 | none | any | Details for owa_tools-1.10.0-py3-none-any.whl |
Total release size: 715.7 kB
Release files / owa_tools-1.10.0.tar.gz
| Download URL | owa_tools-1.10.0.tar.gz |
|---|---|
| Size | 330.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
74952bb18804a2d2ed722ec6e14c254b52b5205834679a6b1457ab1055bbeed8
|
|
BLAKE2b-256 checksum How to use checksums |
b11b629755a78434df55b6fdbe9beaae17f21e39e276a9d92a5c8c7948cd976c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / owa_tools-1.10.0-py3-none-any.whl
| Download URL | owa_tools-1.10.0-py3-none-any.whl |
|---|---|
| Size | 384.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
40ed3bf9b39ba6fdc5da77176ed349b9d367bafb50f22bcfd1443b2bc497f846
|
|
BLAKE2b-256 checksum How to use checksums |
28e54411326301cc04caf29fe8ecd464f05f721c504a1b3c97862837974b175c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for owa-tools 1.10.0
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.