event

cmdhub adapter

Microsoft Calendar CLI
for cmdhub.

Outlook calendars, events, free/busy windows, and open slots through Microsoft Graph.

lock Auth: OAuth2

Quick Install cmdhub get mscal

data_object Agent Contract

Agents should start with auth/status and discovery commands, inspect schemas before composition, and treat commands marked as mutating as state-changing operations.

catalog.json Markdown

Output

Use human output for reading, `--json` for one object, and `--jsonl` for pipes.

Auth

Microsoft OAuth. Used for Outlook calendars, events, and availability.

Refs

Prefer list/search, then short refs or piped JSONL. Use `resolve` to inspect cached refs.

Schemas

Use `mscal schema` and `catalog.json` to inspect fields, flags, examples, and side effects.

Auth scopes

offline_accessUser.ReadCalendars.ReadWrite

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--json bool Emit JSON machine output

--jsonl bool Emit JSONL records for piping

--output, -o string Compatibility output mode: json|jsonl. Prefer --json or --jsonl

--view string = summary View mode: summary|full

--profile string = default Config/auth profile

--config string Config path override

--quiet, -q bool Suppress non-essential diagnostics

--debug bool Enable debug diagnostics

--limit int = 50 Maximum items to emit

--page-size int = 50 Requested upstream page size

--cursor string Continuation cursor

--no-paginate bool Fetch only one page

--version, -v bool Print version information

mscal auth Manage Microsoft Outlook Calendar authentication

#cmd-mscal-auth discovery safe

mscal auth logout Remove stored credentials

#cmd-mscal-auth-logout mutates state

$ mscal auth login

$ mscal auth logout

$ mscal auth logout --help

mscal auth refresh Refresh stored token

#cmd-mscal-auth-refresh mutates state

$ mscal auth refresh

$ mscal auth refresh --help

$ mscal auth status

mscal auth status Show auth status

#cmd-mscal-auth-status discovery safe

$ mscal auth status

$ mscal auth status --help

$ mscal auth status --view full

mscal auth whoami Show current calendar identity

#cmd-mscal-auth-whoami discovery safe

$ mscal auth whoami

$ mscal auth whoami --help

$ mscal auth whoami --json

mscal calendar Manage calendars

#cmd-mscal-calendar discovery safe

mscal calendar get Get a calendar

#cmd-mscal-calendar-get discovery safe

$ mscal calendar get

$ mscal calendar get c1

$ mscal calendar get c1 c2

$ mscal calendar get primary --view full

$ mscal calendar list --jsonl | mscal calendar get

mscal calendar list List calendars

#cmd-mscal-calendar-list discovery safe

$ mscal calendar list

$ mscal calendar list --jsonl | mscal calendar get

$ mscal calendar list --view full

mscal calendar search Search calendars by summary

#cmd-mscal-calendar-search discovery safe

--query string Search text

$ mscal calendar search

$ mscal calendar search --query holidays

$ mscal calendar search --query work --view full

mscal capabilities Describe mscal capabilities, scopes, output modes, and schemas

#cmd-mscal-capabilities discovery safe

Describe mscal capabilities, scopes, schemas, and the command contract.

The default machine output includes the full command contract so help, schemas, guidance, and conformance use the same inventory. Use –section for focused human or JSON views of scopes, schemas, or command paths.

--section string Focused section: scopes, schemas, or commands

$ mscal capabilities

$ mscal capabilities --help

$ mscal capabilities --json

$ mscal capabilities --section scopes

mscal config Inspect local configuration

#cmd-mscal-config discovery safe

mscal config explain Explain resolved configuration

#cmd-mscal-config-explain discovery safe

$ mscal config explain --help

mscal doctor Run mscal diagnostics

#cmd-mscal-doctor discovery safe

$ mscal doctor

$ mscal doctor --help

$ mscal doctor --view full

mscal event Manage calendar events

#cmd-mscal-event discovery safe

mscal event create Create an event

#cmd-mscal-event-create mutates state

Create a timed or all-day event.

Time fields accept natural values such as “tomorrow 14:00”, relative values such as +1h, or RFC3339 timestamps such as 2026-05-30T14:00:00+02:00. Use –duration with –start for the common RFC3339 + duration + location shape. Timed events without –end or –duration default to 30 minutes.

Adding –attendee, –optional-attendee, or –room creates a Microsoft meeting and sends provider invitations. Pass –send-invites to confirm that external effect.

--all-day bool All-day event

--attendee stringArray = [] Required attendee email; repeat for multiple attendees

