joelhooks 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"
Activity filters: --since, --until, --type (task|comment|project), --event (added|completed|updated|deleted), --project NAME, --limit N.
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