Todoist CLI (todoist-cli)

Agent-first Todoist CLI. All output is structured JSON with next_actions hints.

Auth

Token resolves automatically: TODOIST_API_TOKEN env var → secrets lease todoist_api_token (agent-secrets).

Ref Resolution

All <ref> args accept: task name (fuzzy matched), Todoist URL, id:xxx, or raw ID. Project args (--project) also resolve by name.

todoist-cli complete "Buy milk"                                    # by name
todoist-cli show https://app.todoist.com/app/task/buy-milk-8abc    # by URL
todoist-cli show id:6g3VHV5HJGvJmPhw                              # by id: prefix

Ambiguous matches return an error listing candidates with IDs.

Priority Mapping

p1 (highest) = API value 4, p2 = 3, p3 = 2, p4 (default) = 1.

Commands

Daily Workflow

todoist-cli today                         # tasks due today + overdue
todoist-cli inbox                         # inbox tasks needing triage
todoist-cli review                        # full dashboard: today, inbox, overdue, floating, project breakdown

Search & Browse

todoist-cli search "deploy"               # full-text search
todoist-cli list --filter "priority 1 & today"
todoist-cli list --project "Agent Work"   # by project name
todoist-cli list --label "urgent"
todoist-cli show <ref>                    # task detail + comments

Task CRUD

todoist-cli add "Ship media pipeline" --due tomorrow --project "Agent Work" --priority 2
todoist-cli add "Buy groceries" --due "every saturday" --labels "errands,home"
todoist-cli add "Sub-task" --parent <taskId>
todoist-cli complete <ref>
todoist-cli reopen <ref>
todoist-cli update <ref> --content "New title" --due "next monday" --priority 3
todoist-cli move <ref> --project "Done"
todoist-cli delete <ref>

Add flags: --due, --deadline YYYY-MM-DD, --project NAME, --section ID, --parent ID, --priority 1-4, --labels a,b, --description.

Comments (Async Conversations)

Critical for agent ↔ human async threads on tasks.

todoist-cli comments <ref>                              # list comments on a task
todoist-cli comment-add <ref> --content "Started work"  # add a comment
todoist-cli comment-update <commentId> --content "Done" # update
todoist-cli comment-delete <commentId>                  # delete

Reminders

todoist-cli reminders <ref>                             # list reminders
todoist-cli reminder-add <ref> --before 30m             # 30 min before due
todoist-cli reminder-add <ref> --at 2026-02-20T10:00    # specific time
todoist-cli reminder-delete <reminderId>

Duration format: 30m, 1h, 2h30m.

Activity & History

todoist-cli activity                                    # recent activity
todoist-cli activity --since 2026-02-18 --event completed
todoist-cli activity --project "Agent Work" --type task --limit 20
todoist-cli completed                                   # completed today
todoist-cli completed --since 2026-02-17 --project "Agent Work"

Organization

todoist-cli projects                                    # list all projects
todoist-cli sections --project "Agent Work"             # sections by project name
todoist-cli labels                                      # list all labels
todoist-cli add-project "New Project" --color blue --parent "Parent"
todoist-cli add-section "Backlog" --project "Agent Work"

Output Format

Every response:

{
  "ok": true,
  "command": "todoist-cli <cmd>",
  "result": { ... },
  "next_actions": [
    { "command": "todoist-cli ...", "description": "..." }
  ]
}

Errors: { "ok": false, "error": "message" }.

Parse result.tasks[].id for IDs, result.count for totals, next_actions for what to do next.

Common Agent Patterns

Morning Review

todoist-cli review    # get full dashboard, triage inbox, check overdue

Capture from Conversation

When user mentions something actionable:

todoist-cli add "Deploy the media pipeline" --due tomorrow --project "Agent Work" --priority 2

Async Agent Thread

Agent leaves a question as a comment, user replies later:

todoist-cli comment-add "Deploy pipeline" --content "Should I deploy to staging first, or straight to prod?"
# ... later ...
todoist-cli comments "Deploy pipeline"   # check for user's reply

Weekly Retrospective

todoist-cli completed --since 2026-02-12 --until 2026-02-19
todoist-cli activity --since 2026-02-12 --event completed --limit 50