CLI Reference - outlookctl

Overview

All commands follow this pattern:

bash

uv run python -m outlookctl.cli <command> [options]

Global Options

Option	Description
`--output`	Output format: `json` or `text` (default: json)
`--version`	Show version number and exit
`--help`	Show help message and exit

outlookctl doctor diagnostic

Validates environment and prerequisites. Run this first to ensure everything is set up correctly.

bash

uv run python -m outlookctl.cli doctor

Checks Performed

✓ Windows OS detection
✓ pywin32 installation
✓ Outlook COM availability
✓ Outlook executable location

outlookctl list email

List messages from a folder. Returns message summaries including subject, sender, date, and read status.

bash

uv run python -m outlookctl.cli list --count 10 --unread-only

Options

Option	Default	Description
`--folder`	inbox	Folder to list from
`--count`	10	Number of messages to return
`--unread-only`	false	Only return unread messages
`--since`	-	ISO date filter (messages after)
`--until`	-	ISO date filter (messages before)
`--include-body-snippet`	false	Include body preview
`--body-snippet-chars`	200	Max characters for snippet

Folder Specifications

inbox Default inbox

sent Sent items

drafts Drafts folder

deleted Deleted items

outbox Outbox

junk Junk/spam

Custom folders: by-name:FolderName or by-path:Inbox/Subfolder

outlookctl get email

Get a single message by ID. Returns full message details including body content when requested.

bash

uv run python -m outlookctl.cli get \
  --id "00000..." \
  --store "00000..." \
  --include-body

Options

Option	Required	Description
`--id`	Required	Message entry ID
`--store`	Required	Message store ID
`--include-body`	Optional	Include full message body
`--include-headers`	Optional	Include message headers
`--max-body-chars`	Optional	Limit body length

outlookctl search email

Search messages with various filters. Combines multiple criteria with AND logic.

bash

uv run python -m outlookctl.cli search \
  --from "boss@company.com" \
  --has-attachments \
  --since 2025-01-01

Options

Option	Default	Description
`--folder`	inbox	Folder to search
`--query`	-	Free text search (subject/body)
`--from`	-	Filter by sender
`--to`	-	Filter by To recipient new
`--cc`	-	Filter by CC recipient new
`--subject-contains`	-	Filter by subject text
`--unread-only`	false	Only unread messages
`--has-attachments`	false	Only with attachments new
`--no-attachments`	false	Only without attachments new
`--since`	-	ISO date filter (after)
`--until`	-	ISO date filter (before)
`--count`	50	Maximum results

outlookctl draft email

Create a draft message. The draft is saved to the Drafts folder and can be reviewed before sending.

bash

uv run python -m outlookctl.cli draft \
  --to "recipient@example.com" \
  --subject "Meeting Follow-up" \
  --body-text "Thank you for the meeting."

Options

Option	Description
`--to`	To recipients (comma-separated)
`--cc`	CC recipients (comma-separated)
`--bcc`	BCC recipients (comma-separated)
`--subject`	Email subject
`--body-text`	Plain text body
`--body-html`	HTML body
`--attach`	File path to attach (repeatable)
`--reply-to-id`	Entry ID of message to reply to
`--reply-to-store`	Store ID of message to reply to
`--reply-all`	Reply-all instead of reply new

outlookctl send email

Send a draft or new message. Requires explicit confirmation.

⚠

Safety: Sending requires --confirm-send YES. The recommended workflow is to create a draft first, review it, then send.

bash

# Send existing draft (recommended)
uv run python -m outlookctl.cli send \
  --draft-id "00000..." \
  --draft-store "00000..." \
  --confirm-send YES

Safety Options

Option	Description
`--confirm-send`	Must be exactly "YES" to proceed
`--confirm-send-file`	Path to file containing "YES"
`--unsafe-send-new`	Required for sending new message directly
`--log-body`	Include body in audit log

outlookctl move

email new

Move a message to another folder. Returns the new message ID after moving.

bash

uv run python -m outlookctl.cli move \
  --id "00000..." \
  --store "00000..." \
  --dest "by-name:Archive"

Options

Option	Required	Description
`--id`	Required	Message entry ID
`--store`	Required	Message store ID
`--dest`	Required	Destination folder (same specs as list)

outlookctl delete

email new

Delete a message. By default moves to Deleted Items; use --permanent to skip the trash.

bash

uv run python -m outlookctl.cli delete \
  --id "00000..." \
  --store "00000..."

Options

Option	Required	Description
`--id`	Required	Message entry ID
`--store`	Required	Message store ID
`--permanent`	Optional	Permanently delete (skip Deleted Items)

outlookctl mark-read

email new

Mark a message as read or unread.

bash

# Mark as read
uv run python -m outlookctl.cli mark-read --id "..." --store "..."