--calendar string = primary Calendar selector

--description string Description

--duration string Duration

--end string Event end

--location string Location

--optional-attendee stringArray = [] Optional attendee email; repeat for multiple attendees

--room stringArray = [] Room email or resource attendee; repeat for multiple rooms

--send-invites bool Confirm that attendee or room flags send Microsoft meeting invitations

--start string Event start

--title string Event title

--yes, -y bool Accepted for compatibility; this command is already non-interactive

$ mscal event create --calendar c1 --title "Planning" --start 2026-05-30T14:00:00+02:00 --duration 45m --location "Room 4"

$ mscal event create --help

$ mscal event create --title "Company holiday" --start 2026-05-01 --all-day

$ mscal event create --title "Interview" --start +2h --duration 45m --attendee alex@example.com --room conf-a@example.com --send-invites

$ mscal event create --title "Project review" --start "tomorrow 14:00" --duration 45m

mscal event delete Delete an event

#cmd-mscal-event-delete mutates state

--all bool Confirm batch event delete

--calendar string Optional calendar selector

--yes, -y bool Confirm destructive batch event delete

$ mscal event delete --all --yes e1 e2

$ mscal event delete --help

$ mscal event delete e1

$ mscal event search --query cmdhub-human-audit --jsonl | mscal event delete --all --yes

mscal event get Get an event

#cmd-mscal-event-get discovery safe

Get event details by local ref, provider ID, or event JSONL from stdin.

When stdin contains event JSONL items from event list/search, event get consumes the item id/provider_id plus calendar_id fields, fetches current provider details, and renders the retrieved event. The get output is already the usable detail view; a second “mscal event get e1” call is only needed if you intentionally want to re-open a new local ref.

--calendar string Optional calendar selector

$ mscal event get

$ mscal event get e1

$ mscal event get e1 --view full

$ mscal event get e1 e2

$ mscal event list --today --jsonl | mscal event get

$ mscal event search --query audit --limit 1 --jsonl | mscal event delete --all --yes

$ mscal event search --query audit --limit 1 --jsonl | mscal event get

$ mscal event search --query audit --limit 1 --jsonl | mscal event update --location "Room 4"

mscal event list List events

#cmd-mscal-event-list discovery safe

--calendar string = primary Calendar selector

--from string Start time

--to string End time; relative values such as +4h are relative to --from

--today bool Today window

--tomorrow bool Tomorrow window

--week bool Week window

$ mscal event list

$ mscal event list --calendar c1 --from now --to +72h

$ mscal event list --today

$ mscal event list --week --view full

mscal event quick-add Create an event from natural text

#cmd-mscal-event-quick-add mutates state

--calendar string = primary Calendar selector

--text string Quick-add text

--yes, -y bool Accepted for compatibility; this command is already non-interactive

$ mscal event quick-add --calendar c1 --text "Planning review today 3pm"

$ mscal event quick-add --help

$ mscal event quick-add --text "Lunch with Sam tomorrow 12pm"

mscal event search Search events

#cmd-mscal-event-search discovery safe

Search events using Microsoft Calendar full-text query semantics.

Use plain text or tokens in –query, such as “dentist” or “project review”. Field-prefix filters such as title:review are not supported by this CLI surface.

For single-event detail, pipe JSONL search results into event get: mscal event search –query “project review” –jsonl | mscal event get

The same JSONL search stream can feed update or delete when it contains the exact event you intend to mutate: mscal event search –query “project review” –limit 1 –jsonl | mscal event update –location “Room 4” mscal event search –query “project review” –limit 1 –jsonl | mscal event delete –all –yes

--calendar string = primary Calendar selector

--from string Start time

--query string Search query

--to string End time; relative values such as +4h are relative to --from

$ mscal event search

$ mscal event search --query "project review" --from today --to tomorrow

$ mscal event search --query audit --jsonl | mscal event get

$ mscal event search --query audit --limit 1 --jsonl | mscal event delete --all --yes

$ mscal event search --query audit --limit 1 --jsonl | mscal event update --location "Room 4"

$ mscal event search --query dentist

mscal event update Update an event

#cmd-mscal-event-update mutates state

Update event fields.

Adding or changing attendees creates or updates a Microsoft meeting and can send provider invitations or updates. Pass –send-updates all when using attendee or room flags so the notification behavior is explicit.

--all-day bool All-day event

--attendee stringArray = [] Required attendee email; repeat for multiple attendees

--calendar string Optional calendar selector

