list-checks

cmdhub adapter

Microsoft To Do CLI
for cmdhub.

Task lists, tasks, due dates, and completion through Microsoft To Do.

lock Auth: OAuth2

Quick Install cmdhub get mstodo

data_object Agent Contract

Agents should start with auth/status and discovery commands, inspect schemas before composition, and treat commands marked as mutating as state-changing operations.

catalog.json Markdown

Output

Use human output for normal reads, `--json` for scripting or complete structured fields, and `--jsonl` for upstream pipe inputs.

Auth

Microsoft OAuth. Used for Microsoft To Do lists and tasks.

Refs

Prefer list/search, then short refs or piped JSONL. Use `resolve` to inspect cached refs.

Schemas

Use `mstodo schema` and `catalog.json` to inspect fields, flags, examples, and side effects.

Auth scopes

offline_accessUser.ReadopenidprofileTasks.ReadWrite

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--json bool Emit JSON machine output

--jsonl bool Emit JSONL records for piping

--output, -o string Compatibility output mode: json|jsonl. Prefer --json or --jsonl

--view string = summary View mode: summary|full

--profile string = default Config/auth profile

--config string Config path override

--quiet, -q bool Suppress non-essential diagnostics

--debug bool Enable debug diagnostics

--limit int = 50 Maximum items to emit

--page-size int = 50 Requested upstream page size

--cursor string Continuation cursor

--no-paginate bool Fetch only one page

--version, -v bool Print version information

mstodo attachment Work with task attachments

#cmd-mstodo-attachment discovery safe

Work with file attachments attached to an exact Microsoft To Do task.

Canonical actions: list, get, add, delete. Hidden attachment create resolves to canonical attachment add. Selectors: pass –task for every attachment command; add –list only when the task selector is not a local ref with saved list context. Output modes: human by default; use –json for exact metadata or –jsonl for list streams. Attachment bytes are written with –output-file, not –output. Delete safety: attachment delete requires –dry-run to preview or –yes to execute.

Examples: mstodo attachment list –task t1 mstodo attachment add –task t1 –file ./note.txt mstodo attachment get a1 –task t1 –output-file note.txt

$ mstodo attachment list --task t1

$ mstodo attachment add --task t1 --file ./note.txt

$ mstodo attachment get a1 --task t1 --output-file note.txt

$ mstodo attachment delete a1 --task t1 --dry-run

mstodo attachment add Add a small file attachment

#cmd-mstodo-attachment-add mutates state

Agent guidance:

Purpose: Add a small file attachment. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema attachment.add –input –json; mstodo schema attachment.add –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--file string File path

--name string Display name

$ mstodo attachment add --help

$ mstodo attachment add --task t1 --file ./note.txt

mstodo attachment delete Delete a attachment item

#cmd-mstodo-attachment-delete mutates state dry-run

Agent guidance:

Purpose: Delete a attachment item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema attachment.delete –input –json; mstodo schema attachment.delete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

--dry-run bool Preview deletion without deleting

--yes, -y bool Confirm deletion

$ mstodo attachment delete --help

$ mstodo attachment delete a1 --task t1 --dry-run

$ mstodo attachment delete a1 --task t1 --yes

mstodo attachment get Get a attachment item

#cmd-mstodo-attachment-get discovery safe

Agent guidance:

Purpose: Get a attachment item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema attachment.get –input –json; mstodo schema attachment.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--output-file string Write attachment bytes to this file when content is available

$ mstodo attachment get

$ mstodo attachment get a1 --task t1

mstodo attachment list List attachment items

#cmd-mstodo-attachment-list discovery safe

Agent guidance:

Purpose: List attachment items. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema attachment.list –input –json; mstodo schema attachment.list –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo attachment list

$ mstodo attachment list --task t1

mstodo auth Manage Microsoft authentication

#cmd-mstodo-auth discovery safe

Manage Microsoft To Do OAuth credentials for the selected cmdhub profile.

mstodo uses Microsoft device-code OAuth. Login shows the verification URL https://microsoft.com/devicelogin and a one-time code, then stores the Microsoft Graph refresh/access token in the shared cmdhub credential backend for the selected profile. It never asks for a normal Microsoft account password, client secret, cookie, or pasted token.

Use –profile for one command or mstodo profile use to change the default profile. Required delegated scopes are offline_access, User.Read, openid, profile, and Tasks.ReadWrite.

Recovery commands: mstodo auth status mstodo auth login mstodo auth whoami mstodo doctor

$ mstodo auth --help

mstodo auth login Authenticate with Microsoft To Do

#cmd-mstodo-auth-login mutates state

