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.
- Installs
- 1.7K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/intellectronica/agent-skills --skill todoist-api- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads todoist-api automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 loginto 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) throughp4(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:xxxfor 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 APIreferences/filters.md- Todoist filter query syntax for--filterflag
Workflow Summary
- Verify authentication -
td auth status - Read operations - Execute directly without confirmation
- Write operations - Ask for confirmation before executing
- Use JSON output - Add
--jsonflag for machine-readable data - Handle large datasets - Use
--allor pagination with--cursor
FAQ
What does the todoist-api skill do?
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.
How do I install todoist-api?
Run npx skills add https://github.com/intellectronica/agent-skills --skill todoist-api in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/todoist-api/ (personal) or .claude/skills/todoist-api/ (project).
Which AI agents can use todoist-api?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is todoist-api safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains todoist-api?
It is published by intellectronica in intellectronica/agent-skills. It has 1,671 recorded installs.
More from intellectronica/agent-skills
notion-api
intellectronica/agent-skills
This skill provides comprehensive instructions for interacting with the Notion API via REST calls. This skill should be used whenever the user asks to interact with Notion, including reading, creating, updating, or deleting pages, databases, blocks, comments, or any other Notion content. The skill covers authentication, all available endpoints, pagination, error handling, and best practices.
context7
intellectronica/agent-skills
Retrieve up-to-date documentation for software libraries, frameworks, and components via the Context7 API. This skill should be used when looking up documentation for any programming library or framework, finding code examples for specific APIs or features, verifying correct usage of library functions, or obtaining current information about library APIs that may have changed since training.
youtube-transcript
intellectronica/agent-skills
Extract transcripts from YouTube videos. Use when the user asks for a transcript, subtitles, or captions of a YouTube video and provides a YouTube URL (youtube.com/watch?v=, youtu.be/, or similar). Supports output with or without timestamps.
nano-banana-pro
intellectronica/agent-skills
Generate and edit images using Google's Nano Banana Pro (Gemini 3 Pro Image) API. Use when the user asks to generate, create, edit, modify, change, alter, or update images. Also use when user references an existing image file and asks to modify it in any way (e.g., "modify this image", "change the background", "replace X with Y"). Supports both text-to-image generation and image-to-image editing with configurable resolution (1K default, 2K, or 4K for high resolution). DO NOT read the image file first - use this skill directly with the --input-image parameter.
ultrathink
intellectronica/agent-skills
Display colorful ANSI art of the word "ultrathink". Use when the user says "ultrathink" or invokes /ultrathink.
beautiful-mermaid
intellectronica/agent-skills
Render Mermaid diagrams as SVG and PNG using the Beautiful Mermaid library. Use when the user asks to render a Mermaid diagram.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.