ms-todo-cli

A command-line interface for Microsoft To Do, built with TypeScript and Node.js.

Features

• OAuth authentication via Microsoft device code flow
• Manage todo lists (create, list)
• Manage tasks (create, update, complete, list, get)
• Manage task steps / checklist items (create, update, complete, delete, list)
• JSON output for easy scripting and integration
• MSAL token cache stored in ~/.ms-todo-cli/msal-cache.json (mode 0o600)

Installation

npm install -g ms-todo-cli

Or clone and build locally:

git clone https://github.com/your-org/ms-todo-cli
cd ms-todo-cli
npm install
npm run build
npm link

Azure App Registration

To use this CLI, you need to register an application in Azure Active Directory:

1. Go to Azure Portal → Azure Active Directory → App registrations
2. Click New registration
   • Name: ms-todo-cli (or any name)
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts
   • Redirect URI: leave blank (device code flow doesn't need one)
3. Click Register
4. Copy the Application (client) ID
5. Under API permissions, add:
   • Tasks.ReadWrite (Microsoft Graph, Delegated)
   • User.Read (Microsoft Graph, Delegated)
   • offline_access (Microsoft Graph, Delegated)
6. Grant admin consent if required by your organization

Environment Variables

Variable	Description	Required
MS_TODO_CLIENT_ID	Azure app client ID	Yes — the CLI will fail fast if not set

Set your client ID before using:

export MS_TODO_CLIENT_ID="your-azure-client-id"

Authentication

Login

ms-todo-cli auth login

Follow the device code instructions printed to stderr. After login, a success JSON is printed to stdout.

Check status

ms-todo-cli auth status

Print account info

ms-todo-cli auth print-account

Logout

ms-todo-cli auth logout

List Commands

Create a list

ms-todo-cli list create "Shopping"

List all lists

ms-todo-cli list list

Task Commands

Create a task

ms-todo-cli task create --title "Buy milk" --list "Shopping"
ms-todo-cli task create --title "Buy milk" --due "2024-12-31T00:00:00Z" --priority high

Create a task via stdin (JSON)

echo '{"title":"Buy eggs","list":"Shopping"}' | ms-todo-cli task create --stdin

Update a task

ms-todo-cli task update --task-id "TASK_ID" --title "Buy oat milk"
ms-todo-cli task update --task-id "TASK_ID" --completed true
# Provide --list-id to skip the O(N) list scan:
ms-todo-cli task update --task-id "TASK_ID" --list-id "LIST_ID" --title "Buy oat milk"

Complete a task

ms-todo-cli task complete --task-id "TASK_ID"
# Provide --list-id to skip the O(N) list scan:
ms-todo-cli task complete --task-id "TASK_ID" --list-id "LIST_ID"

List tasks in a list

ms-todo-cli task list --list "Shopping"
ms-todo-cli task list --list-id "LIST_ID"

Get a single task

ms-todo-cli task get --task-id "TASK_ID"
# Provide --list-id to skip the O(N) list scan:
ms-todo-cli task get --task-id "TASK_ID" --list-id "LIST_ID"

Task Step Commands

Microsoft To Do supports checklist items (steps) within a task.

List steps for a task

ms-todo-cli step list --task-id "TASK_ID"

Create a step

ms-todo-cli step create --task-id "TASK_ID" --title "Sub-task title"

Update a step title

ms-todo-cli step update --task-id "TASK_ID" --step-id "STEP_ID" --title "New title"

Complete a step

ms-todo-cli step complete --task-id "TASK_ID" --step-id "STEP_ID"

Delete a step

ms-todo-cli step delete --task-id "TASK_ID" --step-id "STEP_ID"

Short-form Aliases

Top-level shortcuts for common task operations:

ms-todo-cli create --title "Buy milk"
ms-todo-cli update --task-id "TASK_ID" --title "Buy oat milk"
ms-todo-cli get --task-id "TASK_ID"

Output Format

All output is valid JSON. Success responses have ok: true:

{"ok":true,"task":{"id":"...","title":"Buy milk","status":"notStarted"}}

Error responses have ok: false and exit with code 1:

{"ok":false,"error":{"code":"AUTH_REQUIRED","message":"Not authenticated. Run: ms-todo-cli auth login"}}

OpenClaw / Scripting Integration

The JSON output is designed for easy parsing:

# Get all lists and parse with jq
ms-todo-cli list list | jq '.lists[].displayName'

# Create a task and capture its ID
TASK_ID=$(ms-todo-cli create --title "Review PR" | jq -r '.task.id')

# Complete the task
ms-todo-cli task complete --task-id "$TASK_ID"

Development

npm run build   # Compile TypeScript
npm test        # Run tests
npm run lint    # Lint source files

License

MIT