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

> ⚠️ 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>"

Output: ✓ List created: <name>

delete-list — Delete a list

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

> ⚠️ 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]

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>"]

Output: ✓ Task completed: <title>

delete — Delete a task

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

> ⚠️ 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]

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]

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>"]

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 results (1 found):

[In Progress] Write documentation ⭐
   List: Work

stats — Task statistics

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

Output example:

📊 Task Statistics:

  Total lists: 3
  Total tasks: 15
  Completed: 10
  Pending: 5
  High priority: 2
  Overdue: 1

  Completion rate: 66.7%

export — Export all tasks to JSON

uv run scripts/ms-todo-sync.py export [-o "<filename>"]

Output: ✓ Tasks exported to: <filename>

Error Handling

Exit Codes

Common Error Messages

Agent Usage Guidelines

Critical Rules

1. Working directory: Always cd to the directory containing this SKILL.md before running commands.
2. Dependency installation: Before first use or when encountering import errors, run uv sync to ensure all dependencies are installed.
3. Task list organization: When adding tasks:
   - First, run lists to see available task lists
   - If user doesn't specify a list, tasks will be added to their default list (wellknownListName: "defaultList")
   - Intelligently categorize tasks into appropriate lists (e.g., "Work", "Personal", "Shopping")
   - If user mentions a context (work, home, shopping, etc.), use or create an appropriate list
   - Lists will be auto-created if they don't exist, so feel free to use meaningful list names
4. Destructive operations: For delete and delete-list commands:
   - These commands will prompt for confirmation by default (blocking behavior)
   - Use -y flag to skip confirmation ONLY when:
   • User has explicitly requested to delete without confirmation
   • The deletion intent is unambiguous and confirmed through conversation
   • When in doubt, ask the user for confirmation instead of using -y
5. Global option placement: -v and --debug must come BEFORE the subcommand, not after.
6. Do not retry login verify automatically: This command blocks waiting for user browser interaction. Only call it after the user confirms completion.
7. Check login status first: Before performing any task operations, run a lightweight command (e.g., lists) to verify authentication. Handle the "Not logged in" error gracefully.

Recommended Workflow for Agents

1. cd <skill_directory>
2. uv sync                                       # Ensure dependencies are installed (first time or after updates)
3. uv run scripts/ms-todo-sync.py lists          # Test auth & see available lists
   → If fails with exit code 1 ("Not logged in"):
     a. uv run scripts/ms-todo-sync.py login get  # Get code
     b. Present URL + code to user
     c. Wait for user confirmation
     d. uv run scripts/ms-todo-sync.py login verify
4. When adding tasks:
   → Analyze task context from user's description
   → Choose or create appropriate list name:
     - Work-related → "Work" list
     - Personal errands → "Personal" list  
     - Shopping items → "Shopping" list
     - Project-specific → Use project name as list
   → Add task with appropriate list via `-l` option
5. Verify results (e.g., list tasks after adding)

Example task categorization:
- \"Buy milk\" → Shopping list (or default list if no context)
- \"Prepare report for meeting\" → Work list
- \"Call dentist\" → Personal list (or default list)
- \"Review PR for auth service\" → Work or project-specific list

Note: If no list is specified, tasks are added to the user's default Microsoft To Do list.

Task Title Matching

• complete and delete require exact title match.
• detail and search support partial/fuzzy keyword match (case-insensitive).
• When in doubt, use search first to find the exact title, then use it in subsequent commands.

Default List Behavior

When -l is not specified, the tool uses your Microsoft To Do default list (typically "Tasks"). To target a specific list, provide the -l option.

Quick Examples

# Check existing lists first
uv run scripts/ms-todo-sync.py lists

# Add task to specific list (list auto-created if needed)
uv run scripts/ms-todo-sync.py add "Report" -l "Work" -p high -d 3 -D "Q4 financials"

# Add task to default list (no -l option)
uv run scripts/ms-todo-sync.py add "Buy milk"

# Add task with reminder in 2 hours
uv run scripts/ms-todo-sync.py add "Call client" -r 2h

# Add task with specific reminder date and time
uv run scripts/ms-todo-sync.py add "Meeting" -d 2026-03-15 -r "2026-03-15 14:30"

# Add recurring tasks
uv run scripts/ms-todo-sync.py add "Daily standup" -l "Work" -R daily -d 7
uv run scripts/ms-todo-sync.py add "Weekly review" -R weekly -d 2026-02-17
uv run scripts/ms-todo-sync.py add "Gym" -R weekdays -l "Personal"  
uv run scripts/ms-todo-sync.py add "Monthly report" -R monthly -p high -d 30

# Search then complete (use exact title from search results)
uv run scripts/ms-todo-sync.py search "report"
uv run scripts/ms-todo-sync.py complete "Report" -l "Work"

# Delete (use -y only when user intent is clear)
uv run scripts/ms-todo-sync.py delete "Old task" -y

# Views
uv run scripts/ms-todo-sync.py -v pending -g          # all pending, grouped
uv run scripts/ms-todo-sync.py -v detail "report"      # task detail with fuzzy match
uv run scripts/ms-todo-sync.py export -o "backup.json"  # export all