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:

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:

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: