Ms Todo Oauth

Manage Microsoft To Do lists and tasks through a local Python CLI backed by Microsoft Graph OAuth. Use when an agent needs to inspect, add, complete, delete, search, export, or summarize Microsoft To Do tasks, including priorities, due dates, reminders, recurrence, and list selection. Requires local dependency setup and an interactive OAuth authorization-code login on first use.

Nathan_at_GH@nathanatgit

Install

openclaw skills install @nathanatgit/ms-todo-oauth

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:

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

Recommended handling:

Register your own app at portal.azure.com: Microsoft Entra ID > App registrations > New registration.
For personal Microsoft accounts only, select "Personal Microsoft accounts only". For broader use, select the account type that matches your target users.
Add Microsoft Graph delegated permission Tasks.ReadWrite; add Tasks.ReadWrite.Shared only if shared-list access is needed.
Generate a client secret under Certificates & secrets.
Set MS_TODO_CLIENT_ID and MS_TODO_CLIENT_SECRET, or pass --client-id and --client-secret before the subcommand.
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

Python >= 3.9 must be installed
Dependencies from requirements.txt: msal and requests
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
Microsoft Account: Personal Microsoft account (Hotmail, Outlook.com) or work/school account
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.

bash

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

bash

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

bash

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

text

python 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
`--client-id`	Azure app client ID. Overrides `MS_TODO_CLIENT_ID` and the built-in fallback. Must be placed BEFORE the subcommand.
`--client-secret`	Azure app client secret. Overrides `MS_TODO_CLIENT_SECRET` and the built-in fallback. Must be placed BEFORE the subcommand.
`--tenant-id`	Azure tenant ID or account type. Defaults to `MS_TODO_TENANT_ID` or `consumers`. Must be placed BEFORE the subcommand.

⚠️ 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 "<id>" --client-secret "<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

bash

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

Output example:

text

======================================================================
🔐 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:

Open the provided URL in your browser
Sign in with your Microsoft account
Grant permissions when prompted
You'll be redirected to a URL like: http://localhost:8000/callback?code=M.R3_BAY.abc123...
If the browser shows that localhost:8000 cannot be reached, that is expected.
Copy either the full callback URL or the entire code value after code=.
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:

Visit the URL
Complete the login
Copy the authorization code from the callback URL
Provide it to you

`login verify` — Complete login with authorization code

bash

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

Example:

bash

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:

text

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

Output on failure:

text

❌ 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

bash

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

bash

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

Output example:

text

📋 Task Lists (3 total):

1. 任务
   ID: AQMkADAwATYwMAItYTQwZC04OThhLTAwAi0wMAoALgAAA0QJKpxW32BIsIlHaM...
   Created: 2024-12-15T08:30:00Z
2. Work
3. Shopping

`create-list` — Create a new list

bash

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

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

Example:

bash

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

Output: ✓ List created: 项目 A

`delete-list` — Delete a list

bash

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

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

Task Operations

`add` — Add a new task

bash

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

text

✓ Task added: Complete report

With recurrence:

text

✓ Task added: Daily standup
🔄 Recurring task created

Examples:

bash

# 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

bash

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

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

`delete` — Delete a task

bash

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

Option	Required	Default	Description
`title`	Yes	—	Exact task title
`-l, --list`	No	(default list)	List name where the task resides
`-y, --yes`	No	—	Skip confirmation prompt

⚠️ Destructive operation. Without -y, will prompt for confirmation.

Output: ✓ Task deleted: <title>

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

Task Views

`tasks` — List tasks in a specific list

bash

python scripts/ms-todo-oauth.py tasks "<list>" [-a]

Option	Required	Description
`list`	Yes	List name (exact match)
`-a, --all`	No	Include completed tasks (default: incomplete only)

Output example:

text

📋 Tasks in list "Work" (2 total):

1. [In Progress] Write documentation ⭐
2. [In Progress] Review PR

With -a flag:

text

📋 Tasks in list "Work" (3 total):

1. [In Progress] Write documentation ⭐
2. [Completed] Submit report
3. [In Progress] Review PR

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

`pending` — All incomplete tasks across all lists

bash

python scripts/ms-todo-oauth.py pending [-g]

Option	Required	Description
`-g, --group`	No	Group results by list

Output example (with -g):

text

📋 All incomplete tasks (3 total):

📂 Work:
  [In Progress] Write documentation ⭐
  [In Progress] Review PR

📂 Shopping:
  [In Progress] Buy groceries

Without -g:

text

📋 All incomplete tasks (3 total):

[In Progress] Write documentation ⭐
   List: Work
[In Progress] Review PR
   List: Work
[In Progress] Buy groceries
   List: Shopping

`today` — Tasks due today

bash

python scripts/ms-todo-oauth.py today

Lists incomplete tasks with due date matching today's date.

Output example:

text

📅 Tasks due today (2 total):

[In Progress] Submit report ⭐
   List: Work
[In Progress] Buy groceries
   List: Shopping

If no tasks: 📅 No tasks due today

`overdue` — Overdue tasks

bash

python scripts/ms-todo-oauth.py overdue

Lists incomplete tasks past their due date, sorted by days overdue.

Output example:

text

⚠️  Overdue tasks (1 total):

[In Progress] Submit report ⭐
   List: Work
   Overdue: 3 days

If no overdue tasks: ✓ No overdue tasks

`detail` — View full task details

bash

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

Option	Required	Default	Description
`title`	Yes	—	Task title (supportspartial/fuzzy match)
`-l, --list`	No	(default list)	List name

Fuzzy matching: Matches tasks containing the search string (case-insensitive).

When multiple tasks match:

Prefers incomplete tasks over completed
Returns most recently modified task

Output example:

text

============================================================
📌 Task Details
============================================================

📋 Title: Complete Q1 Report
🔖 Status: [In Progress]
⚡ Priority: ⭐ High
📅 Created: 2026-01-15 08:30:00
📝 Modified: 2026-02-10 14:22:00
⏰ Due: 2026-02-20 00:00:00
🔔 Reminder: 2026-02-20 09:00:00

📝 Notes:
- Review sales figures
- Include charts
- Prepare for board meeting

🏷️  Categories: work, important, Q1

🔄 Recurrence:
   Every week on Monday
   Start date: 2026-02-17
   No end date

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

`search` — Search tasks by keyword

bash

python scripts/ms-todo-oauth.py search "<keyword>"

Searches across all lists in both task titles and descriptions (case-insensitive).

Output example:

text

🔍 Search results for "report" (2 found):

[In Progress] Complete Q1 Report ⭐
   List: Work
   Notes: Review sales figures...

[Completed] Submit weekly report
   List: Work

`stats` — Task statistics

bash

python scripts/ms-todo-oauth.py stats

Shows aggregate statistics across all lists.

Output example:

text

📊 Task Statistics:

  Total lists: 3
  Total tasks: 15
  Completed: 10
  Pending: 5
  High priority: 2
  Overdue: 1

  Completion rate: 66.7%

`export` — Export all tasks to JSON

bash

python scripts/ms-todo-oauth.py export [-o "<filename>"]

Option	Required	Default	Description
`-o, --output`	No	`todo_export.json`	Output file path

Exports complete task data from all lists in JSON format.

Output: ✓ Tasks exported to: <filename>

JSON structure:

json

{
  "Work": [
    {
      "id": "AQMkADAwATYwMAItYTQw...",
      "title": "Complete report",
      "status": "notStarted",
      "importance": "high",
      "createdDateTime": "2026-01-15T08:30:00Z",
      "dueDateTime": {
        "dateTime": "2026-02-20T00:00:00.0000000",
        "timeZone": "UTC"
      },
      "body": {
        "content": "Review Q1 numbers",
        "contentType": "text"
      },
      "categories": ["work", "important"]
    }
  ],
  "Shopping": [...]
}

