Skip to main content

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.

PyPI GitHub release License: MIT

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

No Homebrew? One line installs owa-tools and owa-piggy with uv (or pipx), asks whether to add owa-tui, and puts them on PATH:

curl -fsSL https://owa-piggy.dv.ms/install.sh | bash

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

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. --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

Maintainer reference:

Releases

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.

Metadata

Release files for owa-tools 1.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for owa-tools 1.10.0
File Size Uploaded Provenance Actions
owa_tools-1.10.0.tar.gz 330.9 kB Without provenance Details for owa_tools-1.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for owa-tools 1.10.0
File Interpreter ABI Platform Actions
owa_tools-1.10.0-py3-none-any.whl Python 3 none any Details for owa_tools-1.10.0-py3-none-any.whl

Total release size: 715.7 kB

Release files / owa_tools-1.10.0.tar.gz

Download URL owa_tools-1.10.0.tar.gz
Size 330.9 kB
Tags Source
SHA-256 checksum
How to use checksums
74952bb18804a2d2ed722ec6e14c254b52b5205834679a6b1457ab1055bbeed8
BLAKE2b-256 checksum
How to use checksums
b11b629755a78434df55b6fdbe9beaae17f21e39e276a9d92a5c8c7948cd976c
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.10.0-py3-none-any.whl

Download URL owa_tools-1.10.0-py3-none-any.whl
Size 384.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
40ed3bf9b39ba6fdc5da77176ed349b9d367bafb50f22bcfd1443b2bc497f846
BLAKE2b-256 checksum
How to use checksums
28e54411326301cc04caf29fe8ecd464f05f721c504a1b3c97862837974b175c
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}

Security for owa-tools 1.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page