# Mark as unread
uv run python -m outlookctl.cli mark-read --id "..." --store "..." --unread

Options

Option	Required	Description
`--id`	Required	Message entry ID
`--store`	Required	Message store ID
`--unread`	Optional	Mark as unread instead of read

outlookctl forward

email new

Create a forward draft for a message. The forward is saved as a draft for review before sending.

bash

uv run python -m outlookctl.cli forward \
  --id "00000..." \
  --store "00000..." \
  --to "colleague@example.com" \
  --message "FYI - see below"

Options

Option	Required	Description
`--id`	Required	Original message entry ID
`--store`	Required	Original message store ID
`--to`	Required	To recipients (comma-separated)
`--cc`	Optional	CC recipients
`--bcc`	Optional	BCC recipients
`--message`	Optional	Additional text to prepend

outlookctl attachments save email

Save attachments from a message to disk. Creates the destination directory if needed.

bash

uv run python -m outlookctl.cli attachments save \
  --id "00000..." \
  --store "00000..." \
  --dest "./downloads"

Options

Option	Required	Description
`--id`	Required	Message entry ID
`--store`	Required	Message store ID
`--dest`	Required	Destination directory

outlookctl calendar calendars calendar new

List all available calendars across all accounts, including subscribed ICS calendars, shared calendars, and internet calendars.

bash

uv run python -m outlookctl.cli calendar calendars

Output Fields

Field	Description
`name`	Calendar display name
`path`	Full path in folder hierarchy
`store`	Account/store containing the calendar

Usage

Use this to discover calendar names, then access them with --calendar "Name" in other commands.

outlookctl calendar list calendar

List calendar events within a date range. Defaults to the next 7 days from today.

bash

uv run python -m outlookctl.cli calendar list \
  --start "2025-01-20" \
  --days 14

bash

# Access a specific calendar by name
uv run python -m outlookctl.cli calendar list \
  --calendar "Family" --days 7

Options

Option	Default	Description
`--start`	today	Start date
`--end`	-	End date (overrides --days)
`--days`	7	Number of days from start
`--calendar`	-	Calendar name or email for shared calendar
`--count`	100	Maximum events

outlookctl calendar get calendar

Get detailed information about a calendar event including attendees and recurrence.

bash

uv run python -m outlookctl.cli calendar get \
  --id "00000..." \
  --store "00000..." \
  --include-body

outlookctl calendar create calendar

Create a calendar event or meeting. Meetings with attendees are saved as drafts.

bash

uv run python -m outlookctl.cli calendar create \
  --subject "Team Sync" \
  --start "2025-01-20 10:00" \
  --duration 60 \
  --attendees "alice@example.com,bob@example.com"

Options

Option	Default	Description
`--subject`	Required	Event title
`--start`	Required	Start time
`--duration`	60	Duration in minutes
`--end`	-	End time
`--location`	-	Location
`--attendees`	-	Required attendees
`--optional-attendees`	-	Optional attendees
`--all-day`	false	All-day event
`--busy-status`	busy	free, tentative, busy, etc.
`--recurrence`	-	Recurrence pattern

outlookctl calendar send calendar

Send meeting invitations. Requires explicit confirmation.

⚠

Safety: Sending invitations requires --confirm-send YES.

bash

uv run python -m outlookctl.cli calendar send \
  --id "00000..." \
  --store "00000..." \
  --confirm-send YES

outlookctl calendar respond calendar

Respond to a meeting invitation.

bash

uv run python -m outlookctl.cli calendar respond \
  --id "00000..." \
  --store "00000..." \
  --response accept

Options

Option	Description
`--response`	accept, decline, or tentative
`--no-response`	Don't send response to organizer

outlookctl calendar update

calendar new

Update an existing calendar event. Only specified fields are modified.

bash

uv run python -m outlookctl.cli calendar update \
  --id "00000..." \
  --store "00000..." \
  --location "Room B" \
  --start "2025-01-20 11:00"

Options

Option	Required	Description
`--id`	Required	Event entry ID
`--store`	Required	Event store ID
`--subject`	Optional	New subject
`--start`	Optional	New start time
`--end`	Optional	New end time
`--duration`	Optional	New duration (minutes)
`--location`	Optional	New location
`--body`	Optional	New description
`--reminder`	Optional	New reminder (minutes)
`--busy-status`	Optional	New show-as status

outlookctl calendar delete

calendar new

Delete a calendar event. For meetings you organized, sends cancellation to attendees by default.

bash

uv run python -m outlookctl.cli calendar delete \
  --id "00000..." \
  --store "00000..."

Options

Option	Required	Description
`--id`	Required	Event entry ID
`--store`	Required	Event store ID
`--no-cancel`	Optional	Don't send cancellation to attendees