Start Microsoft device-code OAuth for Microsoft To Do.

The command displays https://microsoft.com/devicelogin with a one-time code, waits for Microsoft authorization, and stores the resulting refresh/access token in the shared cmdhub credential backend for the selected profile. It never asks for a normal Microsoft account password, client secret, cookie, or pasted token, and it never prints tokens.

Use –profile to authenticate that profile for this command; otherwise mstodo uses the current default profile. Required delegated scopes are offline_access, User.Read, openid, profile, and Tasks.ReadWrite.

Recovery commands: mstodo auth status mstodo auth login mstodo auth whoami mstodo doctor

Agent guidance:

Purpose: Authenticate with Microsoft To Do. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema auth.login –input –json; mstodo schema auth.login –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Auth recovery: run mstodo auth status, then mstodo auth login when credentials are missing, expired, or underscoped.

$ mstodo auth login

$ mstodo auth login --help

$ mstodo auth status

$ mstodo auth whoami

mstodo auth logout Remove stored credentials

#cmd-mstodo-auth-logout mutates state

Remove the selected profile’s stored Microsoft OAuth refresh/access token from the shared cmdhub credential backend.

Agent guidance:

Purpose: Remove stored credentials. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema auth.logout –input –json; mstodo schema auth.logout –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Auth recovery: run mstodo auth status, then mstodo auth login when credentials are missing, expired, or underscoped.

$ mstodo auth logout

$ mstodo auth logout --help

mstodo auth refresh Refresh stored token

#cmd-mstodo-auth-refresh mutates state

Refresh the selected profile’s stored Microsoft OAuth access token from the shared cmdhub credential backend. If refresh fails or required scopes are missing, rerun mstodo auth login.

Agent guidance:

Purpose: Refresh stored token. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema auth.refresh –input –json; mstodo schema auth.refresh –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Auth recovery: run mstodo auth status, then mstodo auth login when credentials are missing, expired, or underscoped.

$ mstodo auth refresh

$ mstodo auth refresh --help

mstodo auth status Show auth status

#cmd-mstodo-auth-status discovery safe

Report Microsoft To Do auth readiness for the selected profile.

Status checks whether shared cmdhub credential storage has a Microsoft OAuth token, whether refresh succeeds, whether the required delegated scopes are present, and whether Microsoft Graph To Do is reachable for the selected profile.

Use this before resource commands or after auth failures. If credentials are missing, expired, or underscoped, rerun mstodo auth login for the same –profile and then mstodo doctor.

Agent guidance:

Purpose: Show auth status. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema auth.status –input –json; mstodo schema auth.status –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Auth recovery: run mstodo auth status, then mstodo auth login when credentials are missing, expired, or underscoped.

$ mstodo auth status

$ mstodo auth status --help

mstodo auth whoami Show current Microsoft identity

#cmd-mstodo-auth-whoami discovery safe

Show the Microsoft identity bound to the selected mstodo profile.

The command verifies the stored Microsoft OAuth token against Microsoft Graph and reports the account details available for the selected profile. Use mstodo auth status for credential storage, scope, token-refresh, and provider-readiness details.

Recovery commands: mstodo auth status mstodo auth login mstodo doctor

Agent guidance:

Purpose: Show current Microsoft identity. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema auth.whoami –input –json; mstodo schema auth.whoami –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Auth recovery: run mstodo auth status, then mstodo auth login when credentials are missing, expired, or underscoped.

$ mstodo auth whoami

$ mstodo auth whoami --help

mstodo capabilities Describe capabilities

#cmd-mstodo-capabilities discovery safe

Agent guidance:

Purpose: Describe capabilities. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema capabilities.describe –input –json; mstodo schema capabilities.describe –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--section string Show one capability section: scopes, schemas, or commands

$ mstodo capabilities --help

mstodo checklist Work with task checklist items

#cmd-mstodo-checklist discovery safe

Work with checklist items on an exact Microsoft To Do task.

Canonical actions: list, get, create, update, check, uncheck, delete. Selectors: pass –task for every checklist command; add –list only when the task selector is not a local ref with saved list context. Output modes: human by default; use –json for exact IDs or –jsonl for list streams. Delete safety: checklist delete requires –dry-run to preview or –yes to execute.

Examples: mstodo checklist list –task t1 mstodo checklist update c1 –task t1 –checked true mstodo checklist delete c1 –task t1 –dry-run

$ mstodo checklist list --task t1

$ mstodo checklist create --task t1 --title "Confirm launch numbers"

$ mstodo checklist update c1 --task t1 --checked true

$ mstodo checklist delete c1 --task t1 --dry-run

