@mindfullabai/todoist-cli

AI-native Todoist CLI. Self-describing for AI agents via --ai flag. ~84% fewer tokens than MCP.

Why not MCP?

MCP servers load their complete tool schema into the AI's context window at conversation start. For Todoist, that's 4,243 tokens for 14 tools - before any work happens.

This CLI uses 205 tokens for the same discovery. Per-operation savings: 65%. Total session savings: 84% (6.2x).

See our benchmark for real numbers.

Install

npm install -g @mindfullabai/todoist-cli

Set your API token:

export TODOIST_API_TOKEN="your-token-here"

Usage

Tasks

todoist tasks                              # Today + overdue
todoist tasks --project "1. Building"      # Filter by project name
todoist tasks --all                        # All active tasks
todoist task create "Deploy v2" --project "1. Building" --due "friday" --priority 3
todoist task complete <id>
todoist task update <id> --due "next monday"
todoist task move <id> --project "0. Career"
todoist task delete <id>
todoist task reopen <id>

Reminders (Pro account required)

# Absolute reminder: push notification at exact datetime
todoist task create "Call client" --due "2026-05-23 14:00" --reminder "2026-05-23 13:30"

# Relative reminder: push notification N minutes before due
todoist task create "Publish Onda Short" --due "2026-05-23 14:00" --reminder-before 30

# JSON output includes reminder_id
todoist task create "Meeting" --due "tomorrow 10:00" --reminder-before 15 --json

Completed Tasks

todoist completed                          # Today
todoist completed --week                   # This week
todoist completed --since 2026-03-01 --until 2026-03-19
todoist completed --project "1. Building"

Projects

todoist projects                           # List all
todoist project <id>                       # Details
todoist project create "New Project" --color berry_red
todoist project update <id> --name "Renamed"
todoist project delete <id>

AI Agent Integration

This CLI is designed to be used by AI agents (Claude Code, Cursor, etc.) as a more efficient alternative to MCP.

Discovery

todoist --ai              # Full JSON manifest (all commands, params, examples)
todoist --ai brief        # One-liner per command (~205 tokens)
todoist --ai examples     # Usage examples
todoist --ai tasks        # Schema for specific command

Claude Code Setup

todoist setup-claude      # Installs skill + permissions automatically

This creates a skill file at ~/.claude/skills/todoist-cli/SKILL.md and adds Bash(todoist:*) permission.

Output Format

Default output is plain text, optimized for minimal token usage:

# Tasks - today + overdue
- [6g64wC7x3] Deploy v2 (due: 2026-03-20, p3, labels: Task#1, project: 1. Building)
- [6g7R3FXpC] Fix auth bug (due: 2026-03-19, p4, project: 1. Building)

Use --json flag for structured JSON output when needed.

Benchmark

Real measurements comparing this CLI vs the equivalent MCP server (same Todoist account, same operations):

Metric	MCP	CLI	Savings
Discovery (per conversation)	4,243 tokens	205 tokens	95%
"List today's tasks" (5 tasks)	~530 tokens	~183 tokens	65%
Per-task response	~96 tokens	~32 tokens	67%
Typical session (5 ops)	6,893 tokens	1,120 tokens	84%

Part of the AI-Native CLI Pattern

This tool follows the AI-native CLI pattern: command-line tools that self-describe via --ai flag for AI agent consumption.

Other tools using this pattern:

• @mindfullabai/ai-vision-cli - Image/video analysis with Gemini

License

MIT