Error Handling

Exit Codes

Code	Meaning
`0`	Success
`1`	Failure (not logged in, API error, invalid arguments, resource not found)
`2`	Invalid command-line arguments

Common Error Messages

Error	Cause	Resolution
`❌ Not logged in`	No cached token or token expired	Run `login get` then `login verify <code>`
`ModuleNotFoundError: No module named 'msal'`	Dependencies not installed	Run `python -m pip install -r requirements.txt` or `pip install -r requirements.txt`
`❌ List not found: <name>`	Specified list does not exist	Check list name with `lists` command. Note: exact match required.
`❌ Task not found: <name>`	No task with exact matching title	Use `search` to find exact title, or `tasks "<list>"` to list all tasks
`❌ Error: Invalid isoformat string`	DateTime parsing error	This should not occur in the current unreleased maintenance state. If you see this, report as bug.
`❌ Error: Unsupported HTTP method`	Internal API error	This should not occur in the current unreleased maintenance state. If you see this, report as bug.
`❌ Error: <API error message>`	Microsoft Graph API error	Retry; check network; use `--debug` for full details
`Network error` / `Connection timeout`	No internet or API unreachable	Check network connection; verify access to graph.microsoft.com

Testing

This skill includes a comprehensive test suite to ensure reliability.

Automated Testing

Run the full test suite:

bash

cd <skill-directory>
python scripts/test_ms_todo_oauth.py

Run only non-destructive CLI/configuration checks:

bash

python scripts/test_ms_todo_oauth.py --preflight-only

Prerequisites:

Must be authenticated (logged in) before running tests
Internet connection required
Approximately 2-3 minutes to complete

Test Coverage (33 tests):

✅ Authentication (login/logout)
✅ CLI setup, credential override, and authorization-code normalization preflight checks
✅ List management (create, delete, list)
✅ Basic task operations (add, complete, delete, list)
✅ Task options (priorities, due dates, reminders, descriptions, tags)
✅ Recurring tasks (daily, weekly, weekdays, monthly, custom intervals)
✅ Task views (today, overdue, pending, search, stats)
✅ Data export and validation
✅ Error handling (non-existent resources)
✅ Unicode support (Chinese characters, emojis)

Expected output:

text

========================================================================
TEST SUMMARY
========================================================================

Total tests: 33
Passed: 29
Failed: 0
Pass rate: 100.0%

========================================================================
🎉 ALL TESTS PASSED! 🎉
========================================================================

Manual Testing

For manual verification, see MANUAL_TEST_CHECKLIST.txt which provides:

Step-by-step test procedures
Expected outcomes
9 test categories covering all functionality

Test Cleanup

The automated test suite:

Creates a temporary test list (e.g., 🧪 Test List 14:23:45)
Runs all tests in isolation
Deletes the test list on completion
Cleans up any temporary files

If tests are interrupted, you may need to manually delete leftover test lists.

Agent Usage Guidelines

Critical Rules

Working directory: Always cd to the directory containing this SKILL.md before running commands.
Dependency installation: Before first use or when encountering import errors, run python -m pip install -r requirements.txt to ensure all dependencies are installed.
Check authentication first: Before any operation, verify authentication status:
bash
```
python scripts/ms-todo-oauth.py lists
```
If this returns "Not logged in" error (exit code 1), initiate the login flow.
Task list organization: When adding tasks:
- First, run lists to see available task lists
- If user doesn't specify a list, tasks will be added to their default list (usually "Tasks" or "任务")
- Intelligently categorize tasks into appropriate lists:
  - Work tasks → "Work" list
  - Personal errands → "Personal" or default list
  - Shopping → "Shopping" list
  - Project-specific → Use project name as list