mstodo checklist check Check a checklist item

#cmd-mstodo-checklist-check discovery safe

Agent guidance:

Purpose: Check a checklist item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.check –input –json; mstodo schema checklist.check –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo checklist check --help

$ mstodo checklist check c1 --task t1

mstodo checklist create Create a checklist item

#cmd-mstodo-checklist-create mutates state

Agent guidance:

Purpose: Create a checklist item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.create –input –json; mstodo schema checklist.create –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--title string Checklist item title

$ mstodo checklist create --help

$ mstodo checklist create --task t1 --title "Confirm launch numbers"

mstodo checklist delete Delete a checklist item

#cmd-mstodo-checklist-delete mutates state dry-run

Agent guidance:

Purpose: Delete a checklist item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.delete –input –json; mstodo schema checklist.delete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

--dry-run bool Preview deletion without deleting

--yes, -y bool Confirm deletion

$ mstodo checklist delete --help

$ mstodo checklist delete c1 --task t1 --dry-run

$ mstodo checklist delete c1 --task t1 --yes

mstodo checklist get Get a checklist item

#cmd-mstodo-checklist-get discovery safe

Agent guidance:

Purpose: Get a checklist item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.get –input –json; mstodo schema checklist.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo checklist get

$ mstodo checklist get c1 --task t1

mstodo checklist list List checklist items

#cmd-mstodo-checklist-list discovery safe

Agent guidance:

Purpose: List checklist items. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.list –input –json; mstodo schema checklist.list –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo checklist list

$ mstodo checklist list --task t1

mstodo checklist uncheck Uncheck a checklist item

#cmd-mstodo-checklist-uncheck discovery safe

Agent guidance:

Purpose: Uncheck a checklist item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.uncheck –input –json; mstodo schema checklist.uncheck –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo checklist uncheck --help

$ mstodo checklist uncheck c1 --task t1

mstodo checklist update Update a checklist item

#cmd-mstodo-checklist-update mutates state

Agent guidance:

Purpose: Update a checklist item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema checklist.update –input –json; mstodo schema checklist.update –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--checked string Set checked state (true or false)

--title string New checklist title

$ mstodo checklist update --help

$ mstodo checklist update c1 --task t1 --title "Confirm numbers"

mstodo config Inspect local configuration

#cmd-mstodo-config discovery safe

$ mstodo config --help

mstodo config explain Explain resolved configuration

#cmd-mstodo-config-explain discovery safe

Agent guidance:

Purpose: Explain resolved configuration. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema config.explain –input –json; mstodo schema config.explain –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo config explain --help

mstodo doctor Run mstodo diagnostics

#cmd-mstodo-doctor discovery safe

Agent guidance:

Purpose: Run mstodo diagnostics. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema doctor.run –input –json; mstodo schema doctor.run –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Auth recovery: run mstodo auth status, then mstodo auth login when credentials are missing, expired, or underscoped.

$ mstodo doctor --help

mstodo link Work with task linked resources

#cmd-mstodo-link discovery safe

Work with linked resources attached to an exact Microsoft To Do task.

Canonical actions: list, get, create, update, delete. Selectors: pass –task for every link command; add –list only when the task selector is not a local ref with saved list context. Output modes: human by default with URL aliases; use –json for exact IDs and full URLs or –jsonl for list streams. Delete safety: link delete requires –dry-run to preview or –yes to execute.

Examples: mstodo link list –task t1 mstodo link create –task t1 –application “cmdhub” –name “Ticket 882” –url https://example.test/tickets/882 mstodo link delete r1 –task t1 –dry-run

$ mstodo link list --task t1

$ mstodo link create --task t1 --application "cmdhub" --name "Ticket 882" --url https://example.test/tickets/882

$ mstodo link get r1 --task t1

$ mstodo link delete r1 --task t1 --dry-run

mstodo link create Create a linked resource

#cmd-mstodo-link-create mutates state

Agent guidance:

Purpose: Create a linked resource. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema link.create –input –json; mstodo schema link.create –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--application string Source application name

--external-id string External source ID

--name string Display name

--url string Source URL

$ mstodo link create --help

$ mstodo link create --task t1 --application "cmdhub" --name "Ticket 882" --url https://example.test/tickets/882

mstodo link delete Delete a link item

#cmd-mstodo-link-delete mutates state dry-run

Agent guidance:

Purpose: Delete a link item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema link.delete –input –json; mstodo schema link.delete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

--dry-run bool Preview deletion without deleting

--yes, -y bool Confirm deletion

$ mstodo link delete --help

$ mstodo link delete r1 --task t1 --dry-run

