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
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
owa-cal config --profile acme # persistent for owa-cal
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.
1 maintainer
Metadata
1 maintainer
Release files for owa-tools 1.9.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 | |
|---|---|---|---|
| owa_tools-1.9.0.tar.gz | 335.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| owa_tools-1.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 721.8 kB
Release files / owa_tools-1.9.0.tar.gz
| Download URL | owa_tools-1.9.0.tar.gz |
|---|---|
| Size | 335.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b17ca4791c936e383577e86cf3e44ba6e3d6753d85949704418b1b60eeb6885
|
|
BLAKE2b-256 checksum How to use checksums |
9b19ec568a97961daf6f3e4f6aed61184a8e9a237fed5721d80ab7478d38b15a
|
| 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.9.0-py3-none-any.whl
| Download URL | owa_tools-1.9.0-py3-none-any.whl |
|---|---|
| Size | 386.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ed774dc7d35c569a6189b614bc392e2ca5a0e9340cf89b4aae1bab19a0471167
|
|
BLAKE2b-256 checksum How to use checksums |
2594fbc29bc7171fa5fd41b2771412bc5c366b4e2dbf11ab3c19b4f7e2e2c89f
|
| 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}
|
