Todoist Api

1---2name: todoist-api3description: This skill provides instructions for interacting with Todoist using the td CLI tool. It covers CRUD operations for tasks/projects/sections/labels/comments, and requires confirmation before destructive actions. Use this skill when the user wants to read, create, update, or delete Todoist data.4---5 6# Todoist CLI Skill7 8This skill provides procedural guidance for working with Todoist using the `td` CLI tool.9 10## Prerequisites11 12The `td` CLI must be installed and authenticated. Verify with:13 14```bash15td auth status16```17 18If td is not installed or not authenticated:19- **Not installed**: Tell the user to install with `npm install -g @doist/todoist-cli`20- **Not authenticated**: Tell the user to run `td auth login` to authenticate via OAuth21 22## Output Formats for Agents23 24For machine-readable output, use these flags:25- `--json` - Output as JSON array26- `--ndjson` - Output as newline-delimited JSON (one object per line)27- `--full` - Include all fields in JSON output (default shows essential fields only)28 29## Confirmation Requirement30 31**Before executing any destructive action, always ask the user for confirmation using AskUserQuestion or similar tool.** A single confirmation suffices for a logical group of related actions.32 33Destructive actions include:34- Deleting tasks, projects, sections, labels, or comments35- Completing tasks36- Updating existing resources37- Archiving projects38 39Read-only operations do not require confirmation.40 41## Quick Commands42 43| Command | Description |44|---------|-------------|45| `td add "text"` | Quick add with natural language parsing |46| `td today` | Tasks due today and overdue |47| `td upcoming [days]` | Tasks due in next N days (default: 7) |48| `td inbox` | Tasks in Inbox |49| `td completed` | Recently completed tasks |50 51### Quick Add Examples52 53```bash54td add "Buy milk tomorrow p1 #Shopping"55td add "Call dentist every monday @health"56td add "Review PR #Work /Code Review"57```58 59The quick add parser supports:60- Due dates: `tomorrow`, `next monday`, `Jan 15`61- Priority: `p1` (urgent) through `p4` (normal)62- Project: `#ProjectName`63- Section: `/SectionName`64- Labels: `@label1 @label2`65 66## Tasks67 68### List Tasks69 70```bash71td task list [options]72```73 74**Filters:**75- `--project <name>` - Filter by project name or id:xxx76- `--label <name>` - Filter by label (comma-separated for multiple)77- `--priority <p1-p4>` - Filter by priority78- `--due <date>` - Filter by due date (today, overdue, or YYYY-MM-DD)79- `--filter <query>` - Raw Todoist filter query80- `--assignee <ref>` - Filter by assignee (me or id:xxx)81- `--workspace <name>` - Filter to workspace82- `--personal` - Filter to personal projects only83 84**Output:**85```bash86td task list --json                    # JSON array87td task list --project "Work" --json   # Filtered JSON88td task list --all --json              # All tasks (no limit)89```90 91### View Task Details92 93```bash94td task view <ref>              # Human-readable95td task view <ref> --json       # JSON output96```97 98The ref can be a task name, partial match, or `id:xxx`.99 100### Create Task101 102**Quick add (natural language):**103```bash104td add "Task text with #Project @label tomorrow p2"105```106 107**Explicit flags:**108```bash109td task add --content "Task text" \110  --project "Work" \111  --due "tomorrow" \112  --priority p2 \113  --labels "urgent,review" \114  --description "Additional details"115```116 117**Options:**118- `--content <text>` - Task content (required)119- `--due <date>` - Due date (natural language or YYYY-MM-DD)120- `--deadline <date>` - Deadline date (YYYY-MM-DD)121- `--priority <p1-p4>` - Priority level122- `--project <name>` - Project name or id:xxx123- `--section <id>` - Section ID124- `--labels <a,b>` - Comma-separated labels125- `--parent <ref>` - Parent task for subtask126- `--description <text>` - Task description127- `--assignee <ref>` - Assign to user (name, email, id:xxx, or "me")128- `--duration <time>` - Duration (e.g., 30m, 1h, 2h15m)129 130### Update Task131 132```bash133td task update <ref> --content "New content" --due "next week"134```135 136**Options:**137- `--content <text>` - New content138- `--due <date>` - New due date139- `--deadline <date>` - Deadline date140- `--no-deadline` - Remove deadline141- `--priority <p1-p4>` - New priority142- `--labels <a,b>` - Replace labels143- `--description <text>` - New description144- `--assignee <ref>` - Assign to user145- `--unassign` - Remove assignee146- `--duration <time>` - Duration147 148### Complete Task149 150```bash151td task complete <ref>152```153 154### Reopen Task155 156```bash157td task uncomplete id:xxx158```159 160Note: Uncomplete requires the task ID (id:xxx format).161 162### Delete Task163 164```bash165td task delete <ref>166```167 168### Move Task169 170```bash171td task move <ref> --project "New Project"172td task move <ref> --section <section-id>173td task move <ref> --parent <task-ref>174```175 176### Open in Browser177 178```bash179td task browse <ref>180```181 182## Projects183 184### List Projects185 186```bash187td project list                     # Human-readable tree188td project list --json              # JSON array189td project list --personal --json   # Personal projects only190```191 192### View Project193 194```bash195td project view <ref>196td project view <ref> --json197```198 199### Create Project200 201```bash202td project create --name "Project Name" \203  --color "blue" \204  --parent "Parent Project" \205  --view-style board \206  --favorite207```208 209**Options:**210- `--name <name>` - Project name (required)211- `--color <color>` - Colour name212- `--parent <ref>` - Parent project for nesting213- `--view-style <style>` - "list" or "board"214- `--favorite` - Mark as favourite215 216### Update Project217 218```bash219td project update <ref> --name "New Name" --color "red"220```221 222### Archive/Unarchive Project223 224```bash225td project archive <ref>226td project unarchive <ref>227```228 229### Delete Project230 231```bash232td project delete <ref>233```234 235Note: Project must have no uncompleted tasks.236 237### List Collaborators238 239```bash240td project collaborators <ref>241```242 243## Sections244 245### List Sections246 247```bash248td section list <project>           # Human-readable249td section list <project> --json    # JSON array250```251 252### Create Section253 254```bash255td section create --name "Section Name" --project "Project Name"256```257 258### Update Section259 260```bash261td section update <id> --name "New Name"262```263 264### Delete Section265 266```bash267td section delete <id>268```269 270## Labels271 272### List Labels273 274```bash275td label list              # Human-readable276td label list --json       # JSON array277```278 279### Create Label280 281```bash282td label create --name "label-name" --color "green" --favorite283```284 285### Update Label286 287```bash288td label update <ref> --name "new-name" --color "blue"289```290 291### Delete Label292 293```bash294td label delete <name>295```296 297## Comments298 299### List Comments300 301```bash302td comment list <task-ref>                    # Comments on task303td comment list <project-ref> --project       # Comments on project304```305 306### Add Comment307 308```bash309td comment add <task-ref> --content "Comment text"310td comment add <project-ref> --project --content "Comment text"311```312 313### Update Comment314 315```bash316td comment update <id> --content "Updated text"317```318 319### Delete Comment320 321```bash322td comment delete <id>323```324 325## Reminders326 327### List Reminders328 329```bash330td reminder list <task-ref>331```332 333### Add Reminder334 335```bash336td reminder add <task-ref> --due "tomorrow 9am"337```338 339### Delete Reminder340 341```bash342td reminder delete <id>343```344 345## Filters346 347### List Saved Filters348 349```bash350td filter list --json351```352 353### Show Tasks Matching Filter354 355```bash356td filter show <filter-ref> --json357```358 359### Create Filter360 361```bash362td filter create --name "My Filter" --query "today & p1"363```364 365## Completed Tasks366 367```bash368td completed                              # Today's completed tasks369td completed --since 2024-01-01           # Since specific date370td completed --project "Work" --json      # Filtered JSON output371td completed --all --json                 # All completed (no limit)372```373 374**Options:**375- `--since <date>` - Start date (YYYY-MM-DD), default: today376- `--until <date>` - End date (YYYY-MM-DD), default: tomorrow377- `--project <name>` - Filter by project378 379## Activity and Stats380 381```bash382td activity                  # Recent activity383td stats                     # Productivity stats and karma384```385 386## Pagination387 388For large result sets, use `--all` to fetch everything, or handle pagination with cursors:389 390```bash391# First page392result=$(td task list --json --limit 50)393 394# If there's a next_cursor in the response, continue395cursor=$(echo "$result" | jq -r '.[-1].id // empty')396td task list --json --limit 50 --cursor "$cursor"397```398 399## Reference Resolution400 401The `<ref>` parameter in commands accepts:402- Task/project/label name (partial match supported)403- `id:xxx` for exact ID match404- Numeric ID (interpreted as id:xxx)405 406## Additional Reference407 408For detailed information on specific topics, consult:409- `references/completed-tasks.md` - Alternative methods for completed task history via API410- `references/filters.md` - Todoist filter query syntax for `--filter` flag411 412## Workflow Summary413 4141. **Verify authentication** - `td auth status`4152. **Read operations** - Execute directly without confirmation4163. **Write operations** - Ask for confirmation before executing4174. **Use JSON output** - Add `--json` flag for machine-readable data4185. **Handle large datasets** - Use `--all` or pagination with `--cursor`