$ mstodo link delete r1 --task t1 --yes

mstodo link get Get a link item

#cmd-mstodo-link-get discovery safe

Agent guidance:

Purpose: Get a link item. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema link.get –input –json; mstodo schema link.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo link get

$ mstodo link get r1 --task t1

mstodo link list List link items

#cmd-mstodo-link-list discovery safe

Agent guidance:

Purpose: List link items. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema link.list –input –json; mstodo schema link.list –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo link list

$ mstodo link list --task t1

mstodo link update Update a linked resource

#cmd-mstodo-link-update mutates state

Agent guidance:

Purpose: Update a linked resource. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema link.update –input –json; mstodo schema link.update –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--application string Source application name

--external-id string External source ID

--name string Display name

--url string Source URL

$ mstodo link create --task t1 --application "cmdhub" --name "Ticket 882" --url https://example.test/tickets/882

$ mstodo link update --help

mstodo list Work with Microsoft To Do task lists

#cmd-mstodo-list discovery safe

$ mstodo list list

$ mstodo list search --query operations

$ mstodo list get l1 --limit 0

mstodo list create Create a task list

#cmd-mstodo-list-create mutates state

Agent guidance:

Purpose: Create a task list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema list.create –input –json; mstodo schema list.create –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--name string List name

$ mstodo list create --help

$ mstodo list create --name "Operations"

mstodo list delete Delete a task list

#cmd-mstodo-list-delete mutates state dry-run

Agent guidance:

Purpose: Delete a task list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema list.delete –input –json; mstodo schema list.delete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

--dry-run bool Preview task list deletion without deleting

--yes, -y bool Confirm task list deletion

$ mstodo list delete --help

$ mstodo list delete l1 --dry-run

$ mstodo list delete l1 --yes

mstodo list get Get a task list

#cmd-mstodo-list-get discovery safe

Agent guidance:

Purpose: Get a task list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema list.get –input –json; mstodo schema list.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--query string Filter tasks in this list by title/body

--task-limit int = 3 Maximum task preview items; 0 fetches until provider exhaustion

--tasks bool Include a bounded task preview in summary output

$ mstodo list get

$ mstodo list get l1

$ mstodo list get l1 --tasks --query packet

$ mstodo list get l1 --view full --task-limit 3

$ mstodo list search --query operations --jsonl | mstodo list get

mstodo list list List task lists

#cmd-mstodo-list-list discovery safe

Agent guidance:

Purpose: List task lists. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema list.list –input –json; mstodo schema list.list –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--query string Filter list names locally

--shared string Filter by shared state: true or false

--well-known string Filter by built-in list: defaultList, flaggedEmails, or none

$ mstodo list list

$ mstodo list list --limit 0

mstodo list search Search task lists

#cmd-mstodo-list-search discovery safe

Agent guidance:

Purpose: Search task lists. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema list.search –input –json; mstodo schema list.search –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--query string Filter list names locally

--shared string Filter by shared state: true or false

--well-known string Filter by built-in list: defaultList, flaggedEmails, or none

$ mstodo list search

$ mstodo list search --query operations

$ mstodo list search operations

mstodo list update Update a task list

#cmd-mstodo-list-update mutates state

Agent guidance:

Purpose: Update a task list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema list.update –input –json; mstodo schema list.update –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--name string New list name

$ mstodo list update --help

$ mstodo list update l1 --name "Operations"

mstodo mcp Run the MCP server

#cmd-mstodo-mcp discovery safe

Run a stdio Model Context Protocol server for this adapter.

The server exposes read-only resource commands by default. Mutating commands are listed only when explicitly allowed with –allow and remain gated by the command contract safety class.

Agent guidance:

Purpose: Run the MCP server. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema mcp.get –input –json; mstodo schema mcp.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--allow stringArray = [] Allow mutating command keys such as gmail.message.archive or gmail.message.label.*

--allow-dangerous bool Allow --allow wildcards to include destructive or sends_external commands

--concurrency int Maximum concurrent MCP subprocesses

--max-output int64 = 0 Maximum stdout/stderr bytes captured per MCP command

--print-config bool Print MCP tool configuration and exit

--timeout duration = 0s Per-command MCP subprocess timeout, for example 45s or 2m

$ mcp

$ mcp --print-config

mstodo profile Manage provider profiles

#cmd-mstodo-profile discovery safe

$ mstodo profile --help

mstodo profile create Create an unauthenticated provider profile

#cmd-mstodo-profile-create mutates state

Agent guidance:

Purpose: Create an unauthenticated provider profile. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema profile.create –input –json; mstodo schema profile.create –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo profile create --help