- Lists will be auto-created if they don't exist
- Support Chinese list names and Unicode characters
Destructive operations: For delete and delete-list:
- These commands prompt for confirmation by default (blocking behavior)
- Use -y flag ONLY when:
  - User has explicitly requested to delete without confirmation
  - The deletion intent is unambiguous and confirmed through conversation
- When in doubt, ask the user for confirmation instead of using -y
- These operations return exit code 1 on failure (resource not found)
Global option placement: -v, --debug, --reauth, --client-id, --client-secret, and --tenant-id must come BEFORE the subcommand:
- ✅ python scripts/ms-todo-oauth.py -v lists
- ✅ python scripts/ms-todo-oauth.py --client-id "<id>" --client-secret "<secret>" lists
- ❌ python scripts/ms-todo-oauth.py lists -v
Login flow:
- Do NOT call login verify until user confirms they've completed browser authentication
- Each authorization code can only be used once
- If verify fails, you must run login get again for a new code
Error handling:
- Check exit codes: 0 = success, 1 = failure, 2 = invalid arguments
- Parse error messages to provide helpful guidance
- Use --debug flag when troubleshooting API issues

Recommended Workflow for Agents

text

Step 1: Setup and Authentication Check
---------------------------------------
cd <skill_directory>
python -m pip install -r requirements.txt                                       # Ensure dependencies (first time only)
python scripts/ms-todo-oauth.py lists          # Test auth & see available lists

If exit code is 1 and output contains "Not logged in":
  a. python scripts/ms-todo-oauth.py login get
  b. Present URL to user
  c. Explain: "Visit this URL, login, and copy the 'code' parameter from callback URL"
  d. Wait for user to provide authorization code
  e. python scripts/ms-todo-oauth.py login verify "<code>"
  f. Verify success (exit code 0)

Step 2: Task Analysis and List Selection
-----------------------------------------
When user requests to add task(s):
  a. Analyze task context from user's description
  b. Review available lists (from Step 1 output)
  c. Choose appropriate list or use default:
     - Work-related → "Work"
     - Personal errands → "Personal" or default
     - Shopping items → "Shopping"
     - Project-specific → "<ProjectName>"
  d. If list doesn't exist, it will be auto-created

Step 3: Execute Operation
--------------------------
Add task with appropriate options:
  python scripts/ms-todo-oauth.py add "Task Title" \
    -l "Work" \
    -p high \
    -d 3 \
    -r 2h \
    -D "Detailed description" \
    -t "tag1,tag2"

Step 4: Verify and Report
--------------------------
Check exit code:
  - 0: Success → Confirm to user
  - 1: Failure → Parse error, provide guidance
  - 2: Invalid args → Fix command syntax

Optionally verify:
  python scripts/ms-todo-oauth.py tasks "<list>"  # Show updated list

Task Title Matching Rules

Exact match required: complete, delete commands
Partial/fuzzy match supported: detail, search commands
Case-insensitive: All search operations
Best practice: Use search first to find exact title, then use it in subsequent commands

Example workflow:

bash

# Find task with fuzzy search
python scripts/ms-todo-oauth.py search "report"
# Output shows: "Complete Q1 Report"

# Use exact title from search results
python scripts/ms-todo-oauth.py complete "Complete Q1 Report" -l "Work"

Default List Behavior

When -l is not specified, operations use the Microsoft To Do default list
The default list is typically named "Tasks" (English) or "任务" (Chinese)
To target a specific list, always provide -l "<ListName>"

Example Task Categorization

User request: "Add these tasks: buy milk, finish report, call dentist"

Agent approach:

bash

# First check available lists
python scripts/ms-todo-oauth.py lists

# Categorize intelligently:
python scripts/ms-todo-oauth.py add "Buy milk" -l "Shopping"
python scripts/ms-todo-oauth.py add "Finish report" -l "Work" -p high -d 2
python scripts/ms-todo-oauth.py add "Call dentist" -l "Personal"
# Or use default list if no specific context: add "Call dentist"

