Microsoft To Do CLI

Manage tasks in Microsoft To Do using the todo command.

User Request

$ARGUMENTS

Commands Reference

Tasks

bash

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

bash

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

bash

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

bash

# 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

bash

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

json

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

todo attach / todo detach:

json

{"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:

json

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

todo link / todo unlink:

json

{"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

bash

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:

json

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

todo lists --json:

json

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

Write commands (new, complete, rm):

json

{"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

Method	Stability	When to Use
`--id "AAMk..."`	Stable	Multi-step operations, automation
Index (`0`, `1`)	Unstable	Quick interactive commands only
Name (`"Task"`)	Unstable	Unique task names only

bash

# 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

Type	Examples
Relative	`1h`, `30m`, `2d`, `1h30m`
Time	`9:30`, `9am`, `17:00`, `5:30pm`
Days	`tomorrow`, `monday`, `fri`
Date	`2026-12-31`, `31.12.2026`, `12/31/2026`
Keywords	`morning` (7:00), `evening` (18:00)

Recurrence Patterns

Pattern	Description
`daily`	Every day
`weekly`	Every week
`monthly`	Every month
`yearly`	Every year
`weekdays`	Monday to Friday
`weekly:mon,wed,fri`	Specific days
`every 2 days`	Custom interval

Aliases

Alias	Command
`t`	`tasks`
`n`	`new`
`c`	`complete`
`d`	`rm`
`sn`	`show-note`
`cn`	`clear-note`

Instructions

•Parse the user's natural language request
•Determine the appropriate todo command
•Always use --json flag -- all examples above include it
•Always use -y flag with rm commands

•For multi-step operations, capture ID from JSON response:

bash

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

•Parse JSON response and report result clearly to the user

If the request is ambiguous, ask for clarification.