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:

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

1. Tasks
2. Work
3. 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 "