todoist-cli

name	todoist-cli
description	Todoist workflow assistant powered by Todoist CLI (td). Use to plan daily work, triage inbox/today/upcoming tasks, run weekly reviews, reorganize projects/sections/labels, manage reminders/comments/notifications, perform safe bulk edits, and summarize what changed.
homepage	https://github.com/Doist/todoist-cli
metadata	{"openclaw":{"emoji":"✅"}}

Todoist CLI (td)

Use this skill as a Todoist productivity operator, not just a command reference. Translate user intent (plan, triage, review, clean up, automate) into concrete td workflows and explain outcomes clearly.

What this skill provides

• Daily planning and triage: today/inbox/upcoming/completed views to decide what to do next.
• Task lifecycle management: create, update, move, complete, reopen, and delete tasks.
• Organization management: projects, sections, labels, filters, and workspace-level operations.
• Collaboration workflows: comments, assignees, shared labels, notifications, and reminders.
• Review and analytics: activity logs, productivity stats, and user settings.
• Flexible references: act on tasks/projects by name, id:..., or Todoist URL.

Assistant behavior and context

• Start by understanding the user goal (daily plan, backlog cleanup, weekly review, etc.).
• For broad or risky requests, list first, then mutate (preview before changes).
• Ask for confirmation before destructive actions (delete, archive, bulk completion) unless explicitly requested.
• Prefer --json/--ndjson when output needs to be filtered, counted, or reused programmatically.
• After running commands, summarize what changed: counts, key items, and next recommended action.

Typical intent-to-workflow mapping

• "Plan my day" → td today, optionally filter by workspace/priority, then propose top tasks.
• "Clean my inbox" → td inbox + classify by project/label/due date, then move/update in batches.
• "Weekly review" → td upcoming 14, td completed, td activity, and identify carry-overs.
• "Set up follow-up" → update due dates/assignees and add reminders/comments.

Setup

1) Install todoist-cli

npm install -g @doist/todoist-cli

If you need to run from source instead:

git clone https://github.com/Doist/todoist-cli.git
cd todoist-cli
npm install
npm run build
npm link

2) Authenticate

Preferred (browser OAuth):

td auth login

Alternative (manual token):

td auth token "your-token"

Or via environment variable:

export TODOIST_API_TOKEN="your-token"

3) Verify auth

td auth status

Quick Reference

• td today - Tasks due today and overdue
• td inbox - Inbox tasks
• td upcoming - Tasks due in next N days
• td completed - Recently completed tasks
• td task add "content" - Add a task
• td task list - List tasks with filters
• td task complete <ref> - Complete a task
• td project list - List projects
• td label list - List labels
• td filter list/view - Manage and use saved filters
• td workspace list - List workspaces
• td activity - Activity logs
• td notification list - Notifications
• td reminder add - Task reminders
• td stats - Productivity stats
• td settings view - User settings
• td completion install - Install shell completions
• td view <url> - View supported Todoist entities/pages by URL

Output Formats

All list commands support:

• --json - JSON output (essential fields)
• --ndjson - Newline-delimited JSON (streaming)
• --full - Include all fields in JSON
• --raw - Disable markdown rendering

Shared List Options

Most list commands also support:

• --limit <n> - Limit number of results
• --all - Fetch all results (no limit)
• --cursor <cursor> - Continue from pagination cursor
• --show-urls - Show web app URLs for each item

Global Options

• --no-spinner - Disable loading animations
• --progress-jsonl - Machine-readable progress events (JSONL to stderr)
• -v, --verbose - Verbose output to stderr (repeat: -v info, -vv detail, -vvv debug, -vvvv trace)

References

Tasks, projects, labels, and filters can be referenced by:

• Name (fuzzy matched within context)
• id:xxx - Explicit ID
• Todoist URL pasted from the web app

Priority Mapping

• p1 = Highest priority (API value 4)
• p2 = High priority (API value 3)
• p3 = Medium priority (API value 2)
• p4 = Lowest priority (API value 1, default)

Commands

Today

td today
td today --json
td today --workspace "Work"
td today --personal
td today --any-assignee

Inbox

td inbox
td inbox --priority p1
td inbox --due today

Upcoming

td upcoming
td upcoming 14
td upcoming --workspace "Work"
td upcoming --personal
td upcoming --any-assignee

Completed

td completed
td completed --since 2024-01-01 --until 2024-01-31
td completed --project "Work"

Task Management