mstodo profile delete Delete a local provider profile

#cmd-mstodo-profile-delete mutates state

Agent guidance:

Purpose: Delete a local provider profile. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema profile.delete –input –json; mstodo schema profile.delete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

$ mstodo profile delete --help

mstodo profile list List provider profiles

#cmd-mstodo-profile-list discovery safe

Agent guidance:

Purpose: List provider profiles. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema profile.list –input –json; mstodo schema profile.list –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo profile list --help

mstodo profile rename Rename a local provider profile

#cmd-mstodo-profile-rename discovery safe

Agent guidance:

Purpose: Rename a local provider profile. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema profile.rename –input –json; mstodo schema profile.rename –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo profile rename --help

mstodo profile use Set the default provider profile

#cmd-mstodo-profile-use mutates state

Agent guidance:

Purpose: Set the default provider profile. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema profile.use –input –json; mstodo schema profile.use –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo profile use --help

mstodo resolve Resolve a local mstodo reference

#cmd-mstodo-resolve discovery safe

Agent guidance:

Purpose: Resolve a local mstodo reference. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema resolve.get –input –json; mstodo schema resolve.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo resolve --help

mstodo schema Emit mstodo schema hints

#cmd-mstodo-schema discovery safe

Agent guidance:

Purpose: Emit mstodo schema hints. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema schema.describe –input –json; mstodo schema schema.describe –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--in bool Show input schema

--input bool Show input schema

--out bool Show output schema

$ mstodo schema --help

mstodo sync Work with To Do sync cursors

#cmd-mstodo-sync discovery safe

Work with Microsoft To Do delta sync cursors for an exact task list.

Canonical actions: delta. Selectors: pass –list ; pass –delta-cursor to resume a previous delta. Output modes: human by default with cursor aliases; use –json for exact nextLink/deltaLink values or –jsonl for task streams.

Examples: mstodo sync delta –list l1 mstodo sync delta –list l1 –delta-cursor dcur1 mstodo sync delta –list l1 –page-size 25 –json

$ mstodo sync delta --list l1

$ mstodo sync delta --list l1 --delta-cursor dcur1

$ mstodo sync delta --list l1 --page-size 25 --json

mstodo sync delta Fetch task delta changes for a list

#cmd-mstodo-sync-delta discovery safe

Agent guidance:

Purpose: Fetch task delta changes for a list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema sync.delta –input –json; mstodo schema sync.delta –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--delta-cursor string Delta cursor alias or Graph delta link

--list string Task list ref or ID

$ mstodo sync delta

$ mstodo sync delta --list l1

mstodo task Work with Microsoft To Do tasks

#cmd-mstodo-task discovery safe

$ 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 reopen t1

mstodo task cleanup Preview or delete bounded task cleanup matches

#cmd-mstodo-task-cleanup discovery safe dry-run

Agent guidance:

Purpose: Preview or delete bounded task cleanup matches. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.cleanup –input –json; mstodo schema task.cleanup –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

--all bool Confirm all cleanup matches

--dry-run bool Preview cleanup without deleting

--list string Optional list ref or ID

--older-than string Only match tasks last modified before this duration, e.g. 24h

--query string Required cleanup text filter unless another narrowing filter is supplied

--status string Filter by status

--yes, -y bool Confirm destructive cleanup

$ mstodo task cleanup --help

$ mstodo task cleanup --query cmdhub-eval --all --yes

$ mstodo task cleanup --query cmdhub-eval --dry-run

mstodo task complete Mark a task complete

#cmd-mstodo-task-complete mutates state

Agent guidance:

Purpose: Mark a task complete. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.complete –input –json; mstodo schema task.complete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--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 complete --help

$ mstodo task complete t1

mstodo task create Create a task

#cmd-mstodo-task-create mutates state

Agent guidance:

Purpose: Create a task. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.create –input –json; mstodo schema task.create –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--body string Task body

--body-file string Read task body from a text file

--category stringArray = [] Category name; may be repeated

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

--recurrence string Graph recurrence pattern type such as daily, weekly, absoluteMonthly, or absoluteYearly

--reminder string Reminder date/time

--start string Start date/time

--title string Task title

$ 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

mstodo task delete Delete a task

#cmd-mstodo-task-delete mutates state dry-run

Agent guidance:

Purpose: Delete a task. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.delete –input –json; mstodo schema task.delete –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.
Safety: destructive commands require –dry-run previews or explicit –yes confirmation; cleanup also requires –all –yes.

--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, -y bool Confirm destructive task deletion

$ mstodo task delete --help

