ms-todo-sync — ms-todo-同步

ms-todo-同步

A Microsoft To Do command-line 命令行工具ent for managing tasks and 列出s via Microsoft Graph API.

Prerequisites Python >= 3.9 must be 安装ed. uv (Python package 管理器) must be 安装ed. 安装 via pip 安装 uv or see https://docs.astral.sh/uv/. Working directory: All commands MUST be 运行 from the root of this 技能 (the directory contAIning this 技能.md file). Network 访问: Requires internet 访问 to Microsoft Graph API 端点s. Authentication: First-time use requires interactive 记录in via browser. See Authentication section. 令牌 缓存: ~/.mstodo_令牌_缓存.json (persists across 会话s, auto-refreshed) Device flow 缓存: ~/.mstodo_device_flow.json (temporary) 安装ation & 设置up First-Time 设置up

Before using this 技能 for the first time, dependencies must be 安装ed:

# Navigate to 技能 directory cd

# 安装 dependencies using uv (recommended - 创建s isolated 环境) uv 同步

# Alternative: 安装 dependencies with pip (uses global/active Python 环境) pip 安装 -r requirements.txt

Dependencies:

Requires msal (Microsoft Authentication 库) and 请求s Specified in requirements.txt uv 创建s an isolated virtual 环境 to avoid conflicts 环境 Verification

After 安装ation, 验证 the 设置up:

# 检查 if uv can find the script uv 运行 scripts/ms-todo-同步.py --help

# Expected: Command help text should be displayed

Troubleshooting:

If uv: command not found, 安装 uv: pip 安装 uv If Python not found, 安装 Python 3.9 or higher from https://python.org If script fAIls with 导入 errors, ensure dependencies are 安装ed: uv 同步 or pip 安装 -r requirements.txt Security Notes Uses official Microsoft Graph API via Microsoft's msal 库 All code is plAIn Python (.py files), readable and 审计able 令牌s stored locally in ~/.mstodo_令牌_缓存.json All API calls go directly to Microsoft 端点s Command Reference

All commands follow this pattern:

uv 运行 scripts/ms-todo-同步.py [GLOBAL_OPTIONS] [COMMAND_OPTIONS]

Global Options Option Description -v, --verbose Show detAIled in格式化ion (IDs, dates, notes). Must be placed BEFORE the subcommand. --调试 Enable 调试 mode to display API 请求s and 响应s. Useful for troubleshooting. Must be placed BEFORE the subcommand.

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

✅ uv 运行 scripts/ms-todo-同步.py -v 列出s ✅ uv 运行 scripts/ms-todo-同步.py --调试 添加 "Task" ❌ uv 运行 scripts/ms-todo-同步.py 列出s -v Authentication

Authentication uses a two-step device code flow de签名ed for non-interactive/代理 环境s.

记录in 获取 — 获取 verification code uv 运行 scripts/ms-todo-同步.py 记录in 获取

输出 example:

✓ Verification code 生成d

Please visit the following link to 记录 in: https://microsoft.com/device记录in

Enter verification code: ABC123XYZ

验证 with command: ms-todo-同步.py 记录in 验证

代理 behavior: Present the URL and verification code to the user. WAIt for the user to confirm they have completed the browser 记录in before proceeding.

记录in 验证 — Complete 记录in uv 运行 scripts/ms-todo-同步.py 记录in 验证

输出 on 成功:

✓ Authentication 成功ful! 记录in in格式化ion saved, you will be 记录ged in automatically next time.

输出 on 失败:

✗ Authentication fAIled:

⚠️ This command blocks until Microsoft's server confirms the user completed browser authentication. Do NOT 运行 this until the user confirms they have completed the browser step.

Exit code: 0 on 成功, 1 on 失败.

记录out — Clear saved 记录in uv 运行 scripts/ms-todo-同步.py 记录out

Only use when the user explicitly asks to switch accounts or clear 记录in data. Under normal circumstances, the 令牌 is 缓存d and 记录in is automatic.

列出 Management 列出s — 列出 all task 列出s uv 运行 scripts/ms-todo-同步.py 列出s uv 运行 scripts/ms-todo-同步.py -v 列出s # with IDs and dates

输出 example:

📋 Task 列出s (3 total):

• Tasks
• Work
• Shopping

创建-列出 — 创建 a new 列出 uv 运行 scripts/ms-todo-同步.py 创建-列出 ""

Argument Required Description name Yes Name of the new 列出

输出: ✓ 列出 创建d:

删除-列出 — 删除 a 列出 uv 运行 scripts/ms-todo-同步.py 删除-列出 "" [-y]

Argument/Option Required Description name Yes Name of the 列出 to 删除 -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 导入ant 列出s.

输出: ✓ 列出 删除d:

Task Operations 添加 — 添加 a new task uv 运行 scripts/ms-todo-同步.py 添加 "