# List
td task list --project "Work"
td task list --label "urgent" --priority p1
td task list --due today
td task list --filter "today | overdue"
td task list --assignee me
td task list --assignee "[e-mail]"
td task list --unassigned
td task list --workspace "Work"
td task list --personal
td task list --parent "Parent task"

# View, complete, uncomplete
td task view "task name"
td task complete "task name"
td task complete id:123456
td task complete "task name" --forever
td task uncomplete id:123456

# Add
td task add "New task" --due "tomorrow" --priority p2
td task add "Task" --deadline "2024-03-01" --project "Work"
td task add "Task" --duration 1h --section "Planning" --project "Work"
td task add "Task" --labels "urgent,review" --parent "Parent task"
td task add "Task" --description "Details here" --assignee me

# Update
td task update "task name" --due "next week"
td task update "task name" --deadline "2024-06-01"
td task update "task name" --no-deadline
td task update "task name" --duration 2h
td task update "task name" --assignee "[e-mail]"
td task update "task name" --unassign

# Move
td task move "task name" --project "Personal"
td task move "task name" --section "In Progress"
td task move "task name" --parent "Parent task"
td task move "task name" --no-parent
td task move "task name" --no-section

# Delete and browse
td task delete "task name" --yes
td task browse "task name"

Projects

td project list
td project list --personal
td project view "Project Name"
td project collaborators "Project Name"
td project create --name "New Project" --color "blue"
td project update "Project Name" --favorite
td project archive "Project Name"
td project unarchive "Project Name"
td project delete "Project Name" --yes
td project browse "Project Name"
td project move "Project Name" --to-workspace "Acme"
td project move "Project Name" --to-workspace "Acme" --folder "Engineering"
td project move "Project Name" --to-workspace "Acme" --visibility team
td project move "Project Name" --to-personal

Labels

td label list
td label view "urgent"
td label create --name "urgent" --color "red"
td label update "urgent" --color "orange"
td label delete "urgent" --yes
td label browse "urgent"

Comments

td comment list --task "task name"
td comment list --project "Project Name" -P
td comment add --task "task name" --content "Comment text"
td comment add --task "task name" --content "See attached" --file ./report.pdf
td comment view id:123
td comment update id:123 --content "Updated text"
td comment delete id:123 --yes
td comment browse id:123

Sections

td section list "Work"
td section list --project "Work"
td section create --project "Work" --name "In Progress"
td section update id:123 --name "Done"
td section delete id:123 --yes
td section browse id:123

Filters

td filter list
td filter create --name "Urgent work" --query "p1 & #Work"
td filter view "Urgent work"
td filter update "Urgent work" --query "p1 & #Work & today"
td filter delete "Urgent work" --yes
td filter browse "Urgent work"

Workspaces

td workspace list
td workspace view "Workspace Name"
td workspace projects "Workspace Name"
td workspace users "Workspace Name" --role ADMIN,MEMBER

Activity

td activity
td activity --since 2024-01-01 --until 2024-01-31
td activity --type task --event completed
td activity --project "Work"
td activity --by me

Notifications

td notification list
td notification list --unread
td notification list --type "item_assign"
td notification view id:123
td notification read --all --yes
td notification accept id:123
td notification reject id:123

Reminders

td reminder list "task name"
td reminder add "task name" --before 30m
td reminder add "task name" --at "2024-01-15 10:00"
td reminder update id:123 --before 1h
td reminder delete id:123 --yes

Stats

td stats
td stats --json
td stats goals --daily 10 --weekly 50
td stats vacation --on
td stats vacation --off

Settings

td settings view
td settings view --json
td settings update --timezone "America/New_York"
td settings update --time-format 24 --date-format intl
td settings themes

Shell Completions

td completion install
td completion install bash
td completion install zsh
td completion install fish
td completion uninstall

View (URL Router)

td view <todoist-url>
td view https://app.todoist.com/app/task/buy-milk-abc123
td view https://app.todoist.com/app/project/work-def456
td view https://app.todoist.com/app/label/urgent-ghi789
td view https://app.todoist.com/app/filter/work-tasks-jkl012
td view https://app.todoist.com/app/today
td view https://app.todoist.com/app/upcoming
td view <url> --json
td view <url> --limit 25 --ndjson

Workflow Examples

Daily triage

td today --json | jq '.results | length'
td inbox --limit 5
td upcoming
td completed

High-priority work

td task list --project "Work" --label "urgent" --priority p1
td task list --filter "today & #Work"

Fast completion loop

td task complete "Review PR"
td task complete id:123456789
td task uncomplete id:123456789