# Microsoft To Do CLI Task lists, tasks, due dates, and completion through Microsoft To Do. ## Install ```bash cmdhub get mstodo ``` ## Authentication OAuth2 ## Agent-Readable Catalog - Machine-readable command catalog: `/cli/mstodo/catalog.json` - Stable command anchors use the `cmd-...` IDs listed under each command. - Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support. ## Overview ```bash mstodo auth login # Create and complete a Microsoft To Do task mstodo list search --query "Operations" mstodo list get l1 mstodo task create --title "Send weekly packet" --list l1 --due 2026-05-01 mstodo task complete t1 # Pipe a listed task into a follow-up command mstodo list get l1 --limit 1 --jsonl | mstodo task get --json # Fetch every task in a long list mstodo list get l1 --limit 0 --json ``` ## CLI Overview Microsoft To Do adapter CLI Work with Microsoft To Do task lists and tasks. The intended workflow is: - authenticate with mstodo auth login - list or search first - follow up with short refs such as l1 or t1, or pipe jsonl into the next command - use resolve when you need to inspect what a short ref expands to ## Generated Coverage - Command groups: `12` - Total documented command nodes: `37` - Live examples: `4` - Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version` - Machine-readable output: `--json`, `--jsonl` - Human views: `summary`, `full` ## Auth Contract - Auth mode: OAuth2 - Provider permission model: Microsoft OAuth - Auth scopes: `offline_access`, `User.Read`, `Tasks.ReadWrite` - Scope note: Used for Microsoft To Do lists and tasks. - Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami` - `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`. - `auth whoami --json` is the stable way to answer identity questions. ## Agent Safety Notes - Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first. - Treat commands marked as mutating as state-changing local or provider operations. - Mutating command paths: `mstodo auth login`, `mstodo auth logout`, `mstodo auth refresh`, `mstodo list create`, `mstodo list delete`, `mstodo list update`, `mstodo login`, `mstodo logout`, `mstodo profile create`, `mstodo profile delete`, `mstodo profile use`, `mstodo task comment`, `mstodo task complete`, `mstodo task create`, `mstodo task delete`, `mstodo task update` - Commands with `--dry-run`: `mstodo list delete`, `mstodo task delete` ## Global Flags - `--json` (bool): Emit JSON machine output - `--jsonl` (bool): Emit JSONL records for piping - `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl - `--view` (string): View mode: summary|full Default: `summary`. - `--profile` (string): Config/auth profile Default: `default`. - `--config` (string): Config path override - `--quiet` (bool): Suppress non-essential diagnostics - `--debug` (bool): Enable debug diagnostics - `--limit` (int): Maximum items to emit Default: `50`. - `--page-size` (int): Requested upstream page size Default: `50`. - `--cursor` (string): Continuation cursor - `--no-paginate` (bool): Fetch only one page - `--version` (bool): Print version information ## Command Reference ### `mstodo auth` - Anchor: `cmd-mstodo-auth` - Mutates state: `no` - Supports dry run: `no` Manage Microsoft authentication #### `mstodo auth login` - Anchor: `cmd-mstodo-auth-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Microsoft To Do Example: ```bash mstodo auth login mstodo auth login --help mstodo auth status mstodo auth whoami ``` #### `mstodo auth logout` - Anchor: `cmd-mstodo-auth-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored credentials Example: ```bash mstodo auth logout mstodo auth logout --help ``` #### `mstodo auth refresh` - Anchor: `cmd-mstodo-auth-refresh` - Mutates state: `yes` - Supports dry run: `no` Refresh stored token Example: ```bash mstodo auth refresh mstodo auth refresh --help ``` #### `mstodo auth status` - Anchor: `cmd-mstodo-auth-status` - Mutates state: `no` - Supports dry run: `no` Show auth status Example: ```bash mstodo auth status mstodo auth status --help ``` #### `mstodo auth whoami` - Anchor: `cmd-mstodo-auth-whoami` - Mutates state: `no` - Supports dry run: `no` Show current Microsoft identity Example: ```bash mstodo auth whoami mstodo auth whoami --help ``` ### `mstodo capabilities` - Anchor: `cmd-mstodo-capabilities` - Mutates state: `no` - Supports dry run: `no` Describe capabilities Example: ```bash mstodo capabilities --help ``` ### `mstodo config` - Anchor: `cmd-mstodo-config` - Mutates state: `no` - Supports dry run: `no` Inspect local configuration #### `mstodo config explain` - Anchor: `cmd-mstodo-config-explain` - Mutates state: `no` - Supports dry run: `no` Explain resolved configuration Example: ```bash mstodo config explain --help ``` ### `mstodo doctor` - Anchor: `cmd-mstodo-doctor` - Mutates state: `no` - Supports dry run: `no` Run mstodo diagnostics Example: ```bash mstodo doctor --help ``` ### `mstodo list` - Anchor: `cmd-mstodo-list` - Mutates state: `no` - Supports dry run: `no` Work with Microsoft To Do task lists Example: ```bash mstodo list list mstodo list search --query operations mstodo list get l1 --limit 0 ``` #### `mstodo list create` - Anchor: `cmd-mstodo-list-create` - Mutates state: `yes` - Supports dry run: `no` Create a task list Example: ```bash mstodo list create --help mstodo list create --name "Operations" ``` Flags: - `--name` (string): List name #### `mstodo list delete` - Anchor: `cmd-mstodo-list-delete` - Mutates state: `yes` - Supports dry run: `yes` Delete a task list Example: ```bash mstodo list delete l1 --dry-run mstodo list delete l1 --yes ``` Flags: - `--dry-run` (bool): Preview task list deletion without deleting - `--yes` (bool): Confirm task list deletion #### `mstodo list get` - Anchor: `cmd-mstodo-list-get` - Mutates state: `no` - Supports dry run: `no` Get a task list Example: ```bash mstodo list get mstodo list get l1 mstodo list get l1 --limit 0 mstodo list get l1 --query packet mstodo list search --query operations --jsonl | mstodo list get ``` Flags: - `--query` (string): Filter tasks in this list by title/body #### `mstodo list list` - Anchor: `cmd-mstodo-list-list` - Mutates state: `no` - Supports dry run: `no` List task lists Example: ```bash mstodo list list mstodo list list --limit 0 ``` Flags: - `--query` (string): Filter list names locally #### `mstodo list search` - Anchor: `cmd-mstodo-list-search` - Mutates state: `no` - Supports dry run: `no` Search task lists Example: ```bash mstodo list search mstodo list search --query operations mstodo list search operations ``` Flags: - `--query` (string): Filter list names locally #### `mstodo list update` - Anchor: `cmd-mstodo-list-update` - Mutates state: `yes` - Supports dry run: `no` Update a task list Example: ```bash mstodo list update --help mstodo list update l1 --name "Operations" ``` Flags: - `--name` (string): New list name ### `mstodo login` - Anchor: `cmd-mstodo-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Microsoft To Do Example: ```bash mstodo auth status mstodo auth whoami mstodo login ``` ### `mstodo logout` - Anchor: `cmd-mstodo-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored credentials Example: ```bash mstodo logout ``` ### `mstodo profile` - Anchor: `cmd-mstodo-profile` - Mutates state: `no` - Supports dry run: `no` Manage provider profiles #### `mstodo profile create` - Anchor: `cmd-mstodo-profile-create` - Mutates state: `yes` - Supports dry run: `no` Create an unauthenticated provider profile Example: ```bash mstodo profile create --help ``` #### `mstodo profile delete` - Anchor: `cmd-mstodo-profile-delete` - Mutates state: `yes` - Supports dry run: `no` Delete a local provider profile Example: ```bash mstodo profile delete --help ``` #### `mstodo profile list` - Anchor: `cmd-mstodo-profile-list` - Mutates state: `no` - Supports dry run: `no` List provider profiles Example: ```bash mstodo profile list --help ``` #### `mstodo profile rename` - Anchor: `cmd-mstodo-profile-rename` - Mutates state: `no` - Supports dry run: `no` Rename a local provider profile Example: ```bash mstodo profile rename --help ``` #### `mstodo profile use` - Anchor: `cmd-mstodo-profile-use` - Mutates state: `yes` - Supports dry run: `no` Set the default provider profile Example: ```bash mstodo profile use --help ``` ### `mstodo resolve` - Anchor: `cmd-mstodo-resolve` - Mutates state: `no` - Supports dry run: `no` Resolve a local mstodo reference Example: ```bash mstodo resolve --help ``` ### `mstodo schema` - Anchor: `cmd-mstodo-schema` - Mutates state: `no` - Supports dry run: `no` Emit mstodo schema hints Example: ```bash mstodo schema --help ``` Flags: - `--in` (bool): Show input schema - `--out` (bool): Show output schema ### `mstodo task` - Anchor: `cmd-mstodo-task` - Mutates state: `no` - Supports dry run: `no` Work with Microsoft To Do tasks Example: ```bash mstodo task list --list l1 mstodo task search --list l1 --query packet mstodo task create --list l1 --title "Send packet" mstodo task get t1 mstodo task complete t1 ``` #### `mstodo task comment` - Anchor: `cmd-mstodo-task-comment` - Mutates state: `yes` - Supports dry run: `no` Append text to a task body Example: ```bash mstodo task comment --help mstodo task comment t1 --body "Comment marker for audit trail" ``` Flags: - `--body` (string): Text to append - `--list` (string): Task list ref or ID when task is not a local ref - `--task` (string): Task ref or ID #### `mstodo task complete` - Anchor: `cmd-mstodo-task-complete` - Mutates state: `yes` - Supports dry run: `no` Mark a task complete Example: ```bash mstodo task complete --help mstodo task complete t1 ``` Flags: - `--all` (bool): Confirm batch task completion - `--list` (string): Task list ref or ID when task is not a local ref - `--task` (string): Task ref or ID #### `mstodo task create` - Anchor: `cmd-mstodo-task-create` - Mutates state: `yes` - Supports dry run: `no` Create a task Example: ```bash mstodo task create --help mstodo task create --list l1 --title "Send packet" mstodo task create --list l1 --title "Send packet" --due 2026-05-01 --importance high ``` Flags: - `--body` (string): Task body - `--due` (string): Due date/time, e.g. YYYY-MM-DD or RFC3339; date-only values are stored at 00:00 UTC - `--importance` (string): Importance: low, normal, or high - `--list` (string): Task list ref or ID - `--title` (string): Task title #### `mstodo task delete` - Anchor: `cmd-mstodo-task-delete` - Mutates state: `yes` - Supports dry run: `yes` Delete a task Example: ```bash mstodo task delete t1 --dry-run mstodo task delete t1 --yes ``` Flags: - `--all` (bool): Confirm batch task deletion - `--dry-run` (bool): Preview task deletion without deleting - `--list` (string): Task list ref or ID when task is not a local ref - `--task` (string): Task ref or ID - `--yes` (bool): Confirm destructive task deletion #### `mstodo task get` - Anchor: `cmd-mstodo-task-get` - Mutates state: `no` - Supports dry run: `no` Get a task Example: ```bash mstodo list get l1 --limit 1 --jsonl | mstodo task get --json mstodo task get mstodo task get t1 ``` Flags: - `--list` (string): Task list ref or ID when task is not a local ref - `--task` (string): Task ref or ID #### `mstodo task list` - Anchor: `cmd-mstodo-task-list` - Mutates state: `no` - Supports dry run: `no` List tasks in a task list Example: ```bash mstodo list search --query operations --jsonl | mstodo task list --query packet mstodo task list --list l1 ``` Flags: - `--list` (string): Task list ref or ID - `--query` (string): Filter tasks by title/body - `--status` (string): Filter by status: open, completed, notStarted, inProgress, waitingOnOthers, or deferred #### `mstodo task search` - Anchor: `cmd-mstodo-task-search` - Mutates state: `no` - Supports dry run: `no` Search tasks in a task list Example: ```bash mstodo list search --query operations --jsonl | mstodo task search --query packet mstodo task search --list l1 --query packet ``` Flags: - `--list` (string): Task list ref or ID - `--query` (string): Filter tasks by title/body - `--status` (string): Filter by status: open, completed, notStarted, inProgress, waitingOnOthers, or deferred #### `mstodo task update` - Anchor: `cmd-mstodo-task-update` - Mutates state: `yes` - Supports dry run: `no` Update a task Example: ```bash mstodo task update --help mstodo task update t1 --importance high --due 2026-05-01 mstodo task update t1 --title "Send updated packet" ``` Flags: - `--body` (string): New task body - `--due` (string): New due date/time; empty clears the due date - `--importance` (string): Importance: low, normal, or high - `--list` (string): Task list ref or ID when task is not a local ref - `--status` (string): Graph task status, e.g. notStarted or completed - `--task` (string): Task ref or ID - `--title` (string): New task title ### `mstodo version` - Anchor: `cmd-mstodo-version` - Mutates state: `no` - Supports dry run: `no` Print version information Example: ```bash mstodo version --help ``` ## Live Examples ### Auth #### Check Microsoft auth status Shows whether the Microsoft grant is configured. _Example metadata: requires auth; provider state: live._ ```bash mstodo auth status ``` ```text Not logged in. Next steps: - Login: mstodo auth login ``` #### Run diagnostics Checks Microsoft provider configuration and stored credentials. _Example metadata: requires auth; provider state: live._ ```bash mstodo doctor ``` ```text mstodo doctor: FAIL Checks: credential_backend ok, credential_security warn, profiles warn, microsoft_oauth ok, token fail CHECK STATUS DETAIL credential_backend OK using file credential_security WARN credential backend stores local plaintext secrets profiles WARN no provider profiles configured microsoft_oauth OK built-in Microsoft provider client is configured token FAIL no stored Microsoft token Next steps: - Status: prefer an OS keychain backend outside isolated test accounts - Capabilities: mstodo capabilities ``` ### Overview #### Show capabilities Lists supported Microsoft To Do resources. _Example metadata: requires auth; provider state: live._ ```bash mstodo capabilities ``` ```text mstodo capabilities Resources: auth, capabilities, config, doctor, list, profile, resolve, schema, task, version Machine output: --json, --jsonl Required scopes: Tasks.ReadWrite, User.Read, offline_access Next steps: - Scopes: mstodo capabilities --section scopes - Schema: mstodo schema - Contract: mstodo capabilities --json - Help: mstodo --help ``` ### Schemas #### Inspect task schema Shows fields for creating a task. _Example metadata: requires auth; provider state: live._ ```bash mstodo schema task.create --in ``` ```text Schema: mstodo.task.create.input.v1 (mstodo task create input) Required: list, title Optional: body, due, importance ```