Microsoft Calendar CLI
for cmdhub.
Outlook calendars, events, free/busy windows, and open slots through Microsoft Graph.
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.
Output
Use human output for normal reads, `--json` for scripting or complete structured fields, and `--jsonl` for upstream pipe inputs.
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.ReadWriteterminal 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 informationmscal attachment
Manage event attachmentsmscal attachment add
Add a file attachment to an event--calendar
string
Optional calendar selector--content-type
string
Attachment MIME type--event
string
Event ref or provider ID--file
string
File to upload--name
string
Attachment display name--yes, -y
bool
Confirm attachment uploadmscal attachment delete
Delete an attachment--calendar
string
Optional calendar selector--dry-run
bool
Preview attachment deletion without deleting--event
string
Event ref or provider ID when not using an attachment local ref--yes, -y
bool
Confirm attachment deletemscal attachment download
Download an attachment--calendar
string
Optional calendar selector--event
string
Event ref or provider ID when not using an attachment local ref--output-file
string
Path to write attachment bytesmscal attachment get
Get an attachment--calendar
string
Optional calendar selector--event
string
Event ref or provider ID when not using an attachment local refmscal attachment list
List attachments for an event--calendar
string
Optional calendar selector--event
string
Event ref or provider IDmscal auth
Manage Microsoft Outlook Calendar authenticationManage Microsoft Outlook Calendar OAuth credentials for the selected cmdhub profile.
mscal uses Microsoft OAuth device-code login. Login displays https://microsoft.com/devicelogin with a one-time code, waits for Microsoft authorization, and stores the Microsoft Graph refresh/access token in the shared cmdhub credential backend for the selected profile. It never asks for a normal Microsoft account password and never prints tokens.
Use –profile for one command or mscal profile use to change the default profile. Required delegated scopes are offline_access, User.Read, and Calendars.ReadWrite.
Recovery commands: mscal auth status mscal auth login mscal auth whoami mscal doctor
mscal auth login
Authenticate with Microsoft Outlook CalendarStart Microsoft OAuth device-code login for Microsoft Outlook Calendar.
The command displays https://microsoft.com/devicelogin with a one-time code. Sign in with the intended Microsoft account and approve delegated Microsoft Graph scopes offline_access, User.Read, and Calendars.ReadWrite. Do not paste a normal Microsoft account password, access token, refresh token, client secret, cookie, or private key into mscal.
The packaged CLI embeds a public Microsoft native-client ID. Local development can override it with CMDHUB_MSCAL_CLIENT_ID only when testing a different public/native app registration.
Recovery commands: mscal auth status mscal auth login mscal auth whoami mscal doctor
mscal auth logout
Remove stored Microsoft OAuth device-code credentialsmscal auth refresh
Refresh stored tokenmscal auth status
Show auth statusReport Microsoft Outlook Calendar auth readiness for the selected profile.
Status checks whether the shared cmdhub credential backend has Microsoft OAuth device-code credentials, whether refresh succeeds, whether the required delegated scopes are present, and whether the profile is ready for Microsoft Graph Calendar commands.
If credentials are missing, expired, underscoped, or tied to the wrong Microsoft account, rerun mscal auth login for the same –profile and then mscal doctor.
mscal auth whoami
Show current calendar identityShow the Microsoft identity bound to the selected mscal profile.
The command verifies the stored Microsoft OAuth token against Microsoft Graph /me and reports the account details available for the selected profile. Use mscal auth status for credential storage, scope, token-refresh, and provider-readiness details.
mscal calendar
Manage calendarsmscal calendar get
Get a calendarmscal calendar list
List calendarsmscal calendar search
Search calendars by summary--query
string
Search textmscal capabilities
Describe mscal capabilities, scopes, output modes, and schemasDescribe 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 commandsmscal category
Inspect Outlook calendar categoriesmscal category get
Get a categorymscal category list
List categoriesmscal config
Inspect local configurationmscal config explain
Explain resolved configurationmscal doctor
Run mscal diagnosticsmscal event
Manage calendar eventsmscal event accept
Respond to an event invitation--calendar
string
Optional calendar selector--comment
string
Response comment--send-response
bool
Send response message to organizermscal event cancel
Cancel a meeting and notify attendees--calendar
string
Optional calendar selector--comment
string
Cancellation message--dry-run
bool
Preview event cancellation without notifying attendees--yes, -y
bool
Confirm cancellation notificationmscal event create
Create an eventCreate 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 or –optional-attendee 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--category
stringArray = []
Existing Outlook category name; repeat for multiple categories--description
string
Description--duration
string
Duration--end
string
Event end--location
string
Location--online-meeting
bool
Request a provider online meeting link when supported--optional-attendee
stringArray = []
Optional attendee email; repeat for multiple attendees--recurrence
string
Provider recurrence payload or rule--reminder
string
Reminder before start, for example 15m--send-invites
bool
Confirm that attendee flags send Microsoft meeting invitations--show-as
string
Show-as state: free, tentative, busy, oof, workingElsewhere--start
string
Event start--timezone
string
Event time zone--title
string
Event title--transaction-id
string
Idempotency transaction ID for create--yes, -y
bool
Accepted for compatibility; this command is already non-interactivemscal event decline
Respond to an event invitation--calendar
string
Optional calendar selector--comment
string
Response comment--send-response
bool
Send response message to organizermscal event delete
Delete an event--all
bool
Confirm batch event delete--calendar
string
Optional calendar selector--dry-run
bool
Preview event delete without deleting--yes, -y
bool
Confirm destructive batch event deletemscal event get
Get an eventGet 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 selectormscal event list
List events--calendar
string = primary
Calendar selector--from
string
Start time--include-cancelled
bool
Include cancelled events--to
string
End time; relative values such as +4h are relative to --from--today
bool
Today window--tomorrow
bool
Tomorrow window--tz
string
Display time zone--week
bool
Week windowmscal event quick-add
Create an event from natural text--calendar
string = primary
Calendar selector--text
string
Quick-add text--yes, -y
bool
Accepted for compatibility; this command is already non-interactivemscal event search
Search eventsSearch 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
--attendee
stringArray = []
Filter by attendee email; repeat for multiple attendees--calendar
string = primary
Calendar selector--category
stringArray = []
Filter by Outlook category; repeat for multiple categories--from
string
Start time--include-cancelled
bool
Include cancelled events--query
string
Search query--status
stringArray = []
Filter by event status, for example busy or cancelled--to
string
End time; relative values such as +4h are relative to --from--tz
string
Display time zonemscal event tentatively-accept
Respond to an event invitation--calendar
string
Optional calendar selector--comment
string
Response comment--send-response
bool
Send response message to organizermscal event update
Update an eventUpdate 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 attendee-list flags so the notification behavior is explicit.
--add-attendee
stringArray = []
Add required attendee email; repeat for multiple attendees--all-day
bool
All-day event--attendee
stringArray = []
Required attendee email; repeat for multiple attendees--calendar
string
Optional calendar selector--cancel-online-meeting
bool
Remove online meeting state when provider-supported--category
stringArray = []
Existing Outlook category name; repeat for multiple categories--clear-description
bool
Clear event description--clear-location
bool
Clear event location--clear-reminder
bool
Clear event reminder--description
string
Description--duration
string
Duration--end
string
Event end--location
string
Location--online-meeting
bool
Request a provider online meeting link when supported--optional-attendee
stringArray = []
Optional attendee email; repeat for multiple attendees--recurrence
string
Provider recurrence payload or rule--reminder
string
Reminder before start, for example 15m--remove-attendee
stringArray = []
Remove attendee email; repeat for multiple attendees--send-updates
string
Confirm attendee update notifications: all--set-optional-attendee
stringArray = []
Set optional attendee list; repeat for multiple attendees--set-required-attendee
stringArray = []
Set required attendee list; repeat for multiple attendees--show-as
string
Show-as state: free, tentative, busy, oof, workingElsewhere--start
string
Event start--timezone
string
Event time zone--title
string
Event title--yes, -y
bool
Accepted for compatibility; this command is already non-interactivemscal freebusy
Inspect busy windowsmscal freebusy get
Get busy windows for calendars--calendar
stringSlice = [primary]
Calendar selectors--from
string
Start time--schedule
stringSlice = []
User or resource schedule email to include; repeat or comma-separate--to
string
End time; relative values such as +4h are relative to --from--tz
string
Display time zonemscal mcp
Run the MCP serverRun a stdio Model Context Protocol server for this adapter.
The server exposes read-only resource commands by default. Mutating commands are listed only when explicitly allowed with –allow and remain gated by the command contract safety class.
--allow
stringArray = []
Allow mutating command keys such as gmail.message.archive or gmail.message.label.*--allow-dangerous
bool
Allow --allow wildcards to include destructive or sends_external commands--concurrency
int
Maximum concurrent MCP subprocesses--max-output
int64 = 0
Maximum stdout/stderr bytes captured per MCP command--print-config
bool
Print MCP tool configuration and exit--timeout
duration = 0s
Per-command MCP subprocess timeout, for example 45s or 2mmscal meeting-time
Find Microsoft Graph meeting-time suggestionsmscal meeting-time find
Find meeting-time suggestionsFind Microsoft Graph meeting-time suggestions for attendees.
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--location
string
Preferred meeting location--max-candidates
int
Maximum meeting-time candidates--optional
stringSlice = []
Optional attendee email; repeat or comma-separate--required
stringSlice = []
Required attendee email; repeat or comma-separate--to
string
End time; relative values such as +4h are relative to --from--tz
string
Display time zonemscal profile
Manage provider profilesmscal profile create
Create an unauthenticated provider profilemscal profile delete
Delete a local provider profilemscal profile list
List provider profilesmscal profile rename
Rename a local provider profilemscal profile use
Set the default provider profilemscal resolve
Resolve a marker or short idmscal schema
Emit mscal schema hints--in
bool
Show input schema--input
bool
Show input schema--out
bool
Show output schemamscal slot
Find open slotsmscal slot find
Find open slots across calendars--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--tz
string
Display time zonemscal version
Show mscal version informationplay_circle Live Examples
Output captured from a real workspace. Regenerate with
scripts/gen-docs.sh --update.
auth
Authenticated as kestrelphilip@outlook.com Next steps: - Calendars: mscal calendar list - Events: mscal event list --week - Capabilities: mscal capabilities
diagnostics
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 Microsoft Calendar OAuth client is configured
token OK token expires at 2026-06-13T17:56:58Z
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 capabilitiescalendars
REF TITLE STATUS c1 Calendar primary, writer c2 Birthdays selected, reader c3 South Africa holidays selected, reader Next steps: - Open: mscal calendar get c1 - Search: mscal calendar search --query <text> - Calendars: mscal calendar list - Events: mscal event list --week
events
No event found. Next steps: - Search: mscal event search --query <text> - Create: mscal event create - Status: mscal auth status - Calendars: mscal calendar list
No event found. Next steps: - List: mscal event list - Create: mscal event create - Status: mscal auth status - Calendars: mscal calendar list
freebusy
Status: free Busy windows Field Value --------- ----- Window Sat 13 Jun 18:57-Sun 14 Jun 02:57 Local Calendars primary No busy intervals found. Next steps: - Find slots: mscal slot find --calendar primary --from 2026-06-13T16:57:35Z --to 2026-06-14T00:57:35Z --duration 30m - Events: mscal event list --calendar primary --from 2026-06-13T16:57:35Z --to 2026-06-14T00:57:35Z - 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 --dry-run
mscal event delete e1 --yes
