todoist-api

name	todoist-api
description	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.

Todoist CLI Skill

This skill provides procedural guidance for working with Todoist using the td CLI tool.

Prerequisites

The td CLI must be installed and authenticated. Verify with:

td auth status

If td is not installed or not authenticated:

• Not installed: Tell the user to install with npm install -g @doist/todoist-cli
• Not authenticated: Tell the user to run td auth login to authenticate via OAuth

Output Formats for Agents

For machine-readable output, use these flags:

• --json - Output as JSON array
• --ndjson - Output as newline-delimited JSON (one object per line)
• --full - Include all fields in JSON output (default shows essential fields only)

Confirmation Requirement

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.

Destructive actions include:

• Deleting tasks, projects, sections, labels, or comments
• Completing tasks
• Updating existing resources
• Archiving projects

Read-only operations do not require confirmation.

Quick Commands

Command	Description
td add "text"	Quick add with natural language parsing
td today	Tasks due today and overdue
td upcoming [days]	Tasks due in next N days (default: 7)
td inbox	Tasks in Inbox
td completed	Recently completed tasks

Quick Add Examples

td add "Buy milk tomorrow p1 #Shopping"
td add "Call dentist every monday @health"
td add "Review PR #Work /Code Review"

The quick add parser supports:

• Due dates: tomorrow, next monday, Jan 15
• Priority: p1 (urgent) through p4 (normal)
• Project: #ProjectName
• Section: /SectionName
• Labels: @label1 @label2

Tasks

List Tasks

td task list [options]

Filters:

• --project <name> - Filter by project name or id:xxx
• --label <name> - Filter by label (comma-separated for multiple)
• --priority <p1-p4> - Filter by priority
• --due <date> - Filter by due date (today, overdue, or YYYY-MM-DD)
• --filter <query> - Raw Todoist filter query
• --assignee <ref> - Filter by assignee (me or id:xxx)
• --workspace <name> - Filter to workspace
• --personal - Filter to personal projects only

Output:

td task list --json                    # JSON array
td task list --project "Work" --json   # Filtered JSON
td task list --all --json              # All tasks (no limit)

View Task Details

td task view <ref>              # Human-readable
td task view <ref> --json       # JSON output

The ref can be a task name, partial match, or id:xxx.

Create Task

Quick add (natural language):

td add "Task text with #Project @label tomorrow p2"

Explicit flags:

td task add --content "Task text" \
  --project "Work" \
  --due "tomorrow" \
  --priority p2 \
  --labels "urgent,review" \
  --description "Additional details"

Options:

• --content <text> - Task content (required)
• --due <date> - Due date (natural language or YYYY-MM-DD)
• --deadline <date> - Deadline date (YYYY-MM-DD)
• --priority <p1-p4> - Priority level
• --project <name> - Project name or id:xxx
• --section <id> - Section ID
• --labels <a,b> - Comma-separated labels
• --parent <ref> - Parent task for subtask
• --description <text> - Task description
• --assignee <ref> - Assign to user (name, email, id:xxx, or "me")
• --duration <time> - Duration (e.g., 30m, 1h, 2h15m)

Update Task

td task update <ref> --content "New content" --due "next week"

Options:

• --content <text> - New content
• --due <date> - New due date
• --deadline <date> - Deadline date
• --no-deadline - Remove deadline
• --priority <p1-p4> - New priority
• --labels <a,b> - Replace labels
• --description <text> - New description
• --assignee <ref> - Assign to user
• --unassign - Remove assignee
• --duration <time> - Duration

Complete Task

td task complete <ref>

Reopen Task

td task uncomplete id:xxx

Note: Uncomplete requires the task ID (id:xxx format).

Delete Task

td task delete <ref>

Move Task

td task move <ref> --project "New Project"
td task move <ref> --section <section-id>
td task move <ref> --parent <task-ref>

Open in Browser

td task browse <ref>

Projects

List Projects

td project list                     # Human-readable tree
td project list --json              # JSON array
td project list --personal --json   # Personal projects only

View Project

td project view <ref>
td project view <ref> --json

Create Project

td project create --name "Project Name" \
  --color "blue" \
  --parent "Parent Project" \
  --view-style board \
  --favorite

Options:

• --name <name> - Project name (required)
• --color <color> - Colour name
• --parent <ref> - Parent project for nesting
• --view-style <style> - "list" or "board"
• --favorite - Mark as favourite

Update Project

td project update <ref> --name "New Name" --color "red"

Archive/Unarchive Project

td project archive <ref>
td project unarchive <ref>

Delete Project

td project delete <ref>

Note: Project must have no uncompleted tasks.

List Collaborators

td project collaborators <ref>

Sections

List Sections

td section list <project>           # Human-readable
td section list <project> --json    # JSON array

Create Section

td section create --name "Section Name" --project "Project Name"

Update Section

td section update <id> --name "New Name"

Delete Section

td section delete <id>

Labels

List Labels

td label list              # Human-readable
td label list --json       # JSON array

Create Label

td label create --name "label-name" --color "green" --favorite

Update Label

td label update <ref> --name "new-name" --color "blue"

Delete Label

td label delete <name>

Comments

List Comments

td comment list <task-ref>                    # Comments on task
td comment list <project-ref> --project       # Comments on project

Add Comment

td comment add <task-ref> --content "Comment text"
td comment add <project-ref> --project --content "Comment text"

Update Comment

td comment update <id> --content "Updated text"

Delete Comment

td comment delete <id>

Reminders

List Reminders

td reminder list <task-ref>

Add Reminder

td reminder add <task-ref> --due "tomorrow 9am"

Delete Reminder

td reminder delete <id>

Filters

List Saved Filters

td filter list --json

Show Tasks Matching Filter

td filter show <filter-ref> --json

Create Filter

td filter create --name "My Filter" --query "today & p1"

Completed Tasks

td completed                              # Today's completed tasks
td completed --since 2024-01-01           # Since specific date
td completed --project "Work" --json      # Filtered JSON output
td completed --all --json                 # All completed (no limit)

Options:

• --since <date> - Start date (YYYY-MM-DD), default: today
• --until <date> - End date (YYYY-MM-DD), default: tomorrow
• --project <name> - Filter by project

Activity and Stats

td activity                  # Recent activity
td stats                     # Productivity stats and karma

Pagination

For large result sets, use --all to fetch everything, or handle pagination with cursors:

# First page
result=$(td task list --json --limit 50)

# If there's a next_cursor in the response, continue
cursor=$(echo "$result" | jq -r '.[-1].id // empty')
td task list --json --limit 50 --cursor "$cursor"

Reference Resolution

The <ref> parameter in commands accepts:

• Task/project/label name (partial match supported)
• id:xxx for exact ID match
• Numeric ID (interpreted as id:xxx)

Additional Reference

For detailed information on specific topics, consult:

• references/completed-tasks.md - Alternative methods for completed task history via API
• references/filters.md - Todoist filter query syntax for --filter flag

Workflow Summary

1. Verify authentication - td auth status
2. Read operations - Execute directly without confirmation
3. Write operations - Ask for confirmation before executing
4. Use JSON output - Add --json flag for machine-readable data
5. Handle large datasets - Use --all or pagination with --cursor