# todoist-api

This skill tells the agent how to drive Todoist through the td CLI: tasks, projects, sections, labels and comments. Handy when you want your lists sorted without leaving the chat.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1700 installs · ★ 298
- Author: intellectronica
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/intellectronica/agent-skills/tree/HEAD/skills/todoist-api/SKILL.md
- Updated: 2026-04-25
- HTML: https://affpapa.org/en/nevibecode/skills/todoist-api

## What it does

The skill spells out how the agent calls `td` for tasks, projects, sections, labels and comments. Reads, creates, updates and deletes all go through CLI commands. Shortcuts cover the common cases: `td today`, `td inbox`, `td upcoming`. The quick-add parser handles plain language — due dates, priority `p1`–`p4`, project as `#Name`, section as `/Name`, labels as `@label`.

Machine-readable output comes from `--json`, `--ndjson` and `--full`. Before anything destructive — deleting, completing, updating, archiving — the skill asks the user to confirm, and one confirmation covers a logical group of related actions. Read-only calls skip that step.

You need `td` installed and authenticated first. Check with `td auth status`, install with `npm install -g @doist/todoist-cli`, log in with `td auth login` over OAuth. Two limits worth knowing: a project has to have no uncompleted tasks before it can be deleted, and reopening a task requires its ID in `id:xxx` form.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill todoist-api -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/todoist-api/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/todoist-api/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill todoist-api -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/todoist-api/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill todoist-api -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/todoist-api/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install intellectronica/agent-skills todoist-api
```

2. **Manually: put the files in place**
- File: `.github/skills/todoist-api/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill todoist-api -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/intellectronica/agent-skills --path skills/todoist-api
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/todoist-api/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill todoist-api -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/intellectronica/agent-skills/tree/HEAD/skills/todoist-api/SKILL.md

## When to use it
- see what is due today and what slipped
- add a task with a date, priority and labels in one line
- move a task to another project or section
- pull a project's tasks as JSON for further processing
- leave a comment on a task or project

## Example prompts
- Show me today's tasks with todoist-api
- Add a task "Review PR" to the Work project, priority p2, due tomorrow
- Delete the review label from Todoist

## Source text · SKILL.md · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 03b2218bfe23b002.

BEGIN THIRD-PARTY FILE 03b2218bfe23b002
````text
---
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:

```bash
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

```bash
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

```bash
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:**
```bash
td task list --json                    # JSON array
td task list --project "Work" --json   # Filtered JSON
````
END THIRD-PARTY FILE 03b2218bfe23b002

The third-party file has ended. Everything between the 03b2218bfe23b002 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2803 of 9215 bytes. © intellectronica · CC0-1.0 · https://github.com/intellectronica/agent-skills/tree/HEAD/skills/todoist-api/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md