Quick Reference

Common Workflows

Daily task review:

bash

python scripts/ms-todo-oauth.py today          # Check today's tasks
python scripts/ms-todo-oauth.py overdue        # Check overdue tasks
python scripts/ms-todo-oauth.py -v pending -g  # Review all pending, grouped

Adding various task types:

bash

# Simple task (default list)
python scripts/ms-todo-oauth.py add "Buy milk"

# Work task with priority and deadline
python scripts/ms-todo-oauth.py add "Quarterly review" -l "Work" -p high -d 7

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

# Detailed task with all options
python scripts/ms-todo-oauth.py add "Project meeting" \
  -l "Work" \
  -p high \
  -d 2026-03-15 \
  -r "2026-03-15 14:30" \
  -D "Discuss Q1 goals and resource allocation" \
  -t "meeting,important,Q1"

# Recurring tasks
python scripts/ms-todo-oauth.py add "Daily standup" -R daily -l "Work"
python scripts/ms-todo-oauth.py add "Weekly review" -R weekly -d 7
python scripts/ms-todo-oauth.py add "Gym" -R weekdays -l "Personal"
python scripts/ms-todo-oauth.py add "Monthly report" -R monthly -p high

Task completion workflow:

bash

# Search for task
python scripts/ms-todo-oauth.py search "report"

# Complete using exact title from search results
python scripts/ms-todo-oauth.py complete "Quarterly review" -l "Work"

Data management:

bash

# Export for backup
python scripts/ms-todo-oauth.py export -o "backup_$(date +%Y%m%d).json"

# View statistics
python scripts/ms-todo-oauth.py stats

Changelog

Unreleased

Normalize login verify input so URL-encoded codes and full callback URLs work
Added preflight coverage for authorization-code URL decoding and callback extraction
Updated login instructions to quote authorization codes in the shell
Added non-destructive preflight tests for help output and credential resolution
Added --preflight-only mode for safe local verification without live To Do changes
Updated documented test count to 33 tests
Added credential override support through CLI options and environment variables
Kept the existing built-in OAuth app credentials as fallback defaults
Made the skill description more agent-neutral for OpenClaw-style usage
Fixed setup workflow to match the existing requirements.txt-only package layout
Replaced stale uv sync guidance with active Python/Conda installation commands
Corrected automated test paths and OAuth callback guidance
Added stronger handling guidance for embedded OAuth app credentials

Version 1.0.5 (Current)

