todoist-3

name	todoist-3
description	Use the td (Todoist CLI) to read and manage Todoist todos/to-dos/tasks from the terminal. Trigger when the user asks about their todos/tasks/agenda/checklist (today/upcoming/overdue), wants to list inbox/tasks/projects/labels, add a task/todo with natural language, or update/complete/delete/move tasks (e.g., add a phone number to a task description, change due dates, priorities, labels).

Todoist via td CLI

Install / verify

Repo: https://github.com/Doist/todoist-cli

If td is not installed (e.g., command not found: td), install from the repo:

git clone https://github.com/Doist/todoist-cli
cd todoist-cli
npm install
npm run build
npm link

Then verify:

td --help

Use td for all Todoist operations. Prefer parseable output:

• Use --json (or --ndjson) for listing/reading tasks.
• Use td task update ... for edits (content, due, description, priority, labels, etc.).

Quick agenda

• Today + overdue:
  • td today --json
• Next N days:
  • td upcoming 7 --json
• Inbox:
  • td inbox --json

When summarizing an agenda for the user:

• Separate Overdue vs Due today (and optionally Upcoming).
• Include priority (p1–p4) if present and any labels.

Find the right task to edit

Preferred approaches:

1. If you already have the task id, use it directly:

• Reference format: id:<taskId> (e.g., id:6WcqCcR4wF7XW5m6)

2. If you only have a title/snippet, search/list then match:

• td task list --json (optionally filter via other list commands like today, upcoming, inbox)
• Then pick the correct item by content + due date + project.

To view a single task:

• td task view <ref> --json

Common edits

Update description (notes):

• td task update <ref> --description "..."

Update title/content:

• td task update <ref> --content "New task title"

Change due date/time (natural language often works):

• td task update <ref> --due "tomorrow 3pm"

Priority:

• td task update <ref> --priority p1 (or p2/p3/p4)

Labels (replaces existing labels):

• td task update <ref> --labels "Chores,Calls"

Complete / reopen:

• td task complete <ref>
• td task uncomplete id:<taskId>

Delete:

• td task delete <ref> --yes (only if the user explicitly wants deletion)

Add tasks

Fast natural-language add:

• td add "Call dentist tomorrow 10am p2 #Personal"

Or explicit add (when you need structured fields):

• td task add --content "..." --due "..." --priority p2 --labels "..."

Safety / UX

• Confirm before destructive actions (delete).
• If multiple tasks match the user’s description, ask a clarifying question (or show candidates) before updating.
• When the user asks to add info (e.g., a phone number), put it in the description unless they explicitly want it in the title.