This skill provides instructions for interacting with the Todoist REST API v2 using curl and jq. It covers authentication, CRUD operations for tasks/projects/sections/labels/comments, pagination handling, and requires confirmation before destructive actions. Use this skill when the user wants to read, create, update, or delete Todoist data via the API.
npxskills add intellectronica/agent-skills--skill todoist-apiLoading…
This skill provides procedural guidance for working with Todoist using the td CLI tool.
The td CLI must be installed and authenticated. Verify with:
td auth status
If td is not installed or not authenticated:
npm install -g @doist/todoist-clitd auth login to authenticate via OAuthFor 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)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:
Read-only operations do not require confirmation.
| 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 |
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:
tomorrow, next monday, Jan 15p1 (urgent) through p4 (normal)#ProjectName/SectionName@label1 @label2td 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 onlyOutput:
td task list --json # JSON array
td task list --project "Work" --json # Filtered JSON
td task list --all --json # All tasks (no limit)
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.
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")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> - Durationtd task complete <ref>
td task uncomplete id:xxx
Note: Uncomplete requires the task ID (id:xxx format).
td task delete <ref>
td task move <ref> --project "New Project"
td task move <ref> --section <section-id>
td task move <ref> --parent <task-ref>
td task browse <ref>
td project list # Human-readable tree
td project list --json # JSON array
td project list --personal --json # Personal projects only
td project view <ref>
td project view <ref> --json
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 favouritetd project update <ref> --name "New Name" --color "red"
td project archive <ref>
td project unarchive <ref>
td project delete <ref>
Note: Project must have no uncompleted tasks.
td project collaborators <ref>
td section list <project> # Human-readable
td section list <project> --json # JSON array
td section create --name "Section Name" --project "Project Name"
td section update <id> --name "New Name"
td section delete <id>
td label list # Human-readable
td label list --json # JSON array
td label create --name "label-name" --color "green" --favorite
td label update <ref> --name "new-name" --color "blue"
td label delete <name>
td comment list <task-ref> # Comments on task
td comment list <project-ref> --project # Comments on project
td comment add <task-ref> --content "Comment text"
td comment add <project-ref> --project --content "Comment text"
td comment update <id> --content "Updated text"
td comment delete <id>
td reminder list <task-ref>
td reminder add <task-ref> --due "tomorrow 9am"
td reminder delete <id>
td filter list --json
td filter show <filter-ref> --json
td filter create --name "My Filter" --query "today & p1"
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 projecttd activity # Recent activity
td stats # Productivity stats and karma
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"
The <ref> parameter in commands accepts:
id:xxx for exact ID matchFor detailed information on specific topics, consult:
references/completed-tasks.md - Alternative methods for completed task history via APIreferences/filters.md - Todoist filter query syntax for --filter flagtd auth status--json flag for machine-readable data--all or pagination with --cursor--duration <time> - Duration (e.g., 30m, 1h, 2h15m)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.