Introduction
# Todoist Skill — Natural Language Task Management
Manage your Todoist tasks conversationally. No need to remember CLI syntax — just talk naturally about your tasks.
## Natural Language Examples
This skill understands conversational requests:
**List tasks:** - "What tasks do I have today?" - "Show me my Todoist list for this week" - "What do I have overdue?" - "Show priority 1 tasks"
**Add tasks:** - "Add 'buy milk' to my todo list" - "Create a task to call the dentist tomorrow" - "I need to review the Q4 report by Friday" - "Add 'weekly standup' due every Monday"
**Complete tasks:** - "Complete my task about the dentist" - "Mark the milk task as done" - "I finished the report"
**Manage projects:** - "What projects do I have in Todoist?" - "Show tasks from my Work project"
## Prerequisites
- `TODOIST_API_KEY` environment variable must be set with your Todoist API token - Get your token at: https://todoist.com/app/settings/integrations/developer
## Technical Usage
If you prefer CLI commands or need to script operations, use the Python script directly:
```bash # List today's tasks python3 todoist/scripts/todoist.py list --filter "today"
# Add a task python3 todoist/scripts/todoist.py add "Buy milk" --due "tomorrow" --priority 2
# Complete a task by ID python3 todoist/scripts/todoist.py complete "TASK_ID"
# List all projects python3 todoist/scripts/todoist.py projects ```
## Filter Syntax
When filtering tasks (via natural language or CLI):
- `today` — tasks due today - `overdue` — overdue tasks - `tomorrow` — tasks due tomorrow - `p1`, `p2`, `p3`, `p4` — priority filters - `7 days` — tasks due in next 7 days - `@label` — tasks with specific label - `#project` — tasks in project - Combine with `&` (and) and `|` (or): `today & p1`
## Priority Levels
- `1` — Urgent (red) - `2` — High (orange) - `3` — Medium (blue) - `4` — Low (white/gray, default)
## Features
- ✅ Natural language task management - ✅ Timezone-aware "today" filtering - ✅ Smart filtering (excludes completed tasks) - ✅ Recurring task support - ✅ Full Todoist API v1 coverage
## Response Format
The script outputs JSON for programmatic use. See `references/api.md` for full API documentation.
## Notes
- The skill automatically filters out completed tasks - "Today" uses your local timezone (set `TZ` environment variable if needed) - Natural language dates ("tomorrow", "next Friday") use Todoist's built-in parsing