td

A fast Todoist CLI written in Go.

Mainly for Agents to use but Humans are welcome too.

Notes

• Not all Todoist API functions are implemented, just the most useful.

Setup

1. Get a Todoist API token from Settings > Integrations > Developer.
2. Export it: sh export TODOIST_API_TOKEN="your-token-here"
3. Build: sh go build -o td .

Usage

All commands support --json for machine-readable output.

View tasks

td today                            # Due today + overdue
td week                             # Due in the next 7 days
td tasks                            # All active tasks
td tasks --filter "p1 | p2"         # Todoist filter syntax
td tasks --filter "#Work"           # Tasks in a project
td search deploy                    # Keyword search
td completed                        # Recently completed tasks
td completed -n 50                  # Last 50 completed

Manage tasks

td add Buy groceries                          # Quick add
td add Fix login bug -p p1 -d tomorrow        # With priority and due date
td add Write docs --project 12345 --desc "API reference"  # With project and description
td add Review PR -l urgent -l work            # With labels

td update 12345 -d "next monday"              # Reschedule
td update 12345 -p p2 -c "New title"          # Change priority and content

td done 12345                                 # Complete a task
td done 12345 67890                           # Complete multiple

td delete 12345                               # Delete a task

Task details & comments

td show 12345                                 # Full task details + comments
td comment 12345 Looks good, shipping it      # Add a comment

Projects

td projects                                   # List all projects
td overview                                   # Summary with task counts per project
td overview -p Personal                       # Detailed view of a project (by name)
td overview -p 12345                          # Detailed view (by ID)

Agent reference

td agent                                # Full CLI reference in one shot (no auth required)

Prints a compact, structured plain-text reference covering all commands, flags, priority mapping, filter syntax, and output behavior. Designed to be consumed by LLM agents in a single context load.

Development

go test ./...       # Run all tests
go build -o td .    # Build binary