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 <path-to-ms-todo-oauth>

# 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> [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 <authorization_code>

======================================================================

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 <authorization_code>

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

| 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 "<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. 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 "<title>" [options]

| Option | Required | Default | Description |

| --------------------- | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| title | Yes | — | Task title (positional argument, supports Unicode/Chinese/emojis) |

| -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 by Microsoft To Do API, not time. |

| -r, --reminder | No | — | Reminder datetime. Formats:3h (hours from now), 2d (days from now), 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). |

| -D, --description | No | — | Task description/notes (supports multiline with quotes) |

| -t, --tags | No | — | Comma-separated tags/categories (e.g.,"work,urgent") |

| --create-list | No | False | Create the list if it doesn't exist (deprecated, lists auto-create now) |

Auto-created lists: If the specified list doesn't exist, it will be automatically created.

Output example:

✓ Task added: Complete report

With recurrence:

✓ Task added: Daily standup
🔄 Recurring task created

Examples:

# Simple task
python3 scripts/ms-todo-oauth.py add "Buy milk" -l "Shopping"

# High priority task due in 3 days
python3 scripts/ms-todo-oauth.py add "Submit report" -l "Work" -p high -d 3

# Task with reminder in 2 hours
python3 scripts/ms-todo-oauth.py add "Call client" -r 2h

# Task with specific date and time reminder
python3 scripts/ms-todo-oauth.py add "Meeting" -d 2026-03-15 -r "2026-03-15 14:30"

# Daily recurring task
python3 scripts/ms-todo-oauth.py add "Daily standup" -l "Work" -R daily

# Weekday recurring task  
python3 scripts/ms-todo-oauth.py add "Gym" -R weekdays -l "Personal"

# Task with all options
python3 scripts/ms-todo-oauth.py add "Project Review" \
  -l "Work" \
  -p high \
  -d 7 \
  -r "2026-02-20 14:00" \
  -D "Review Q1 deliverables and prepare presentation" \
  -t "work,important,meeting"

# Chinese task with emoji
python3 scripts/ms-todo-oauth.py add "🎉 完成项目" -l "任务" -p high

complete — Mark a task as completed

python3 scripts/ms-todo-oauth.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 |

Title matching: Requires exact match. If unsure of exact title, use search first.

Output: ✓ Task completed: