owa-tools 0.5.0

Monorepo workspace for owa-piggy consumer CLIs

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.

Suite

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 nine owa-* binaries continue to work standalone.

Install

Homebrew (recommended):

brew install damsleth/tap/owa-piggy damsleth/tap/owa-tools

PyPI:

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

Either path lands nine binaries on your PATH (owa, owa-cal, owa-mail, owa-graph, owa-doctor, owa-people, owa-sched, owa-drive, owa-todo) 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 [e-mail]

# 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 [e-mail] --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-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	Umbrella: suite meta (owa list, owa schema, owa version, owa --doctor) plus owa <tool> ... pass-through dispatch (e.g. owa cal events).

Multi-account / profiles

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

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

For agents and automation

• 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

• 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

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

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.