OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add intellectronica/agent-skills --skill todoist-api
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.
npx skills add intellectronica/agent-skills --skill todoist-api
This skill provides procedural guidance for working with Todoist using the td CLI tool.
The td CLI must be installed and authenticated. Verify with:
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 |
The quick add parser supports:
tomorrow, next monday, Jan 15p1 (urgent) through p4 (normal)#ProjectName/SectionName@label1 @label2Filters:
--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:
The ref can be a task name, partial match, or id:xxx.
Quick add (natural language):
Explicit flags:
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)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> - DurationNote: Uncomplete requires the task ID (id:xxx format).
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 favouriteNote: Project must have no uncompleted tasks.
Options:
--since <date> - Start date (YYYY-MM-DD), default: today--until <date> - End date (YYYY-MM-DD), default: tomorrow--project <name> - Filter by projectFor large result sets, use --all to fetch everything, or handle pagination with cursors:
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 --cursortd task list [options]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 outputtd add "Task text with #Project @label tomorrow p2"td task add --content "Task text" \
--project "Work" \
--due "tomorrow" \
--priority p2 \
--labels "urgent,review" \
--description "Additional details"td task update <ref> --content "New content" --due "next week"td task complete <ref>td task uncomplete id:xxxtd 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 onlytd project view <ref>
td project view <ref> --jsontd project create --name "Project Name" \
--color "blue" \
--parent "Parent Project" \
--view-style board \
--favoritetd project update <ref> --name "New Name" --color "red"td project archive <ref>
td project unarchive <ref>td project delete <ref>td project collaborators <ref>td section list <project> # Human-readable
td section list <project> --json # JSON arraytd 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 arraytd label create --name "label-name" --color "green" --favoritetd 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 projecttd 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 --jsontd filter show <filter-ref> --jsontd 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)td activity # Recent activity
td stats # Productivity stats and karma# 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"