47 releases

0.5.7 Nov 5, 2023
0.5.2 Sep 19, 2023
0.4.8 Jun 27, 2023
0.3.3 Mar 21, 2023
0.1.0 Nov 11, 2020

#24 in Command line utilities

Download history 48/week @ 2023-11-03 58/week @ 2023-11-10 14/week @ 2023-11-17 59/week @ 2023-11-24 104/week @ 2023-12-01 2/week @ 2023-12-08 56/week @ 2023-12-15 100/week @ 2023-12-22 12/week @ 2023-12-29 52/week @ 2024-01-05 2/week @ 2024-01-12 39/week @ 2024-01-19 52/week @ 2024-01-26 51/week @ 2024-02-02 101/week @ 2024-02-09 850/week @ 2024-02-16

1,054 downloads per month

MIT license



Build Status codecov Crates.io

A tiny Todoist CLI program. Takes simple input and dumps it in your inbox or another project. Takes advantage of natural language processing to assign due dates, tags, etc.


Table of Contents

Will ask for your Todoist API token on the first run


Crates.io (Linux, Mac, and Windows)

Install Rust

# Linux and MacOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install Tod

cargo install tod

AUR (Arch-based Linux)

# Use yay or another AUR helper
yay tod-bin

GitHub (Linux, Mac, and Windows)

Install Rust

Clone the project

git clone git@github.com:alanvardy/tod.git
cd tod
./test.sh # run the tests
cargo build --release

You can then find the binary in /target/release/


Discovering the commands

> tod -h

A tiny unofficial Todoist client

Usage: tod [OPTIONS] [COMMAND]

  help     Print this message or the help of the given subcommand(s)

  -o, --config <CONFIGURATION PATH>  Absolute path of configuration. Defaults to $XDG_CONFIG_HOME/tod.cfg
  -q, --quickadd <quickadd>...       Create a new task with natural language processing.
  -h, --help                         Print help
  -V, --version                      Print version

And also use it to dig into subcommands

> tod task -h

Usage: tod task <COMMAND>

  create    Create a new task
  list      List all tasks in a project
  next      Get the next task by priority
  complete  Complete the last task fetched with the next command
  help      Print this message or the help of the given subcommand(s)

  -h, --help     Print help
  -V, --version  Print version

Usage Examples

# Quickly create a task
tod -q Buy more milk today

# Create a new task (you will be prompted for content and project)
tod task create

# Create a task in a project
tod task create --content "Write more rust" --project code

# Import your projects
tod project import

# Get the next task for a project
tod task next

# Go through tasks with an interactive prompt, completing them in order of importance one at a time.
tod project process

# Complete the last "next task" and get another
tod task complete && tod task next

# Get your work schedule
tod tasks list --scheduled --project work

# Get all tasks for work
tod tasks list --project work

Shell script examples

Sort, schedule, prioritize, and process tasks

  echo "" && \
  echo "=== EMPTYING INBOX ===" && \
  tod project empty --project inbox && \
  echo "" && \
  echo "=== SCHEDULING DIGITAL ===" && \
  tod project schedule --project digital && \
  echo "" && \
  echo "=== SCHEDULING PHYSICAL ===" && \
  tod project schedule --project physical && \
  echo "" && \
  echo "=== PRIORITIZING DIGITAL ===" && \
  tod project prioritize --project digital && \
  echo "" && \
  echo "=== PRIORITIZING PHYSICAL ===" && \
  tod project prioritize --project physical
  echo "" && \
  echo "=== PROCESSING DIGITAL ===" && \
  tod project process --project digital && \
  echo "" && \
  echo "=== PROCESSING PHYSICAL ===" && \
  tod project process --project physical;

Update Tod only if it is out of date

tod version check || cargo install tod --force

How task priority is determined

Tasks are ranked by points and the first is returned, the points are the sum of the following:

  • Task is overdue: 150
  • The date is today with no time: 100
  • The date is today with time in next or last 15 min: 200
  • No date: 80
  • Not recurring: 50
  • Task has no priority: 2
  • Priority 1: 1
  • Priority 2: 3
  • Priority 3: 4

Why I made this

I am a developer who uses Todoist to reduce stress and cognitive overhead, by delegating things that a machine does well to a machine. This CLI application scratches some very specific itches for me, and I hope that it may be of use to others as well!

Some points around my general strategy:

  • Do one thing at a time, multitasking is an illusion (see tod project process)
  • Capture all tasks immediately with the inbox and add detail later (see tod project empty, schedule, and prioritize)
  • Make all your tasks "actions", concrete tasks that can be acted on. Add phone numbers, hyperlinks etc. to your tasks
  • Batch process like things as infrequently as possible to lower context switching, i.e. clear your email inbox once per day, spam once per week.
  • Remember that the objective is to get the important things done with less friction, not just get more things done.
  • Further to the above point, make sure to leave yourself margin. It is in the spaces between the periods work that we recover and get our best ideas.
  • Fewer projects are better than more projects
  • Use projects as "modes" where you only work in one at a time


Contributions are welcome, just please open up an issue before putting too much work into a PR. If you would like clarification on any tickets, be sure to ask! I also enjoy supporting people newer to Rust and am happy to review PRs and give pointers.

Setting up for development

You will need to install tarpaulin with cargo install cargo-tarpaulin before running ./test.sh locally.



Data is stored in JSON format in $XDG_CONFIG_HOME/tod.cfg. This defaults to:

  • ~/.config/tod.cfg on Linux
  • ~/Library/Application Support/tod.cfg on Mac
  • No idea about Windows, sorry!



  type: nullable string
  default: null
  possible_values: any string in format YYYY-MM-DD

Holds a string date, i.e. "2023-08-30" representing the last time crates.io was checked for the latest tod version. Tod will check crates.io a maximum of once per day.


  type: nullable non-negative integer
  default: null
  possible values: any integer 0 or greater

Used in test only, instead of displaying a select picker in test instead the zero-based number will be used to choose the item.


  type: nullable string
  default: null
  possible values: any string

Used in test only, instead of displaying a text in test instead the string will be returned.


  type: nullable string
  default: null
  possible values: any URL

Used in test only, gives the location of the mock server so that external APIs are not used in test.


  type: nullable string
  default: null
  possible values: null or any positive integer in string form

When task next is executed the ID is stored in this field. When task complete is run the field is set back to null


  type: string
  default: $XDG_CONFIG_HOME/tod.cfg
  possible values: Any path

Location of the tod configuration file


  type: nullable boolean
  default: null
  possible values: null, true, or false

If true, the datetime selection in project schedule will go straight to natural language input.


  type: nullable boolean
  default: null
  possible values: null, true, or false

If true will not prompt for a section whenever possible


  type: nullable boolean
  default: null
  possible values: null, true, or false

Controls whether the spinner is displayed when an API call occurs. Useful for cases where the terminal output is captured. null is considered the same as true.

You can also use the environment variable DISABLE_SPINNER to turn them off.

  DISABLE_SPINNER=1 tod task create


  type: string
  default: No default
  possible values: Any timezone string i.e. "Canada/Pacific"

You will be prompted for timezone on first run


  type: string
  default: No default
  possible values: Any valid token

You will be prompted for your Todoist API token on first run


  type: Nullable array of objects
  default: null
  possible values: List of project objects from the Todoist API

Projects are stored locally in config to help save on API requests and speed up actions taken. Manage this with the project subcommands. The strange naming is because projects was used in previous versions of tod.


  type: nullable boolean
  default: null
  possible values: null, true, or false

Outputs additional information in console to assist with debugging.


~437K SLoC