$ mstodo task delete t1 --dry-run

$ mstodo task delete t1 --yes

mstodo task get Get a task

#cmd-mstodo-task-get discovery safe

Agent guidance:

Purpose: Get a task. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.get –input –json; mstodo schema task.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--list string Task list ref or ID when task is not a local ref

--task string Task ref or ID

$ mstodo task get

$ mstodo task get t1

$ mstodo task list --list l1 --limit 1 --jsonl | mstodo task get

mstodo task list List tasks in a task list

#cmd-mstodo-task-list discovery safe

Agent guidance:

Purpose: List tasks in a task list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.list –input –json; mstodo schema task.list –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--category string Filter by category

--due string Filter by due state: today, tomorrow, overdue, none, before:YYYY-MM-DD, or after:YYYY-MM-DD

--importance string Filter by importance: low, normal, or high

--include-completed bool Include completed tasks when no explicit completed status is requested

--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 list search --query operations --jsonl | mstodo task list --query packet

$ mstodo task list

$ mstodo task list --list l1

mstodo task move Move a task to another list

#cmd-mstodo-task-move discovery safe

Agent guidance:

Purpose: Move a task to another list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.move –input –json; mstodo schema task.move –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--from-list string Original task list ref or ID when task is not a local ref

--task string Task ref or ID

--to-list string Destination task list ref or ID

$ mstodo task move --help

$ mstodo task move t1 --to-list l2

mstodo task reopen Reopen a completed task

#cmd-mstodo-task-reopen discovery safe

Agent guidance:

Purpose: Reopen a completed task. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.reopen –input –json; mstodo schema task.reopen –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--list string Task list ref or ID when task is not a local ref

--task string Task ref or ID

$ mstodo task reopen --help

$ mstodo task reopen t1

mstodo task search Search tasks in a task list

#cmd-mstodo-task-search discovery safe

Agent guidance:

Purpose: Search tasks in a task list. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.search –input –json; mstodo schema task.search –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--category string Filter by category

--due string Filter by due state: today, tomorrow, overdue, none, before:YYYY-MM-DD, or after:YYYY-MM-DD

--importance string Filter by importance: low, normal, or high

--include-completed bool Include completed tasks when no explicit completed status is requested

--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 list search --query operations --jsonl | mstodo task search --query packet

$ mstodo task search

$ mstodo task search --list l1 --query packet

$ mstodo task search --query packet

mstodo task update Update a task

#cmd-mstodo-task-update mutates state

Agent guidance:

Purpose: Update a task. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema task.update –input –json; mstodo schema task.update –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

--body string New task body

--body-file string Read new task body from a text file

--category stringArray = [] Category name; may be repeated

--clear-categories bool Clear all categories

--clear-due bool Clear due date

--clear-recurrence bool Clear recurrence

--clear-reminder bool Clear reminder

--clear-start bool Clear start date

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

--recurrence string Graph recurrence pattern type

--reminder string New reminder date/time

--start string New start date/time

--status string Graph task status, e.g. notStarted or completed

--task string Task ref or ID

--title string New task title

$ mstodo task update --help

$ mstodo task update t1 --importance high --due 2026-05-01

$ mstodo task update t1 --title "Send updated packet"

mstodo version Print version information

#cmd-mstodo-version discovery safe

Agent guidance:

Purpose: Print version information. Hidden aliases recover common guesses but help stays canonical.
Output modes: human by default; add –json for one exact object or –jsonl for item/meta streams where supported.
Local refs: use displayed refs such as l1, t1, c1, r1, a1, u1, or cursor aliases instead of Microsoft Graph IDs and long URLs.
Schemas: mstodo schema version.get –input –json; mstodo schema version.get –out –json.
Recovery: if a ref is stale, rerun the matching list/search command and use the new displayed ref.

$ mstodo version --help

play_circle Live Examples

Output captured from a real workspace. Regenerate with scripts/gen-docs.sh --update.

auth

Check Microsoft auth status Shows whether the Microsoft grant is configured and provider-ready.

$ mstodo auth status

Not logged in.

Next steps:
- Login: mstodo auth login

Check Microsoft auth status JSON Preserves exact profile, provider, credential, and readiness fields for agents.

$ mstodo auth status --json