--description string Description

--duration string Duration

--end string Event end

--location string Location

--optional-attendee stringArray = [] Optional attendee email; repeat for multiple attendees

--room stringArray = [] Room email or resource attendee; repeat for multiple rooms

--send-updates string Confirm attendee or room update notifications: all

--start string Event start

--title string Event title

--yes, -y bool Accepted for compatibility; this command is already non-interactive

$ mscal event search --query review --jsonl | mscal event update --location "Room 4"

$ mscal event update --help

$ mscal event update e1 --attendee alex@example.com --send-updates all

$ mscal event update e1 --start "tomorrow 15:00" --duration 30m

$ mscal event update e1 --title "Updated title"

mscal freebusy Inspect busy windows

#cmd-mscal-freebusy discovery safe

mscal freebusy get Get busy windows for calendars

#cmd-mscal-freebusy-get discovery safe

--calendar stringSlice = [primary] Calendar selectors

--from string Start time

--schedule stringSlice = [] Alias for --user; Microsoft Graph schedule email to include

--to string End time; relative values such as +4h are relative to --from

--user stringSlice = [] User or schedule email to include; repeat or comma-separate

$ mscal freebusy get

$ mscal freebusy get --calendar c1 --from today --to tomorrow

$ mscal freebusy get --from "tomorrow 09:00" --to "tomorrow 17:00" --view full

$ mscal freebusy get --from now --to +4h

$ mscal freebusy get --user alex@example.com --from "tomorrow 09:00" --to "tomorrow 17:00"

mscal meeting-time Find Microsoft Graph meeting-time suggestions

#cmd-mscal-meeting-time discovery safe

mscal meeting-time find Find meeting-time suggestions

#cmd-mscal-meeting-time-find discovery safe

Find Microsoft Graph meeting-time suggestions for attendees and rooms.

This uses Microsoft Graph findMeetingTimes. Some personal Microsoft accounts or tenants do not support this scheduling surface; in that case mscal returns a provider-limit recovery screen and suggests free/busy or event list fallbacks.

--attendee stringSlice = [] Required attendee email; repeat or comma-separate

--duration string = 30m Meeting duration

--from string Start time

--room stringSlice = [] Room email; repeat or comma-separate

--to string End time; relative values such as +4h are relative to --from

$ mscal meeting-time find

$ mscal meeting-time find --attendee alex@example.com --from "tomorrow 09:00" --to "tomorrow 17:00" --duration 30m

$ mscal meeting-time find --attendee alex@example.com --room conf-a@example.com --from now --to +8h

mscal profile Manage provider profiles

#cmd-mscal-profile discovery safe

mscal profile create Create an unauthenticated provider profile

#cmd-mscal-profile-create mutates state

$ mscal profile create --help

mscal profile delete Delete a local provider profile

#cmd-mscal-profile-delete mutates state

$ mscal profile delete --help

mscal profile list List provider profiles

#cmd-mscal-profile-list discovery safe

$ mscal profile list --help

mscal profile rename Rename a local provider profile

#cmd-mscal-profile-rename discovery safe

$ mscal profile rename --help

mscal profile use Set the default provider profile

#cmd-mscal-profile-use mutates state

$ mscal profile use --help

mscal resolve Resolve a marker or short id

#cmd-mscal-resolve discovery safe

$ mscal resolve --help

$ mscal resolve c1

$ mscal resolve e1

$ mscal resolve u1

mscal room Discover Microsoft 365 rooms

#cmd-mscal-room discovery safe

mscal room get Get a room

#cmd-mscal-room-get discovery safe

$ mscal room get

$ mscal room get r1

$ mscal room search --query conference --jsonl | mscal room get

mscal room list List rooms

#cmd-mscal-room-list discovery safe

$ mscal room list

$ mscal room list --limit 20 --jsonl

mscal room search Search rooms

#cmd-mscal-room-search discovery safe

--query string Room search text

$ mscal room search

$ mscal room search --query "floor 4" --jsonl

$ mscal room search --query conference

mscal schema Emit mscal schema hints

#cmd-mscal-schema discovery safe

--in bool Show input schema

--input bool Show input schema

--out bool Show output schema

$ mscal schema

$ mscal schema --help

$ mscal schema event.create --input

$ mscal schema event.create --out

mscal slot Find open slots

#cmd-mscal-slot discovery safe

mscal slot find Find open slots across calendars

#cmd-mscal-slot-find discovery safe

--calendar stringSlice = [primary] Calendar selectors

