ms-todo-sync

A CLI skill to manage Microsoft To Do tasks via Microsoft Graph API. Supports listing, creating, completing, deleting, searching tasks and lists, viewing overdue/today/pending tasks, and exporting data.

# ms-todo-sync

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

## Prerequisites

1. **Python >= 3.9** must be installed.
2. **uv** (Python package manager) must be installed. Install via `pip install uv` or see https://docs.astral.sh/uv/.
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. **Authentication**: First-time use requires interactive login via browser. See [Authentication](#authentication) section.
   - **Token cache**: `~/.mstodo_token_cache.json` (persists across sessions, auto-refreshed)
   - **Device flow cache**: `~/.mstodo_device_flow.json` (temporary)

## Installation & Setup

### First-Time Setup

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

```bash
# Navigate to skill directory
cd <path-to-ms-todo-sync>

# Install dependencies using uv (recommended - creates isolated environment)
uv sync

# Alternative: Install dependencies with pip (uses global/active Python environment)
pip install -r requirements.txt
```

**Dependencies:**
- Requires `msal` (Microsoft Authentication Library) and `requests`
- Specified in `requirements.txt`
- `uv` creates an isolated virtual environment to avoid conflicts

### Environment Verification

After installation, verify the setup:

```bash
# Check if uv can find the script
uv run scripts/ms-todo-sync.py --help

# Expected: Command help text should be displayed
```

**Troubleshooting:**
- If `uv: command not found`, install uv: `pip install uv`
- If `Python not found`, install Python 3.9 or higher from https://python.org
- If script fails with import errors, ensure dependencies are installed: `uv sync` or `pip install -r requirements.txt`

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

## Command Reference

All commands follow this pattern:

```
uv run scripts/ms-todo-sync.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.** |

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

---

### Authentication

Authentication uses a two-step device code flow designed for non-interactive/agent environments.

#### `login get` — Get verification code

```bash
uv run scripts/ms-todo-sync.py login get
```

**Output example:**
```
✓ Verification code generated

Please visit the following link to log in:
https://microsoft.com/devicelogin

Enter verification code: ABC123XYZ

Verify with command: ms-todo-sync.py login verify
```

**Agent behavior**: Present the URL and verification code to the user. Wait for the user to confirm they have completed the browser login before proceeding.

#### `login verify` — Complete login

```bash
uv run scripts/ms-todo-sync.py login verify
```

**Output on success:**
```
✓ Authentication successful! Login information saved, you will be logged in automatically next time.
```

**Output on failure:**
```
✗ Authentication failed: <error description>
```

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

**Exit code**: 0 on success, 1 on failure.

#### `logout` — Clear saved login

```bash
uv run scripts/ms-todo-sync.py logout
```

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
uv run scripts/ms-todo-sync.py lists
uv run scripts/ms-todo-sync.py -v lists  # with IDs and dates
```

**Output example:**
```
📋 Task Lists (3 total):

1. Tasks
2. Work
3. Shopping
```

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

```bash
uv run scripts/ms-todo-sync.py create-list "<name>"
```

| Argument | Required | Description |
|----------|----------|-------------|
| `name` | Yes | Name of the new list |

Output: `✓ List created: <name>`

#### `delete-list` — Delete a list

```bash
uv run scripts/ms-todo-sync.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. Consider asking the user before deleting important lists.

Output: `✓ List deleted: <name>`

---

### Task Operations

#### `add` — Add a new task

```bash
uv run scripts/ms-todo-sync.py add "<title>" [options]
```

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `title` | Yes | — | Task title (positional argument) |
| `-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, not time. |
| `-r, --reminder` | No | — | Reminder datetime. Formats: `3h` (hours), `2d` (days), `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). **Note:** Automatically sets start date. |
| `-D, --description` | No | — | Task description/notes |
| `-t, --tags` | No | — | Comma-separated tags (e.g., `"work,urgent"`) |

**Behavior:** If the specified list doesn't exist, it will be automatically created.

**Output example:**
```
✓ List created: Work
✓ Task added: Complete report
```

#### `complete` — Mark a task as completed

```bash
uv run scripts/ms-todo-sync.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. If not specified, uses your default list. |

Output: `✓ Task completed: <title>`

#### `delete` — Delete a task

```bash
uv run scripts/ms-todo-sync.py delete "<title>" [-l "<list>"] [-y]
```

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `title` | Yes | — | Exact task title |
| `-l, --list` | No | (default list) | List name. If not specified, uses your default list. |
| `-y, --yes` | No | — | Skip confirmation prompt |

> ⚠️ **This is a destructive operation**. Without `-y`, the command will prompt for confirmation. For routine cleanup or when user intent is clear, `-y` can be used to avoid blocking.

Output: `✓ Task deleted: <title>`

---

### Task Views

#### `tasks` — List tasks in a specific list

```bash
uv run scripts/ms-todo-sync.py tasks "<list>" [-a]
```

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `list` | Yes | — | List name (positional argument) |
| `-a, --all` | No | — | Include completed tasks (default: only incomplete) |

**Output example:**
```
📋 Task