Metadata-Version: 2.4
Name: owa-tools
Version: 0.1.1
Summary: Monorepo workspace for owa-piggy consumer CLIs
Author: Carl Joakim Damsleth
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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](https://img.shields.io/pypi/v/owa-tools.svg)](https://pypi.org/project/owa-tools/)
[![GitHub release](https://img.shields.io/github/v/release/damsleth/owa-tools.svg)](https://github.com/damsleth/owa-tools/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

No Azure AD app registration. No third-party runtime dependencies. Auth piggybacks
on the OWA browser session via [`owa-piggy`](https://github.com/damsleth/owa-piggy)
- separate package, separate token store, never imported.

## Install

Homebrew (recommended):

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

PyPI:

```bash
pipx install owa-piggy && pipx install owa-tools
```

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

## Quickstart

```bash
# 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 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.

## 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` | Umbrella discovery binary: `owa list`, `owa schema`, `owa doctor`, `owa version`. |

## 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:

```bash
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`](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`](docs/security.md) - token, redaction, and live-test boundaries
- [`docs/agent-integration.md`](docs/agent-integration.md) - schema discovery, `--agent`, `--err-json`
- [`docs/profile-model.md`](docs/profile-model.md) - profiles and audiences
- Per-tool: [`cal`](docs/cal.md) | [`mail`](docs/mail.md) | [`graph`](docs/graph.md) | [`doctor`](docs/doctor.md) | [`people`](docs/people.md) | [`sched`](docs/sched.md) | [`drive`](docs/drive.md)

## 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`](CHANGELOG.md)

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, tests, coverage gates,
commit conventions, and code style. The release flow lives in
[`RELEASING.md`](RELEASING.md), and architecture/agent guidance lives in
[`AGENTS.md`](AGENTS.md).

## License

MIT.
