todoist-cli

Manage your Todoist from the terminal. Pretty tables when you're at the keyboard, structured JSON when your scripts and AI agents are driving.

Install

pip install git+https://github.com/craigmccaskill/todoist-cli.git
td init
td completions install

Requires Python 3.10+.

Your morning

td                        # what needs your attention (today + overdue)
td tomorrow               # plan ahead
td upcoming               # next 7 days
td overdue                # just the overdue pile

Capture without breaking flow

td add call dentist tomorrow
td add review Q3 roadmap draft Friday p1
td add buy birthday present for mom this weekend

No flags needed. Todoist's NLP parses dates, priorities, and projects from natural language. When you need precision:

td add "Deploy v2.1" --project Releases --priority 1 --due 2026-04-15

Get things done

Row numbers from td work everywhere. No IDs to copy.

td done 2                 # complete task #2
td done 2 4 5             # batch complete
td done buy milk          # fuzzy match by name

Made a mistake? td undo 2.

Organize

td project add "Q3 Planning"
td section add "In Progress" -p Work
td label add urgent
td comment 2 "Picked up 2%, not whole"

Each entity group has add, edit, delete, and list. The flat shortcuts you'd expect work too: td projects, td sections, td labels.

See one project

td focus Work             # just Work's tasks
td overdue Work           # overdue in Work only
td completed Work 7d      # what you finished this week

When things go wrong

td tells you what happened and what to try:

Error: Task "ljasdf" not found.
  Suggestion: Use a row number from `td ls`, a task name, or a task ID.

Ambiguous match? td asks you to pick. No arguments? td launches a picker.

Check your setup

td doctor

One command to verify Python, config, auth, and connectivity.

Make it yours

# ~/.config/td/config.toml
[settings]
default_command = "today"     # what `td` with no args runs
default_sort = "due"          # priority, due, project, created
cache_ttl_results = 300       # how long row numbers stay valid

For scripts and AI agents

Output adapts automatically. Pipe td and you get JSON:

td ls | jq '.data[].content'

Agents can self-discover everything:

td schema          # full command manifest as JSON
td skill install   # install command reference for Claude Code

Idempotent operations, structured error codes, --json and --plain flags on every command. See the examples guide for more.

Full command list

Run td --help or see the documentation site.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT