ms-todo-oauth

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

Security and OAuth App Credentials

This skill uses OAuth authorization-code login through Microsoft Graph. The script has built-in fallback Azure app credentials, but agents should prefer caller-provided credentials when available. Treat any committed client secret as public and rotate or revoke it before distributing this skill for sensitive accounts.

Credential precedence:

1. Global CLI options: --client-id, --client-secret, --tenant-id
2. Environment variables: MS_TODO_CLIENT_ID, MS_TODO_CLIENT_SECRET, MS_TODO_TENANT_ID
3. Built-in fallback values in scripts/ms-todo-oauth.py

Recommended handling:

1. Register your own app at portal.azure.com: Microsoft Entra ID > App registrations > New registration.
2. For personal Microsoft accounts only, select "Personal Microsoft accounts only". For broader use, select the account type that matches your target users.
3. Add Microsoft Graph delegated permission Tasks.ReadWrite; add Tasks.ReadWrite.Shared only if shared-list access is needed.
4. Generate a client secret under Certificates & secrets.
5. Set MS_TODO_CLIENT_ID and MS_TODO_CLIENT_SECRET, or pass --client-id and --client-secret before the subcommand.
6. If the existing secret has been published, rotate or revoke it in Azure.

Do not print or paste client secrets in user-facing responses or logs.

✨ 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: 33 comprehensive automated tests
• 🌐 Unicode Support: Full support for Chinese characters and emojis

Prerequisites

1. Python >= 3.9 must be installed
2. Dependencies from requirements.txt: msal and requests
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. Microsoft Account: Personal Microsoft account (Hotmail, Outlook.com) or work/school account
6. 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. This repository does not include pyproject.toml or uv.lock, so do not use uv sync unless those files are added later.

# Navigate to skill directory
cd <path-to-ms-todo-oauth>

# Install dependencies into the active Python/Conda environment
python -m pip install -r requirements.txt

# Optional: set your own Azure app credentials for the current PowerShell session
$env:MS_TODO_CLIENT_ID = "<your-client-id>"
$env:MS_TODO_CLIENT_SECRET = "<your-client-secret>"
$env:MS_TODO_TENANT_ID = "consumers"

# Optional uv one-shot without a project file
uv run --with-requirements requirements.txt python scripts/ms-todo-oauth.py --help

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:

# Check if Python can import dependencies and load the script
python scripts/ms-todo-oauth.py --help

# Expected: Command help text should be displayed

Troubleshooting:

• If Python not found, install Python 3.9 or higher or activate the environment where dependencies were installed.
• If script fails with import errors, run python -m pip install -r requirements.txt in the same environment used to run the script.

Testing (Optional but Recommended)

Verify all functionality works correctly:

# Run comprehensive automated test suite (33 tests)
python scripts/test_ms_todo_oauth.py

# Run only non-destructive CLI/configuration checks
python scripts/test_ms_todo_oauth.py --preflight-only

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

python scripts/ms-todo-oauth.py [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]

Global Options

> ⚠️ Common mistake: Global options MUST come before the subcommand.

>

> - ✅ python scripts/ms-todo-oauth.py -v lists

> - ✅ python scripts/ms-todo-oauth.py --debug add "Task"

> - ✅ python scripts/ms-todo-oauth.py --client-id "" --client-secret "" lists

> - ❌ python 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

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

  python scripts/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. If the browser shows that localhost:8000 cannot be reached, that is expected.
6. Copy either the full callback URL or the entire code value after code=.
7. Quote the value in the shell because Microsoft authorization codes can contain punctuation.

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

python scripts/ms-todo-oauth.py login verify "<authorization_code_or_callback_url>"

Example:

python scripts/ms-todo-oauth.py login verify "M.R3_BAY.abc123def456..."
python scripts/ms-todo-oauth.py login verify "http://localhost:8000/callback?code=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

python 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

python scripts/ms-todo-oauth.py lists
python 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

python scripts/ms-todo-oauth.py create-list "<name>"

Example:

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

Output: ✓ List created: 项目 A

delete-list — Delete a list

python scripts/ms-todo-oauth.py delete-list "<name>" [-y]

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

python scripts/ms-todo-oauth.py add "<title>" [options]

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
python scripts/ms-todo-oauth.py add "Buy milk" -l "Shopping"

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

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

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

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

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

# Task with all options
python 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
python scripts/ms-todo-oauth.py add "🎉 完成项目" -l "任务" -p high

complete — Mark a task as completed

python scripts/ms-todo-oauth.py complete "<title>" [-l "<list>"]

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

Output: ✓ Task completed: