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. Auth piggybacks on the OWA browser session via owa-piggy

• separate package, separate token store, 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-piggy damsleth/tap/owa-tools

PyPI:

pipx install owa-piggy && pipx install owa-tools

Either path lands fourteen 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) 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 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.

This repo is CLI-only. For interactive TUI frontends (curses agenda browser, mail reader, Graph explorer), see owa-tui.

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-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 crayon --profile brkh messages --unread   # both inboxes, merged

See docs/profile-model.md for the full precedence rules.

• JSON on stdout by default. --pretty is the human opt-in.
• --agent wraps output for automation tooling; --err-json emits structured stderr.
• owa schema aggregates 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 boundaries
• docs/agent-integration.md - schema discovery, --agent, --err-json
• docs/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 tests
• docs/testing.md - test layers, coverage gates, data policy
• docs/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.