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. Auth piggybacks
on the OWA browser session via owa-piggy
- separate package, separate token store, never imported.
owa-tools is the M365 read/write surface in the
hugr memory suite, alongside
YAAMS (Tier 1 raw), cognitive-ledger (Tier 2 curated), and owa-piggy
(auth broker). The suite gives you one install (brew install damsleth/tap/hugr), one verb surface (hugr mail ..., hugr calendar ...), and one CLI contract (output classes, exit codes,
JSON envelopes - see
hugr/CONVENTIONS.md).
The eight owa-* binaries continue to work standalone.
Homebrew (recommended):
brew install damsleth/tap/owa-piggy damsleth/tap/owa-toolsPyPI:
pipx install owa-piggy && pipx install owa-toolsEither path lands eight binaries on your PATH (owa, owa-cal, owa-mail,
owa-graph, owa-doctor, owa-people, owa-sched, owa-drive) 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 search "ola nordmann" # directory 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.
| 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-drive |
OneDrive CRUD plus binary up/download. |
owa-doctor |
Health check across the suite, all profiles, all audiences. |
owa |
Umbrella discovery binary: owa list, owa schema, owa doctor, owa version. |
Each tool delegates auth to owa-piggy and inherits its profile model. Pin a
profile for a tool, switch per call, or set it via env:
owa-cal --profile crayon events --pretty # one call
OWA_PROFILE=crayon owa-cal events --pretty # one shell session
owa-cal config --profile crayon # persistent for owa-calSee 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, 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
- 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.