The first Outlook calendar CLI built for AI agents on personal Microsoft 365 accounts — with offline conflict detection, free-time math, and recurring-drift insights no Graph endpoint can give you.
Drives your personal Microsoft 365 calendar from scripts and agents. OAuth 2.0 device-code flow against the /common tenant, so personal MSAs work alongside work accounts. A local SQLite store synced through events/delta unlocks conflicts, freetime, review, pending, recurring-drift, and prep — workflows no other Outlook CLI exposes because they require persisted state.
Authentication
Authentication uses OAuth 2.0 device-code flow against https://login.microsoftonline.com/common. Run outlook-calendar-pp-cli auth login --device-code once; visit the displayed URL on any device, enter the code, and you're done. Tokens (access + refresh) are cached at ~/.config/outlook-calendar-pp-cli/config.toml (mode 0600). Personal Microsoft accounts (Outlook.com, Hotmail, Live, MSA) are first-class and tested.
By default this CLI uses the Microsoft-published Graph PowerShell client id (14d82eec-204b-4c2f-b7e8-296a70dab67e), which is configured for AzureADandPersonalMicrosoftAccount and works with personal accounts out of the box. For production use, register your own Azure app (Public client; Accounts in any organizational directory and personal Microsoft accounts; scopes Calendars.ReadWrite User.Read offline_access) and pass it via --client-id or the OUTLOOK_CALENDAR_CLIENT_ID env var.
Reachability check: outlook-calendar-pp-cli doctor --json confirms the access token is valid and /me is reachable. To force-rotate the access token use outlook-calendar-pp-cli auth refresh.
Quick Start
# One-time interactive login; subsequent commands are non-interactive and refresh-token driven.
outlook-calendar-pp-cli auth login --device-code
# Pull events into the local SQLite store via /me/events/delta. Run periodically to keep transcendence features fresh.
outlook-calendar-pp-cli delta events
# Today's week as JSON, ready for an agent.
outlook-calendar-pp-cli events range --from today --to +7d --json
# Find any double-bookings across every calendar you own.
outlook-calendar-pp-cli conflicts --from today --to +14d --json
# Hour-long open slots in working hours over the next week.
outlook-calendar-pp-cli freetime --duration 60m --within 'Mon-Fri 9-17' --next 7d --json
# Agent-shaped dossier for the next four hours of meetings.
outlook-calendar-pp-cli prep --next 4h --json --select subject,location,attendees,body_preview
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
conflicts — Find overlapping events across all your Outlook calendars in one pass — the double-bookings Outlook's own UI never shows.
When the agent needs to know whether a proposed time blocks the user, this is the source of truth across every calendar the user owns.
outlook-calendar-pp-cli conflicts --from today --to +7d --json --select pair_id,a.subject,b.subject,overlap_minutes
-
freetime — Compute N-minute gaps in your working hours over the next K days, honoring all calendars and optional OOF/tentative exclusion.
When the agent needs to propose a meeting time, this gives a deterministic answer that respects the user's actual working hours.
outlook-calendar-pp-cli freetime --duration 60m --within 'Mon-Fri 9-17' --next 7d --exclude-oof --json
-
review — Diff against the last delta-sync snapshot: what was added, rescheduled, cancelled, or had its RSVP change.
Lets the agent answer "what changed since I last looked?" without scanning the whole week.
outlook-calendar-pp-cli review --since last-sync --json
-
pending — List events whose RSVP is still pending and whose start time is in the future, ordered by start.
Agent task: "what invites do I still need to answer?" — answered in one query.
outlook-calendar-pp-cli pending --json
-
recurring-drift — For each recurring-series master, list instances whose start/end/subject/location diverged from the master pattern.
Catches the silent organizer-side reschedules that cause people to join Teams calls at the wrong hour.
outlook-calendar-pp-cli recurring-drift --json
-
with — How often have I met with this person, and when did I see them last? Counts and recent N events from local store.
Agent task: "how often do I meet with X?" without reading the whole calendar.
outlook-calendar-pp-cli with alice@example.com --since 90d --json
-
tz-audit — Surface events whose start time-zone differs from the calendar's default or from their own end-time TZ — likely-broken displays on other devices.
Agent task: "are any of my events about to render at the wrong hour for someone?" — yes/no with the offenders.
outlook-calendar-pp-cli tz-audit --json
Agent-native plumbing
-
prep — For upcoming events in the next N hours, return a dossier: subject, location, attendee emails, organizer, body excerpt, attachments list, recurrence/online-meeting flags.
Single tool call that gives an agent everything needed to brief the user on what's coming up.
outlook-calendar-pp-cli prep --next 4h --json
Usage
Run outlook-calendar-pp-cli --help for the full command reference and flag list.
Commands
attachments
Manage event attachments
outlook-calendar-pp-cli attachments delete - Delete an attachmentoutlook-calendar-pp-cli attachments get - Get a specific attachment by idoutlook-calendar-pp-cli attachments list - List attachments on an event
availability
Free/busy and meeting-time intelligence (degraded on personal Microsoft accounts; prefer freetime for self-only queries)
outlook-calendar-pp-cli availability find - Suggest meeting times based on attendee availability and constraintsoutlook-calendar-pp-cli availability schedule - Get free/busy schedule for a list of users (limited on personal Microsoft accounts)
calendars
Manage Outlook calendars on your account
outlook-calendar-pp-cli calendars create - Create a new calendaroutlook-calendar-pp-cli calendars default - Get the user's default calendaroutlook-calendar-pp-cli calendars delete - Delete a calendaroutlook-calendar-pp-cli calendars get - Get a calendar by idoutlook-calendar-pp-cli calendars list - List all calendars on the accountoutlook-calendar-pp-cli calendars update - Update a calendar
categories
Manage Outlook master categories used to tag events
outlook-calendar-pp-cli categories create - Create a new master categoryoutlook-calendar-pp-cli categories delete - Delete a master categoryoutlook-calendar-pp-cli categories list - List master categories
delta
Incremental delta-sync of events into the local SQLite store
outlook-calendar-pp-cli delta events - Pull incremental event changes since the last delta tokenoutlook-calendar-pp-cli delta view - Pull incremental calendar-view changes within a window
events
Outlook calendar events on your default or named calendar
outlook-calendar-pp-cli events accept - Accept a meeting inviteoutlook-calendar-pp-cli events cancel - Cancel an event you organized (notifies attendees)outlook-calendar-pp-cli events create - Create a new event on the default calendaroutlook-calendar-pp-cli events decline - Decline a meeting inviteoutlook-calendar-pp-cli events delete - Delete an event by idoutlook-calendar-pp-cli events dismiss - Dismiss the reminder for an eventoutlook-calendar-pp-cli events forward - Forward an event to additional attendeesoutlook-calendar-pp-cli events get - Get a single event by idoutlook-calendar-pp-cli events instances - List occurrences of a recurring event in a date rangeoutlook-calendar-pp-cli events list - List events on the default calendaroutlook-calendar-pp-cli events range - List events occurring within a date range (calendarView; expands recurring instances)outlook-calendar-pp-cli events search - Server-side search across events ($search query)outlook-calendar-pp-cli events snooze - Snooze the reminder for an event until a specific timeoutlook-calendar-pp-cli events tentative - Tentatively accept a meeting inviteoutlook-calendar-pp-cli events update - Update fields on an existing event (subject, body, time, location, attendees)
Output Formats
# Human-readable table (default in terminal, JSON when piped)
outlook-calendar-pp-cli attachments list mock-value
# JSON for scripting and agents
outlook-calendar-pp-cli attachments list mock-value --json
# Filter to specific fields
outlook-calendar-pp-cli attachments list mock-value --json --select id,name,status
# Dry run — show the request without sending
outlook-calendar-pp-cli attachments list mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
outlook-calendar-pp-cli attachments list mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
outlook-calendar-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/outlook-calendar-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
OUTLOOK_CALENDAR_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
outlook-calendar-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $OUTLOOK_CALENDAR_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- auth login fails with AADSTS50059 'No tenant-identifying information found' — Confirm your Azure app's Supported account types is
AzureADandPersonalMicrosoftAccount. Re-register if it was set to single-tenant.
- auth login fails with AADSTS70016 polling timeout — Re-run
auth login --device-code; the polling window is ~15 minutes.
- 401 on /me/events after a long idle — Run
outlook-calendar-pp-cli auth refresh to rotate the access token, or just re-run the failing command (the client refreshes automatically).
- getSchedule returns degraded data on a personal MSA — Use
freetime (offline, your own calendars only) instead of availability schedule — getSchedule is documented as degraded on consumer accounts.
- Events show in the wrong time zone in --json output — Pass
--prefer-tz America/New_York (or another IANA zone). The CLI sets the Prefer: outlook.timezone="<tz>" header so all times return in that zone.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press