Microsoft To Do CLI

Manage tasks in Microsoft To Do using the todo command.

User Request

$ARGUMENTS

Commands Reference

Tasks

# List tasks
todo tasks --json                        # Default list
todo tasks Work --json                   # Specific list
todo tasks --due-today --json            # Due today
todo tasks --overdue --json              # Past due
todo tasks --important --json            # High priority
todo tasks --completed --json            # Done tasks
todo tasks --all --json                  # Everything including completed

# Create task
todo new "Task name" --json              # Basic task
todo new "Task" -l Work --json           # In specific list
todo new "Task" -d tomorrow --json       # With due date
todo new "Task" -r 2h --json             # With reminder (in 2 hours)
todo new "Task" -d mon -r 9am --json     # Due Monday, remind at 9am
todo new "Task" -I --json                # Important (high priority)
todo new "Task" -R daily --json          # Recurring daily
todo new "Task" -R weekly:mon,fri --json # Recurring on specific days
todo new "Task" -S "Step 1" -S "Step 2" --json  # With subtasks
todo new "Task" -N "Note content" --json      # With note
todo new "Task" -L "https://jira.com/ZD-1" --json  # With link

# View single task
todo show "Task" --json                  # Show task details
todo show 0 --json                       # Show by index

# Update task
todo update "Task" --title "New" --json  # Rename
todo update "Task" -d friday -I --json   # Change due date, make important

# Complete/Uncomplete
todo complete "Task" --json              # Mark complete
todo complete 0 1 2 --json               # Complete by index (batch)
todo uncomplete "Task" --json            # Reopen task

# Delete
todo rm "Task" -y --json                 # Delete task

Subtasks (Steps)

todo new-step "Task" "Step text" --json      # Add step
todo list-steps "Task" --json                # List steps
todo complete-step "Task" "Step" --json      # Check off step
todo uncomplete-step "Task" "Step" --json    # Uncheck step
todo rm-step "Task" 0 --json                 # Remove step by index

Notes

todo note "Task" "Note content" --json      # Add/update note
todo show-note "Task" --json                # Display note
todo clear-note "Task" --json               # Remove note

Notes are text content attached to a task. Use todo show "Task" to see the note along with other task details.

Deep Links

# Add a link to a task
todo link "Task" "https://jira.com/ZD-123" --app Jira --title ZD-123 --json
todo link "Task" "https://github.com/org/repo/pull/42" --app GitHub --json
todo link "Task" "https://app.slack.com/..." --app Slack --json

# Add link by task ID
todo link --id "AAMk..." -l Tasks "https://jira.com/ZD-123" --app Jira --json

# List links on a task
todo links "Task" --json
todo links --id "AAMk..." -l Tasks --json

# Remove all links from a task
todo unlink "Task" --json
todo unlink --id "AAMk..." -l Tasks --json

# Remove a specific link by index
todo unlink "Task" --index 0 --json

Deep links attach URLs to tasks using Microsoft To Do's linked resources API. In the To Do app, links appear as clickable "Open in {app}" buttons. The --app flag sets the application name (defaults to URL domain), --title sets the display name (defaults to URL).

File Attachments

# Attach a file to a task
todo attach "Task" /path/to/file.pdf --json
todo attach --id "AAMk..." -l Tasks /path/to/file.pdf --json

# List attachments on a task
todo attachments "Task" --json
todo attachments --id "AAMk..." -l Tasks --json

# Remove all attachments from a task
todo detach "Task" --json

# Remove a specific attachment by index
todo detach "Task" --index 0 --json

# Download all attachments to current directory
todo download "Task"

# Download specific attachment to a directory
todo download "Task" --index 0 -o /tmp/downloads

# Create a task with an attachment
todo new "Review report" --attach /path/to/report.pdf --json

File attachments use the Microsoft Graph API. Files up to 3 MB are uploaded directly; 3-25 MB use an upload session. Max size: 25 MB.

todo attachments --json:

{
  "list": "Tasks",
  "attachments": [
    {
      "id": "AAMk...",
      "name": "report.pdf",
      "content_type": "application/pdf",
      "size": 123456
    }
  ]
}

todo attach / todo detach:

{"action": "attached", "attachment_id": "AAMk...", "file_name": "report.pdf", "task_id": "AAMk...", "title": "Task", "list": "Tasks"}
{"action": "detached", "task_id": "AAMk...", "title": "Task", "count": 1, "list": "Tasks"}

todo links --json:

{
  "list": "Tasks",
  "links": [
    {
      "id": "b9b5a24d-...",
      "url": "https://jira.com/ZD-123",
      "app": "Jira",
      "display_name": "ZD-123"
    }
  ]
}

todo link / todo unlink:

{"action": "linked", "link_id": "b9b5...", "task_id": "AAMk...", "title": "Task", "url": "https://...", "list": "Tasks"}
{"action": "unlinked", "task_id": "AAMk...", "title": "Task", "count": 1, "list": "Tasks"}

Lists

todo lists --json                        # Show all lists
todo new-list "Project X" --json         # Create list
todo rename-list "Old" "New" --json      # Rename list
todo rm-list "Project X" -y --json       # Delete list

JSON Response Structures

todo tasks --json:

{
  "list": "Tasks",
  "tasks": [
    {
      "id": "AAMkADU3...",
      "title": "Buy groceries",
      "status": "notStarted",
      "importance": "normal",
      "due_date": null,
      "reminder": null,
      "recurrence": null,
      "steps": []
    }
  ]
}

todo lists --json:

{
  "lists": [
    {"id": "AAMk...", "name": "Tasks", "is_owner": true},
    {"id": "AAMk...", "name": "Work", "is_owner": true}
  ]
}

Write commands (new, complete, rm):

{"action": "created", "id": "AAMk...", "title": "Task", "list": "Tasks"}
{"action": "completed", "id": "AAMk...", "title": "Task", "list": "Tasks"}
{"action": "removed", "id": "AAMk...", "title": "Task", "list": "Tasks"}

Task Identification

# Use --id with -l (list context required)
todo complete --id "AAMkADU3..." -l Tasks --json
todo update --id "AAMkADU3..." --title "New title" -l Work --json
todo rm --id "AAMkADU3..." -l Tasks -y --json

Date & Time Formats

Recurrence Patterns

Aliases

Instructions

1. Parse the user's natural language request
2. Determine the appropriate todo command
3. Always use --json flag -- all examples above include it
4. Always use -y flag with rm commands
5. For multi-step operations, capture ID from JSON response:

   ID=$(todo new "Task" -l Work --json | jq -r '.id')
   todo complete --id "$ID" -l Work --json
   

6. Parse JSON response and report result clearly to the user

If the request is ambiguous, ask for clarification.