✅ Fixed: DateTime parsing errors (Microsoft's 7-decimal format)
✅ Fixed: HTTP method parameter order bugs
✅ Fixed: Missing start_date parameter in create_task()
✅ Fixed: Missing complete_task() method
✅ Fixed: Error exit codes now correctly return 1 on failure
✅ Added: Comprehensive test suite (33 automated tests)
✅ Added: Better error messages and troubleshooting
✅ Improved: OAuth2 authentication flow documentation
✅ Improved: Unicode and emoji support documentation
✅ Improved: Agent usage guidelines

Version 1.0.2 (Previous)

Initial release with OAuth2 authentication
Basic task and list management
Recurring task support
Multiple task views
Data export functionality

Troubleshooting

Authentication Issues

Problem: ❌ Not logged in

Solution: Run login get, complete browser flow, then login verify <code>

Problem: ❌ Token acquisition failed: invalid_grant

Cause: Authorization code already used or expired
Solution: Run login get again to get a fresh code

Problem: Login worked but now getting "Not logged in" again

Cause: Token expired and auto-refresh failed

Solution: Run --reauth to force fresh login:

bash

python scripts/ms-todo-oauth.py --reauth lists

Import/Dependency Issues

Problem: ModuleNotFoundError: No module named 'msal'

Solution: Install dependencies: python -m pip install -r requirements.txt or pip install -r requirements.txt

Problem: uv: command not found

Solution: Install uv: pip install uv

API/Network Issues

Problem: Connection timeout or network errors

Check: Internet connection
Check: Can you access https://graph.microsoft.com in browser?
Try: Using --debug flag to see full API request/response

Problem: Unexpected API errors

Try: Re-authenticate: python scripts/ms-todo-oauth.py --reauth lists
Try: Debug mode: python scripts/ms-todo-oauth.py --debug <command>

Task/List Not Found

Problem: ❌ Task not found: <title>

Solution: Use search to find exact title
Note: complete and delete require exact title match

Problem: ❌ List not found: <name>

Solution: Run lists to see exact list names
Note: List names are case-sensitive

Test Failures

Problem: Tests failing with datetime errors

Solution: Ensure the current unreleased maintenance fixes are present
Check: Verify _parse_ms_datetime() helper function exists

Problem: Tests failing with "Not logged in"

Solution: Authenticate before running tests:

bash

python scripts/ms-todo-oauth.py login get
# Complete browser flow
python scripts/ms-todo-oauth.py login verify "<code-or-callback-url>"
# Then run tests
python scripts/test_ms_todo_oauth.py

Additional Resources

Test Suite: scripts/test_ms_todo_oauth.py - Automated tests
Manual Tests: scripts/MANUAL_TEST_CHECKLIST.txt - Step-by-step testing guide
Quick Reference: scripts/QUICK_REFERENCE.txt - Command cheat sheet

Support & Contributing

Reporting Issues:

Provide error message and command used
Include output from --debug flag if applicable
Note your Python version: python3 --version
Note your OS: Windows/Mac/Linux

Testing New Features:

Always run the test suite after code changes
Add new test cases to scripts/test_ms_todo_oauth.py for new features
Update MANUAL_TEST_CHECKLIST.txt with manual test procedures

License

MIT License - See LICENSE file for details

Version: 1.0.5 Last Updated: 2026-02-13 Status: ✅ Fully Tested & Production Ready

Ms Todo Oauth

Install

ms-todo-oauth

Security and OAuth App Credentials

✨ Features

Prerequisites

Installation & Setup

First-Time Setup

Environment Verification

Testing (Optional but Recommended)

Security Notes

Command Reference

Global Options

Authentication

login get — Get OAuth2 authorization URL

login verify — Complete login with authorization code

logout — Clear saved login

List Management

lists — List all task lists

create-list — Create a new list

delete-list — Delete a list

Task Operations

add — Add a new task

complete — Mark a task as completed

delete — Delete a task

Task Views

tasks — List tasks in a specific list

pending — All incomplete tasks across all lists

today — Tasks due today

overdue — Overdue tasks

detail — View full task details

search — Search tasks by keyword

stats — Task statistics

export — Export all tasks to JSON

Error Handling

Exit Codes

Common Error Messages

Testing

Automated Testing

Manual Testing

Test Cleanup

Agent Usage Guidelines

Critical Rules

Recommended Workflow for Agents

Task Title Matching Rules

Default List Behavior

Example Task Categorization

Quick Reference

Common Workflows

Changelog

Unreleased

Version 1.0.5 (Current)

Version 1.0.2 (Previous)

Troubleshooting

Authentication Issues

Import/Dependency Issues

API/Network Issues

Task/List Not Found

Test Failures

Additional Resources

Support & Contributing

License

Related skills

`login get` — Get OAuth2 authorization URL

`login verify` — Complete login with authorization code

`logout` — Clear saved login

`lists` — List all task lists

`create-list` — Create a new list

`delete-list` — Delete a list

`add` — Add a new task

`complete` — Mark a task as completed

`delete` — Delete a task

`tasks` — List tasks in a specific list

`pending` — All incomplete tasks across all lists

`today` — Tasks due today

`overdue` — Overdue tasks

`detail` — View full task details

`search` — Search tasks by keyword

`stats` — Task statistics

`export` — Export all tasks to JSON