todoist-cli

A fast, full-featured Todoist CLI written in Go.

Installation

Homebrew (macOS/Linux)

brew install buddyh/tap/todoist

Go

go install github.com/buddyh/todoist-cli/cmd/todoist@latest

Build locally

git clone https://github.com/buddyh/todoist-cli
cd todoist-cli
make build
./bin/todoist --help

Authentication

Get your API token from https://todoist.com/app/settings/integrations/developer

# Interactive
todoist auth

# Direct
todoist auth <your-token>

# Or set environment variable
export TODOIST_API_TOKEN=<your-token>

Usage

Tasks

# Show today's tasks (default)
todoist

# List all tasks
todoist tasks --all

# Filter tasks
todoist tasks --filter "p1"        # High priority
todoist tasks --filter "overdue"   # Overdue
todoist tasks -p Work              # By project

# Sort tasks
todoist tasks --sort priority      # By priority (highest first)
todoist tasks --sort due           # By due date
todoist tasks --sort name          # Alphabetical
todoist tasks --sort created       # By creation date

# Show task descriptions and comments
todoist tasks -p Work --details

# Add a task
todoist add "Buy groceries"
todoist add "Call mom" -d tomorrow
todoist add "Urgent" -P 1 -d "today 5pm" -l urgent

# Subtasks
todoist add "Subtask" --parent <task-id>

# Position control
todoist add "Top priority" --top
todoist add "Second item" --order 2

# Assign to collaborator
todoist add "Review PR" -p Work --assignee "John"

# Complete a task
todoist complete <task-id>
todoist done <task-id>

# View task details
todoist view <task-id>

# Update a task
todoist update <task-id> --due "next monday"
todoist update <task-id> -P 2
todoist update <task-id> --assignee "Jane"

# Delete a task
todoist delete <task-id>

# Move a task (Kanban workflows)
todoist move <task-id> --section "In Progress"
todoist move <task-id> --project "Work"

# Search
todoist search "meeting"

Projects

# List projects
todoist projects

# Create project
todoist projects add "New Project" --color blue

Labels

# List labels
todoist labels

# Create label
todoist labels add urgent --color red

Sections

# List sections
todoist sections -p Work

# Create section
todoist sections add "In Progress" -p Work

Comments

# View comments on a task
todoist comment <task-id>

# Add a comment
todoist comment <task-id> "This is a note"

Collaborators

# List project collaborators
todoist collaborators -p Work

Completed Tasks

# Show recently completed
todoist completed

# Filter by date
todoist completed --since 2024-01-01 --limit 50

Configuration

# Show config (masked token, path, source)
todoist config

# Validate API connection
todoist config --validate

Shell Completion

# Bash
source <(todoist completion bash)

# Zsh
source <(todoist completion zsh)

# Fish
todoist completion fish | source

# PowerShell
todoist completion powershell | Out-String | Invoke-Expression

Global Flags

Flag	Description
--json	Output JSON instead of human-readable text
--color auto|always|never	Control color output (respects NO_COLOR and TERM=dumb)
--debug	Show HTTP request/response tracing on stderr

JSON Output

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

todoist tasks --json | jq '.data[] | .content'

Command Reference

Command	Description
todoist	Show today's tasks
todoist tasks	List tasks with filters
todoist add	Create a new task
todoist complete	Mark task complete
todoist done	Alias for complete
todoist delete	Delete a task
todoist update	Update a task
todoist move	Move task to section/project
todoist view	View task details
todoist search	Search tasks
todoist projects	List/manage projects
todoist labels	List/manage labels
todoist sections	List/manage sections
todoist comment	View/add comments
todoist collaborators	List project collaborators
todoist completed	Show completed tasks
todoist reopen	Reopen completed task
todoist config	Show configuration
todoist completion	Generate shell completions
todoist auth	Authenticate

Priority Mapping

CLI	Todoist
-P 1	p1 (highest)
-P 2	p2
-P 3	p3
-P 4	p4 (lowest)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Usage error
3	Authentication error
4	Network error

License

MIT