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.
Homebrew (recommended):
brew install damsleth/tap/owa-toolsPyPI:
pipx install --include-deps owa-toolsEither 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.
# 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 todayEvery 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.
| 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.
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-calRepeat --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, mergedSee docs/profile-model.md for the full precedence
rules.
- 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/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
- 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
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.
MIT.