{
  "account": {
    "account_type": "unknown",
    "display_name": "",
    "email": "",
    "id": "",
    "tenant_id": "",
    "user_principal_name": ""
  },
  "auth_mode": "oauth",
  "authenticated": false,
  "credential_backend": "{backend}",
  "credential_secure": {secure},
  "credential_store_provider": "microsoft",
  "credential_store_tool": "mstodo",
  "credential_type": "oauth_device_code",
  "credentials_stored": false,
  "missing_scopes": [
    "Tasks.ReadWrite",
    "User.Read",
    "offline_access",
    "openid",
    "profile"
  ],
  "next_steps": [
    {
      "label": "Next",
      "command": "mstodo auth login"
    }
  ],
  "oauth": {
    "client_id_source": "env",
    "device_code_supported": true,
    "refresh_token_present": false
  },
  "profile": "default",
  "provider": "microsoft",
  "provider_ready": false,
  "refresh_attempted": true,
  "required_scopes": [
    "Tasks.ReadWrite",
    "User.Read",
    "offline_access",
    "openid",
    "profile"
  ],
  "scopes_granted": [],
  "scopes_required": [
    "Tasks.ReadWrite",
    "User.Read",
    "offline_access",
    "openid",
    "profile"
  ],
  "suggested_next_step": "mstodo auth login",
  "token_valid": false,
  "tool": "mstodo"
}

Show active Microsoft identity Confirms the selected profile and Microsoft account before acting.

$ mstodo auth whoami

Not logged in.

Next steps:
- Login: mstodo auth login

Run diagnostics Checks credential backend, auth, scopes, Graph reachability, and To Do access.

$ mstodo doctor

mstodo doctor: FAIL
Checks: credential_backend ok, credential_security warn, profiles warn, microsoft_oauth ok, token fail, todo_access 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      Microsoft OAuth device-code public client is configured
token                FAIL    no stored Microsoft OAuth device-code token
todo_access          FAIL    Microsoft To Do access check skipped because auth is not ready

Next steps:
- Status:       run mstodo auth login
- Capabilities: mstodo capabilities

schemas

Inspect task create input schema Shows fields for creating a task.

$ mstodo schema task.create --input --json

