Outlook Agenda

outlook-agenda is a small CLI for people who use Outlook Calendar as their primary calendar and want a terminal-friendly way to pull its data, including shared calendars, via Microsoft Graph.

Features

• Reads events from your Outlook calendar and shared calendars
• Supports table, weekly calendar, and CSV output
• English UI by default, optional pt-BR
• Uses MSAL device code flow and stores local state outside the repository

Who this is for

• People who live in Outlook Calendar and want quick CLI access
• Users who need both their main calendar and delegated/shared calendars
• Folks who want to script exports or terminal workflows without switching to the Outlook UI

Requirements

• Python 3.12+
• A Microsoft Entra ID app registration configured as a public client
• Delegated Microsoft Graph permissions:
  • Calendars.Read
  • Calendars.Read.Shared

Install

uv sync

Microsoft Entra ID / Azure setup

Create an app registration in Microsoft Entra ID before using the CLI.

1. Go to Microsoft Entra ID -> App registrations -> New registration.
2. Give the app a name such as outlook-calendar-export.
3. Supported account types:
   • If you use personal Outlook/Hotmail/Live accounts, choose a setting that includes personal Microsoft accounts.
   • If you want broader compatibility, choose Accounts in any organizational directory and personal Microsoft accounts.
4. Open the new app and copy the Application (client) ID.
5. Go to API permissions and add delegated Microsoft Graph permissions:
   • Calendars.Read
   • Calendars.Read.Shared
6. Go to Authentication.
7. Enable the public client / device flow setting:
   • Allow public client flows = Yes
   • Or, in some portal variants, Treat application as a public client = Yes

This step is required because the CLI uses the device code flow. If it is disabled, you will get an error similar to:

AADSTS70002: The provided client is not supported for this feature.
The client application must be marked as 'mobile.'

You do not need a client secret for this project.

CLI configuration

uv run agenda init YOUR_CLIENT_ID

The client ID and token cache are stored in ~/.config/outlook-agenda/. Do not commit local secrets or cache files.

On the first real command, the CLI will show a device login URL and a verification code. Open the URL, enter the code, sign in, and grant consent.

Expected first-login prompt:

Open this URL in your browser:
https://microsoft.com/devicelogin

Verification code: ABCD-EFGH

Usage

uv run agenda today
uv run agenda day 2026-03-09
uv run agenda week
uv run agenda range 2026-03-09 2026-03-13
uv run agenda --lang pt-BR week
uv run agenda --csv range 2026-03-09 2026-03-13 > agenda.csv

Example weekly table output:

                           Weekly Agenda
┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Time  ┃ Mon                ┃ Tue                ┃ Wed                ┃
┃       ┃ 09/03              ┃ 10/03              ┃ 11/03              ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ 09:30 │ 09:30-10:00        │                    │                    │
│       │ Team Sync          │                    │                    │
│ 10:00 │ 10:00-11:00        │                    │                    │
│       │ Product Planning   │                    │                    │
│       │ Conference Room B  │                    │                    │
└───────┴────────────────────┴────────────────────┴────────────────────┘

Example single-day output:

                     Agenda
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Time ┃ Subject              ┃ Location ┃ Calendar         ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ 10:00│ Weekly 1:1           │ Zoom     │ Personal • Main  │
│ 19:30│ Sprint Planning      │ Zoom     │ Product • Shared │
└──────┴──────────────────────┴──────────┴──────────────────┘

Example CSV output:

start,end,time,subject,location,calendar,organizer
2026-03-09T10:00:00-03:00,2026-03-09T11:00:00-03:00,10:00,Weekly 1:1,Zoom,Personal • Main,calendar-owner@example.com

Test

uv run python -m unittest discover -s tests