todoist-ts-cli

⚠️ Unofficial CLI for Todoist
Not affiliated with or endorsed by Doist.

A command-line interface for Todoist built on the official @doist/todoist-api-typescript SDK.

Installation

npm install -g todoist-ts-cli

Or run directly with npx:

npx todoist-ts-cli --help

Quick Start

# Authenticate with your API token
todoist auth <your-api-token>

# View today's tasks (default command)
todoist

# Add a task
todoist add "Buy groceries" --due tomorrow --priority 1

# Complete a task
todoist done <task-id>

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

Commands

Authentication

todoist auth <token>     # Save API token
todoist auth             # Check auth status
todoist logout           # Clear stored token

Tasks

todoist                  # Show today's tasks (default)
todoist today            # Same as above
todoist tasks            # List tasks (today + overdue)
todoist tasks --all      # All tasks
todoist tasks -p "Work"  # Tasks in project
todoist tasks -f "p1"    # Filter query (priority 1)

todoist add "Task" -d "tomorrow" -P 1 -p "Work" -l "urgent"
todoist add "Task at top" -p "Work" --top
todoist add "Task at position 3" -p "Work" --order 3
todoist view <id>        # View task details
todoist update <id> --due "next week"
todoist done <id>        # Complete task
todoist reopen <id>      # Reopen completed task
todoist move <id> -p "Personal"  # Move to project
todoist delete <id>      # Delete task
todoist search "keyword" # Search tasks

Projects

todoist projects         # List all projects
todoist project-add "New Project" --color blue

Sections

todoist sections                    # List all sections
todoist sections -p "Work"          # Sections in project
todoist section-add "Q1" -p "Work"  # Create section

Labels

todoist labels           # List all labels
todoist label-add "urgent" --color red

Comments

todoist comments <taskId>              # List comments
todoist comment <taskId> "Note text"   # Add comment

Options

Global flags available on all commands:

Flag	Description
`-h, --help`	Show help
`-V, --version`	Show version number
`--no-color`	Disable colored output
`--json`	Output as JSON (where applicable)

Environment Variables

Variable	Description
`TODOIST_API_TOKEN`	API token for authentication
`NO_COLOR`	Disable colored output (any value)

Exit Codes

Code	Meaning
`0`	Success
`1`	Generic failure
`2`	Invalid usage (bad arguments)
`3`	Authentication failure

Examples

Add task with all options

todoist add "Review PR" \
  --due "tomorrow 10am" \
  --priority 2 \
  --project "Work" \
  --label "dev" \
  --description "Check the new feature branch"

# Add task to a specific position in a project/section
todoist add "Triage inbox" --order top
todoist add "Triage inbox" --order 2

Filter tasks by priority

todoist tasks -f "p1 | p2"  # Priority 1 or 2
todoist tasks -f "overdue"  # Overdue tasks
todoist tasks -f "@urgent"  # Tasks with label

Export tasks to JSON

todoist tasks --all --json > tasks.json

Scripting

# Add task and get ID
TASK_ID=$(todoist add "Test" --json | jq -r '.id')
echo "Created task: $TASK_ID"

# Complete it
todoist done $TASK_ID

Development

git clone https://github.com/mjrussell/todoist-ts-cli
cd todoist-ts-cli
npm install
npm run build
node dist/cli.js --help

License

Disclaimer

This is an unofficial tool created by the community. Todoist is a trademark of Doist Inc. This project is not affiliated with, endorsed by, or connected to Doist in any way.

This CLI uses the official Todoist TypeScript SDK but is not an official Doist product.