{
  "schema_id": "mstodo.task.create.input.v1",
  "version": "v1",
  "tool": "mstodo",
  "resource": "task",
  "action": "create",
  "direction": "input",
  "kind": "provider-native",
  "json_schema": {
    "type": "object",
    "required": [
      "list",
      "title"
    ],
    "properties": {
      "list": {
        "type": "string"
      },
      "title": {
        "type": "string"
      },
      "body": {
        "type": "string"
      },
      "body_file": {
        "type": "string"
      },
      "due": {
        "type": "string"
      },
      "start": {
        "type": "string"
      },
      "reminder": {
        "type": "string"
      },
      "recurrence": {
        "type": "string"
      },
      "importance": {
        "type": "string",
        "enum": [
          "low",
          "normal",
          "high"
        ]
      },
      "category": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "list",
    "title"
  ],
  "optional": [
    "body",
    "body_file",
    "due",
    "start",
    "reminder",
    "recurrence",
    "importance",
    "category"
  ]
}

Inspect task search output schema Shows structured list/search fields and exact IDs.

$ mstodo schema task.search --out --json

{
  "schema_id": "mstodo.task.search.output.v1",
  "version": "v1",
  "tool": "mstodo",
  "resource": "task",
  "action": "search",
  "direction": "output",
  "kind": "provider-native",
  "json_schema": {
    "type": "object",
    "required": [
      "items",
      "count_emitted",
      "truncated",
      "next_cursor"
    ],
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "type",
            "id",
            "title"
          ],
          "properties": {
            "type": {
              "const": "task"
            },
            "id": {
              "type": "string"
            },
            "list_id": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "status": {
              "type": "string"
            },
            "importance": {
              "type": "string"
            },
            "body": {
              "type": "string"
            },
            "categories": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "due": {
              "type": "string"
            },
            "due_time_zone": {
              "type": "string"
            },
            "start": {
              "type": "string"
            },
            "start_time_zone": {
              "type": "string"
            },
            "reminder": {
              "type": "string"
            },
            "reminder_time_zone": {
              "type": "string"
            },
            "recurrence": {
              "type": "string"
            },
            "created_date_time": {
              "type": "string"
            },
            "modified_date_time": {
              "type": "string"
            },
            "completed_date_time": {
              "type": "string"
            },
            "completed": {
              "type": "boolean"
            }
          }
        }
      },
      "count_emitted": {
        "type": "integer"
      },
      "truncated": {
        "type": "boolean"
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      },
      "resource": {
        "type": "string"
      },
      "action": {
        "type": "string"
      },
      "request": {
        "type": "object"
      },
      "list": {
        "type": "object",
        "required": [
          "type",
          "id",
          "name"
        ],
        "properties": {
          "type": {
            "const": "list"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "wellknown_list_name": {
            "type": "string"
          },
          "is_owner": {
            "type": "boolean"
          },
          "is_shared": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "required": [
    "items",
    "count_emitted",
    "truncated",
    "next_cursor"
  ],
  "optional": [
    "resource",
    "action",
    "request",
    "list"
  ]
}

overview

Show Microsoft To Do help Covers common workflows, resources, aliases, safety, and first safe discovery steps.

$ mstodo --help

mstodo - Microsoft To Do from cmdhub

Auth: required, Microsoft OAuth device-code
Use local refs such as l1, t1, c1, a1, and r1 in follow-up commands.

Common workflows:
- Verify auth:      mstodo auth status
- Confirm account:  mstodo auth whoami
- List task lists:  mstodo list list --limit 10
- Search tasks:     mstodo task search --query "quarterly packet"
- Inspect task:     mstodo task get t1 --view full
- Create task:      mstodo task create --list l1 --title "Review quarterly packet"
- Work checklist:   mstodo checklist create --task t1 --title "Confirm launch numbers"
- Add source link:  mstodo link create --task t1 --application "cmdhub" --name "Ticket 882" --url https://example.test/tickets/882
- Clean up safely:  mstodo task cleanup --query cmdhub-eval --dry-run

Resources:
  auth          login, status, whoami, refresh, logout
  profile       list, create, use, rename, delete
  list          list, search, get, create, update, delete
  task          list, search, get, create, update, complete, reopen, move, delete, cleanup
  checklist     list, get, create, update, check, uncheck, delete
  link          list, get, create, update, delete
  attachment    list, get, add, delete
  sync          delta

Meta:
  doctor, capabilities, schema, mcp, resolve, version

Safety:
- Deletes require --dry-run or --yes.
- Bulk cleanup requires a narrowing filter and --all --yes to execute.
- Built-in lists such as defaultList and flaggedEmails cannot be renamed or deleted.

Discovery:
- Machine inventory: mstodo capabilities --json
- Command schemas:   mstodo schema task.create --input --json
- Command help:      mstodo task create --help

Usage:
  mstodo [flags]
  mstodo [command]

Examples:
  mstodo auth login
  mstodo list list
  mstodo list create --name "Operations"
  mstodo task create --list l1 --title "Send packet" --due 2026-05-01
  mstodo task complete t1

Available Commands:
  attachment   Work with task attachments
  auth         Manage Microsoft authentication
  capabilities Describe capabilities
  checklist    Work with task checklist items
  config       Inspect local configuration
  doctor       Run mstodo diagnostics
  help         Help about any command
  link         Work with task linked resources
  list         Work with Microsoft To Do task lists
  mcp          Run the MCP server
  profile      Manage provider profiles
  resolve      Resolve a local mstodo reference
  schema       Emit mstodo schema hints
  sync         Work with To Do sync cursors
  task         Work with Microsoft To Do tasks
  version      Print version information

Flags:
      --config string    Config path override
      --cursor string    Continuation cursor
      --debug            Enable debug diagnostics
  -h, --help             help for mstodo
      --json             Emit JSON machine output
      --jsonl            Emit JSONL records for piping
      --limit int        Maximum items to emit (default 50)
      --no-paginate      Fetch only one page
  -o, --output string    Compatibility output mode: json|jsonl. Prefer --json or --jsonl
      --page-size int    Requested upstream page size (default 50)
      --profile string   Config/auth profile (default "default")
  -q, --quiet            Suppress non-essential diagnostics
  -v, --version          Print version information
      --view string      View mode: summary|full (default "summary")

Use "mstodo [command] --help" for more information about a command.

Show capabilities Lists supported Microsoft To Do resources, actions, output modes, and safety boundaries.

$ mstodo capabilities

mstodo capabilities
Resources: attachment, auth, capabilities, checklist, config, doctor, link, list, mcp, profile, resolve, schema, sync, task, version
Machine output: --json, --jsonl
Required scopes: Tasks.ReadWrite, User.Read, offline_access, openid, profile

Next steps:
- Scopes:   mstodo capabilities --section scopes
- Schema:   mstodo schema
- Contract: mstodo capabilities --json
- Help:     mstodo --help

alt_route Composition Patterns

Bridge your ecosystem with zero middleware.

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

# Fetch every task in a long list
mstodo list get l1 --limit 0 --json

Microsoft To Do CLIfor cmdhub.

data_object Agent Contract

Output

Auth

Refs

Schemas

Auth scopes

terminal Command Reference

Global Flags

play_circle Live Examples

auth

schemas

overview

alt_route Composition Patterns

Microsoft To Do CLI
for cmdhub.