Ms Todo Oauth

---

name: ms-todo-oauth description: > A robust CLI skill to manage Microsoft To Do tasks via Microsoft Graph API. Supports full task lifecycle management including lists, tasks with priorities, due dates, reminders, recurrence patterns, views, search, and data export. Includes comprehensive test suite for reliability. THIS IS A REVISED OAUTH2-BASED VERSION OF ms-todo-sync with AI ASSISTANCE. ALL CREDITS TO THE ORIGINAL AUTHOR. metadata: version: 1.0.3 author: yalonghan@gmaill.com license: MIT License tags: [productivity, task-management, microsoft-todo, cli, graph-api, tested] category: productivity tested: true test_coverage: 29 comprehensive tests

---

ms-todo-oauth

A fully-tested Microsoft To Do command-line client for managing tasks and lists via Microsoft Graph API.

⚠️This is a oauth based script. It contains a generated Azure Client ID and Secret ID

IF YOU WORRIED ABOUT YOUR PRIVACY, CONSIDER REPLACING THEM TO YOUR OWN IN scripts\ms-todo-oauth.py. Just search for values below:

client_id="ca6ec244……

client_secret="TwQ8Q……

✨ Features

✅ Full Task Management: Create, complete, delete, and search tasks

🗂️ List Organization: Create and manage multiple task lists

⏰ Rich Task Options: Priorities, due dates, reminders, descriptions, tags

🔄 Recurring Tasks: Daily, weekly, monthly patterns with custom intervals

📊 Multiple Views: Today, overdue, pending, statistics

🔍 Powerful Search: Find tasks across all lists

💾 Data Export: Export all tasks to JSON

🧪 Fully Tested: 29 comprehensive automated tests

🌐 Unicode Support: Full support for Chinese characters and emojis

Prerequisites

1. Python >= 3.9 must be installed 2. Working directory: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file) 3. Network access: Requires internet access to Microsoft Graph API endpoints 4. Microsoft Account: Personal Microsoft account (Hotmail, Outlook.com) or work/school account 5. Authentication: First-time use requires OAuth2 login via browser. See Authentication section - Token cache: ~/.mstodo_token_cache.json (persists across sessions, auto-refreshed)

Installation & Setup

First-Time Setup

Before using this skill for the first time, dependencies must be installed:

# Navigate to skill directory
cd 
Create a venv in the project (creates '.venv' folder)
python3 -m venv .venv
Activate the venv choose based on platforms:
#- Bash/Zsh: 
source .venv/bin/activate
- Fish: 
source .venv/bin/activate.fish
 - Windows (PowerShell):
.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -r requirements.txt
Alternative (global python env, not recommended):
pip install -r requirements.txt

Dependencies:

msal (Microsoft Authentication Library) - Official Microsoft OAuth library

requests - HTTP client for API calls

Specified in requirements.txt

Environment Verification

After installation, verify the setup:

If using native venv (activate as above):
python3 scripts/ms-todo-oauth.py --help
Expected: Command help text should be displayed

Troubleshooting:

If Python not found, install Python 3.9 or higher from https://python.org

Testing (Optional but Recommended)

Verify all functionality works correctly:

# Run comprehensive automated test suite (29 tests)
python3 test_ms_todo_oauth.py
Expected: All tests pass (100% pass rate)

See Testing section for details.

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 (graph.microsoft.com)

OAuth2 standard authentication flow

No third-party services involved

Command Reference

All commands follow this pattern:

python3 scripts/ms-todo-oauth.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. | | --reauth | Force re-authentication by clearing the token cache and starting fresh login |

> ⚠️ Common mistake: Global options MUST come before the subcommand. > > - ✅ python3 scripts/ms-todo-oauth.py -v lists > - ✅ python3 scripts/ms-todo-oauth.py --debug add "Task" > - ❌ python3 scripts/ms-todo-oauth.py lists -v

---

Authentication

Authentication uses OAuth2 authorization code flow, designed for both interactive and automated environments.

#### login get — Get OAuth2 authorization URL

python3 scripts/ms-todo-oauth.py login get

Output example:

======================================================================
🔐 OAuth2 Authorization Required
======================================================================
Please visit the following URL to authorize the application:
  https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?...
After authorization, you will be redirected to a callback URL.
Copy the 'code' parameter from the callback URL and run:
  ms-todo-oauth.py login verify 
======================================================================

What to do:

1. Open the provided URL in your browser 2. Sign in with your Microsoft account 3. Grant permissions when prompted 4. You'll be redirected to a URL like: http://localhost:8000/callback?code=M.R3_BAY.abc123... 5. Copy the entire code after code= (usually a long string starting with M.R3_BAY.)

Agent behavior: Present the URL to the user and explain they need to:

1. Visit the URL 2. Complete the login 3. Copy the authorization code from the callback URL 4. Provide it to you

#### login verify — Complete login with authorization code

python3 scripts/ms-todo-oauth.py login verify 

Example:

python3 scripts/ms-todo-oauth.py login verify "M.R3_BAY.abc123def456..."

Output on success:

✓ Authentication successful!
✓ Login information saved, you will be logged in automatically next time.

Output on failure:

❌ Token acquisition failed
Error: invalid_grant
Description: AADSTS54005: OAuth2 Authorization code was already redeemed...

Exit code: 0 on success, 1 on failure.

Important notes:

Each authorization code can only be used ONCE

If verification fails, you need to run login get again to get a new code

Once successfully logged in, the token is cached and you won't need to login again unless:

- You run logout - You run --reauth - The token expires and cannot be auto-refreshed

#### logout — Clear saved login

python3 scripts/ms-todo-oauth.py logout

Output: ✓ Login information cleared

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

python3 scripts/ms-todo-oauth.py lists
python3 scripts/ms-todo-oauth.py -v lists  # with IDs and creation dates

Output example:

📋 Task Lists (3 total):
1. 任务
   ID: AQMkADAwATYwMAItYTQwZC04OThhLTAwAi0wMAoALgAAA0QJKpxW32BIsIlHaM...
   Created: 2024-12-15T08:30:00Z
2. Work
3. Shopping

#### create-list — Create a new list

python3 scripts/ms-todo-oauth.py create-list ""

| Argument | Required | Description | | -------- | -------- | ----------------------------------------------- | | name | Yes | Name of the new list (supports Unicode/Chinese) |

Example:

python3 scripts/ms-todo-oauth.py create-list "项目 A"

Output: ✓ List created: 项目 A

#### delete-list — Delete a list

python3 scripts/ms-todo-oauth.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. All tasks in the list will be deleted. Consider asking the user before deleting important lists.

Output: ✓ List deleted:

Exit code: 1 if list not found, 0 on success

---

Task Operations

#### add — Add a new task

python3 scripts/ms-todo-oauth.py add "