---

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: [email protected] 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

• Python >= 3.9 must be installed.

• uv (Python package manager) must be installed. Install via pip install uv or see https://docs.astral.sh/uv/.

• Working directory: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file).

• Network access: Requires internet access to Microsoft Graph API endpoints.

• 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: ``bash

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: `bash

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 `bash 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 `bash 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 `bash 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 `bash 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):

• Tasks

• Work

• Shopping

` #### create-list — Create a new list `bash 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 `bash 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 `bash uv run scripts/ms-todo-sync.py add "