ms-todo-sync

---

name: ms-todo-sync description: > A CLI skill to manage Microsoft To Do tasks via Microsoft Graph API. Supports listing, creating, completing, deleting, searching tasks and lists, viewing overdue/today/pending tasks, and exporting data. metadata: version: 1.0.2 author: xiaoski@qq.com license: MIT License tags: [productivity, task-management, microsoft-todo, cli] category: productivity

---

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 
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_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: 

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

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