Todoist CLI (td)

Uses the Official Todoist CLI tool for task management.

> AI/LLM note (from the CLI itself): Use td task add (not td add) for structured task creation. Use --json or --ndjson for parseable output.

Installation

npm install -g @doist/todoist-cli

Setup

Get your API token at: https://todoist.com/app/settings/integrations/developer

td auth token "your-token"
# or
export TODOIST_API_TOKEN="your-token"

Viewing Tasks

td today                          # Today + overdue
td upcoming                       # Next 7 days
td upcoming 14                    # Next N days
td inbox                          # Inbox tasks
td completed                      # Completed today
td completed --since 2026-01-01   # Completed since date

Adding Tasks

Prefer td task add with structured flags for reliability:

td task add "Review PR" --due "today" --priority p1 --project "Work"
td task add "Call mom" --due "sunday" --labels "family"
td task add "Prep slides" --project "Work" --section "Q1" --order 0  # 0 = top
td task add "Subtask" --parent <ref>
td task add "Meeting" --due "tomorrow 10am" --duration 1h

Quick add (natural language, for humans — avoid in automation):

td add "Buy milk tomorrow p1 #Shopping @errands"

Listing & Viewing Tasks

td task list                          # All tasks
td task list --project "Work"         # By project
td task list --priority p1            # By priority
td task list --label "urgent"         # By label
td task list --due today              # Due today
td task list --filter "p1 & today"    # Raw Todoist filter query
td task list --json                   # JSON output
td task view <ref>                    # Task details
td view <todoist-url>                 # View any entity by URL

Managing Tasks

td task complete <ref>                # Complete task
td task complete <ref> --forever      # Complete recurring task permanently
td task uncomplete id:<id>            # Reopen task (requires id:xxx)
td task update <ref> --due "next week" --priority p2
td task update <ref> --content "New title"
td task update <ref> --labels "a,b"   # Replaces existing labels
td task move <ref> --project "Personal"
td task reschedule <ref> "next monday" # Preserves recurrence
td task delete <ref>

Projects

td project list
td project create --name "New Project"
td project view <ref>
td project update <ref> --name "Renamed"
td project archive <ref>
td project delete <ref>               # Must have no uncompleted tasks

Sections

td section list <project>
td section create --project "Work" --name "Q2"
td section update <id> --name "Renamed"
td section delete <id>

Labels

td label list
td label create --name "urgent"
td label update <ref> --name "renamed"
td label delete <name>
td label view <ref>                   # View label + its tasks

Comments

td comment list <task-ref>
td comment add <task-ref> "Note about this task"
td comment add <task-ref> --project   # Comment on project instead
td comment update <id> "Updated text"
td comment delete <id>

Reminders

td reminder list <task-ref>
td reminder add <task-ref> --due "tomorrow 9am"
td reminder update <id> --due "friday 10am"
td reminder delete <id>

Activity & Stats

td activity                           # Recent activity log
td activity --type task --event completed --since 2026-03-01
td stats                              # Karma + productivity stats

Usage Examples

User: "What do I have today?"

td today

User: "Add 'buy milk' to my tasks"

td task add "Buy milk" --due "today"

User: "Remind me to call the dentist tomorrow"

td task add "Call the dentist" --due "tomorrow"

User: "Mark the grocery task as done"

td task list --filter "search: grocery" --json   # Find ref
td task complete <ref>

User: "What's on my work project?"

td task list --project "Work"

User: "Show my high priority tasks"

td task list --priority p1

User: "What did I complete this week?"

td completed --since 2026-03-10

Notes

• can be a task name (fuzzy match), URL, or id:xxx
• --order 0 = top of list (differs from mjrussell's --order top)
• Priority: p1 = highest, p4 = lowest
• Due dates support natural language ("tomorrow", "next monday", "jan 15")
• --json / --ndjson recommended for any programmatic parsing
• --full adds all fields to JSON output
• --accessible / TD_ACCESSIBLE=1 adds text labels to color-coded output (useful in non-TTY contexts)