--duration string = 30m Minimum slot duration

--from string Start time

--to string End time; relative values such as +4h are relative to --from

$ mscal slot find

$ mscal slot find --calendar c1 --from today --to tomorrow --duration 1h

$ mscal slot find --from "tomorrow 09:00" --to "tomorrow 17:00" --view full

$ mscal slot find --from now --to +4h --duration 30m

mscal version Show mscal version information

#cmd-mscal-version discovery safe

$ mscal version

$ mscal version --help

$ mscal version --json

play_circle Live Examples

Output captured from a real workspace. Regenerate with scripts/gen-docs.sh --update.

auth

Check current Microsoft calendar identity Returns the active Microsoft calendar identity.

$ mscal auth whoami

Authenticated as kestrelphilip@outlook.com

Next steps:
- Calendars:    mscal calendar list
- Events:       mscal event list --week
- Capabilities: mscal capabilities

diagnostics

Run diagnostics Checks auth, scopes, and Microsoft Graph calendar connectivity.

$ mscal doctor

mscal doctor: WARN
Account: kestrelphilip@outlook.com
Checks: {id} ok, {id} warn, profiles ok, microsoft_oauth ok, token ok, scopes ok, mscal_api ok, local_timezone ok
CHECK                STATUS  DETAIL
{id}   OK      using file
{id}  WARN    credential backend stores local plaintext secrets
profiles             OK      active profile "kestrelphilip@outlook.com"
microsoft_oauth      OK      built-in Microsoft provider client is configured
token                OK      token expires at 2026-05-30T16:33:17Z
scopes               OK      stored token covers required Microsoft Outlook Calendar scopes
mscal_api            OK      calendar API reachable
local_timezone       OK      Local

Next steps:
- Status:       mscal auth status
- Capabilities: mscal capabilities

calendars

List calendars Lists visible calendars.

$ mscal calendar list --limit 5

REF  TITLE                  STATUS
c1   Calendar               primary, writer
c2   Birthdays              selected, reader
c3   South Africa holidays  selected, reader

Next steps:
- Open:         mscal calendar get c1
- Events:       mscal event list --calendar c1 --week
- Freebusy:     mscal freebusy get --calendar c1 --from {time} --to +8h
- Capabilities: mscal capabilities

events

List today's events Lists events happening today.

$ mscal event list --today --limit 5

Empty state

No events found.

Next steps:
- List week:   mscal event list --calendar primary --from 2026-05-30T00:00:00+02:00 --to 2026-05-31T00:00:00+02:00
- Create hold: mscal event create --calendar primary --title Hold --start +1h --duration 30m
- Status:      mscal auth status
- Calendars:   mscal calendar list

Search events Searches events by text.

$ mscal event search --query eval --limit 5

Empty state

No events matched "eval".

Next steps:
- List week:   mscal event list --calendar primary --from 2026-05-30T18:02:12+02:00 --to 2026-06-02T18:02:12+02:00
- Create hold: mscal event create --calendar primary --title Hold --start +1h --duration 30m
- Status:      mscal auth status
- Calendars:   mscal calendar list

freebusy

Inspect busy windows Shows busy windows on the primary calendar.

$ mscal freebusy get --calendar primary --from now --to +8h

Status: free
Busy windows
Field      Value
---------  -----
Window     Sat 30 May 18:02-Sun 31 May 02:02 Local
Calendars  primary

No busy intervals found.

Next steps:
- Find slots: mscal slot find --calendar primary --from 2026-05-30T16:02:13Z --to 2026-05-31T00:02:13Z --duration 30m
- Events:     mscal event list --calendar primary --from 2026-05-30T16:02:13Z --to 2026-05-31T00:02:13Z
- Calendars:  mscal calendar list

alt_route Composition Patterns

Bridge your ecosystem with zero middleware.

mscal auth login

# Review today's calendar and inspect one event
mscal event list --today --limit 10
mscal event get e1

# Search, inspect, and resolve through short refs
mscal event search --query "project review" --limit 1 --jsonl \
  | mscal event get

mscal resolve e1

# Create and clean up an event
mscal event create --title "Project review" --start "tomorrow 14:00" --duration 1h
mscal event delete e1

Microsoft Calendar CLIfor cmdhub.

data_object Agent Contract

Output

Auth

Refs

Schemas

Auth scopes

terminal Command Reference

Global Flags

play_circle Live Examples

auth

diagnostics

calendars

events

freebusy

alt_route Composition Patterns

Microsoft Calendar CLI
for cmdhub.