ms-todo-sync

ms-todo-sync

A Microsoft To Do command-line client for managing tasks and lists via Microsoft Graph API.

Prerequisites

1. Python >= 3.9 must be installed.
2. uv (Python package manager) must be installed. Install via pip install uv or see https://docs.astral.sh/uv/.
3. Working directory: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file).
4. Network access: Requires internet access to Microsoft Graph API endpoints.
5. Authentication: First-time use requires interactive login via browser. See Authentication section.
   • Token cache: ~/.mstodo_token_cache.json (persists across sessions, auto-refreshed)
   • Device flow cache: ~/.mstodo_device_flow.json (temporary)

Installation & Setup

First-Time Setup

Before using this skill for the first time, dependencies must be installed:

# Navigate to skill directory
cd <path-to-ms-todo-sync>

# Install dependencies using uv (recommended - creates isolated environment)
uv sync

# Alternative: Install dependencies with pip (uses global/active Python environment)
pip install -r requirements.txt

Dependencies:

• Requires msal (Microsoft Authentication Library) and requests
• Specified in requirements.txt
• uv creates an isolated virtual environment to avoid conflicts

Environment Verification

After installation, verify the setup:

# Check if uv can find the script
uv run scripts/ms-todo-sync.py --help

# Expected: Command help text should be displayed

Troubleshooting:

• If uv: command not found, install uv: pip install uv
• If Python not found, install Python 3.9 or higher from https://python.org
• If script fails with import errors, ensure dependencies are installed: uv sync or pip install -r requirements.txt

Security Notes

• Uses official Microsoft Graph API via Microsoft's msal library
• All code is plain Python (.py files), readable and auditable
• Tokens stored locally in ~/.mstodo_token_cache.json
• All API calls go directly to Microsoft endpoints

Command Reference

All commands follow this pattern:

uv run scripts/ms-todo-sync.py [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]

Global Options

Option	Description
-v, --verbose	Show detailed information (IDs, dates, notes). Must be placed BEFORE the subcommand.
--debug	Enable debug mode to display API requests and responses. Useful for troubleshooting. Must be placed BEFORE the subcommand.

⚠️ Common mistake: Global options MUST come before the subcommand.

• ✅ uv run scripts/ms-todo-sync.py -v lists
• ✅ uv run scripts/ms-todo-sync.py --debug add "Task"
• ❌ uv run scripts/ms-todo-sync.py lists -v

---

Authentication

Authentication uses a two-step device code flow designed for non-interactive/agent environments.

login get — Get verification code

uv run scripts/ms-todo-sync.py login get

Output example:

✓ Verification code generated

Please visit the following link to log in:
https://microsoft.com/devicelogin

Enter verification code: ABC123XYZ

Verify with command: ms-todo-sync.py login verify

Agent behavior: Present the URL and verification code to the user. Wait for the user to confirm they have completed the browser login before proceeding.

login verify — Complete login

uv run scripts/ms-todo-sync.py login verify

Output on success:

✓ Authentication successful! Login information saved, you will be logged in automatically next time.

Output on failure:

✗ Authentication failed: <error description>

⚠️ This command blocks until Microsoft's server confirms the user completed browser authentication. Do NOT run this until the user confirms they have completed the browser step.

Exit code: 0 on success, 1 on failure.

logout — Clear saved login

uv run scripts/ms-todo-sync.py logout

Only use when the user explicitly asks to switch accounts or clear login data. Under normal circumstances, the token is cached and login is automatic.

---

List Management

lists — List all task lists

uv run scripts/ms-todo-sync.py lists
uv run scripts/ms-todo-sync.py -v lists  # with IDs and dates

Output example:

📋 Task Lists (3 total):

1. Tasks
2. Work
3. Shopping

create-list — Create a new list

uv run scripts/ms-todo-sync.py create-list "<name>"

Argument	Required	Description
name	Yes	Name of the new list

Output: ✓ List created: <name>

delete-list — Delete a list

uv run scripts/ms-todo-sync.py delete-list "<name>" [-y]

