/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

Crea