Argument/Option	Required	Description
name	Yes	Name of the list to delete
-y, --yes	No	Skip confirmation prompt

⚠️ This is a destructive operation. Without -y, the command will prompt for confirmation. Consider asking the user before deleting important lists.

Output: ✓ List deleted: <name>

---

Task Operations

add — Add a new task

uv run scripts/ms-todo-sync.py add "<title>" [options]

Option	Required	Default	Description
title	Yes	—	Task title (positional argument)
-l, --list	No	(default list)	Target list name. If not specified, uses your Microsoft To Do default list.
-p, --priority	No	normal	Priority: low, normal, high
-d, --due	No	—	Due date. Accepts days from now (3 or 3d) or date (2026-02-15). Note: Only date is supported, not time.
-r, --reminder	No	—	Reminder datetime. Formats: 3h (hours), 2d (days), 2026-02-15 14:30 (date+time with space, needs quotes), 2026-02-15T14:30:00 (ISO format), 2026-02-15 (date only, defaults to 09:00).
-R, --recurrence	No	—	Recurrence pattern. Formats: daily (every day), weekdays (Mon-Fri), weekly (every week), monthly (every month). With interval: daily:2 (every 2 days), weekly:3 (every 3 weeks), monthly:2 (every 2 months). Note: Automatically sets start date.
-D, --description	No	—	Task description/notes
-t, --tags	No	—	Comma-separated tags (e.g., "work,urgent")

Behavior: If the specified list doesn't exist, it will be automatically created.

Output example:

✓ List created: Work
✓ Task added: Complete report

complete — Mark a task as completed

uv run scripts/ms-todo-sync.py complete "<title>" [-l "<list>"]

Option	Required	Default	Description
title	Yes	—	Exact task title
-l, --list	No	(default list)	List name where the task resides. If not specified, uses your default list.

Output: ✓ Task completed: <title>

delete — Delete a task

uv run scripts/ms-todo-sync.py delete "<title>" [-l "<list>"] [-y]

Option	Required	Default	Description
title	Yes	—	Exact task title
-l, --list	No	(default list)	List name. If not specified, uses your default list.
-y, --yes	No	—	Skip confirmation prompt

⚠️ This is a destructive operation. Without -y, the command will prompt for confirmation. For routine cleanup or when user intent is clear, -y can be used to avoid blocking.

Output: ✓ Task deleted: <title>

---

Task Views

tasks — List tasks in a specific list

uv run scripts/ms-todo-sync.py tasks "<list>" [-a]

Option	Required	Default	Description
list	Yes	—	List name (positional argument)
-a, --all	No	—	Include completed tasks (default: only incomplete)

Output example:

📋 Tasks in list "Work" (2 total):

1. [In Progress] Write documentation ⭐
2. [In Progress] Review PR

pending — All incomplete tasks across all lists

uv run scripts/ms-todo-sync.py pending [-g]

Option	Required	Description
-g, --group	No	Group results by list

Output example (with -g):

📋 All incomplete tasks (3 total):

📂 Work:
  [In Progress] Write documentation ⭐
  [In Progress] Review PR

📂 Shopping:
  [In Progress] Buy groceries

today — Tasks due today

uv run scripts/ms-todo-sync.py today

Lists incomplete tasks with due date matching today. Output: 📅 No tasks due today if none found.

overdue — Overdue tasks

uv run scripts/ms-todo-sync.py overdue

Output example:

⚠️  Overdue tasks (1 total):

[In Progress] Submit report ⭐
   List: Work
   Overdue: 3 days

detail — View full task details

uv run scripts/ms-todo-sync.py detail "<title>" [-l "<list>"]

Option	Required	Default	Description
title	Yes	—	Task title (supports partial/fuzzy match)
-l, --list	No	(default list)	List name. If not specified, uses your default list.

When multiple tasks match, returns the most recently modified incomplete task. If all matches are completed, returns the most recently modified completed task.

search — Search tasks by keyword

uv run scripts/ms-todo-sync.py search "<keyword>"

Searches across all lists in both task titles and notes (case-insensitive).

Output example:

🔍 Search res

---

*Content truncated.*