doist - Todoist CLI Client

An unofficial Todoist API CLI client written in Rust.

About

This is an unofficial Todoist CLI that focuses on being easy to use. It is currently not feature complete, but covers some basic common use-cases and adds more as we go along.

Installation

doist runs on macOS, Linux and Windows. Each method below installs the doist binary. The releases are on the release page. RELEASING.md tells how a release is made.

Homebrew

On macOS and Linux, install the cask from the tap:

brew install --cask chaosteil/tap/doist

The cask is in chaosteil/homebrew-tap. The macOS binary is not signed. The cask removes the quarantine flag of macOS after the install, so that macOS starts the binary (GoReleaser).

The tap had a formula doist before. If you installed the formula, run brew update. Homebrew then moves you to the cask (tap_migrations.json of the tap, see Homebrew). You can also do it yourself:

brew uninstall --formula doist
brew install --cask chaosteil/tap/doist

Install from crates.io

# Install Rust first: https://www.rust-lang.org/tools/install
cargo install --locked doist
# Binary now available in $HOME/.cargo/bin/doist

Cargo compiles doist. You need Rust 1.88 or later. --locked uses the dependency versions of Cargo.lock (cargo install).

cargo-binstall

cargo binstall doist

cargo-binstall downloads the prebuilt archive of the GitHub release, and does not compile.

Nix

Run doist without an install:

nix run github:chaosteil/doist

Install it in your profile:

nix profile install github:chaosteil/doist

You can also add the flake as an input of your own flake, and use doist.packages.<system>.default. The flake has packages for x86_64-linux, aarch64-linux and aarch64-darwin.

Debian, Ubuntu and Fedora

Download the .deb or .rpm file for your CPU from the release page. Then install it with your package manager:

sudo apt install ./doist_X.Y.Z_amd64.deb         # Debian, Ubuntu
sudo dnf install ./doist-X.Y.Z-1.x86_64.rpm      # Fedora

Prebuilt archives

The release page has an archive doist_X.Y.Z_<target>.tar.gz for each target, and a .zip file for Windows:

Target	System
aarch64-apple-darwin	macOS on Apple silicon
x86_64-apple-darwin	macOS on Intel
x86_64-unknown-linux-musl	Linux on x86_64 (static binary)
aarch64-unknown-linux-musl	Linux on ARM64 (static binary)
x86_64-pc-windows-gnu	Windows on x86_64 (.zip)

Each archive has the binary, the README and the license. checksums.txt has the SHA-256 sum of each file.

1. Download the archive and checksums.txt.

2. Make sure that the sum is correct:

   sha256sum --check --ignore-missing checksums.txt         # Linux
   shasum -a 256 --check --ignore-missing checksums.txt     # macOS
   

   On Windows, compare the output of Get-FileHash doist_X.Y.Z_x86_64-pc-windows-gnu.zip in PowerShell with the line in checksums.txt.

3. Extract the binary to a directory on your PATH:

   tar -xzf doist_X.Y.Z_aarch64-apple-darwin.tar.gz -C ~/.local/bin doist
   

   On Windows, extract doist.exe from the .zip file.

4. If you downloaded the archive with a browser on macOS, remove the quarantine flag:

   xattr -d com.apple.quarantine ~/.local/bin/doist
   

Build from source

# Install Rust first: https://www.rust-lang.org/tools/install
git clone https://github.com/chaosteil/doist
cd doist
cargo build --release
./target/release/doist

To install the binary in ~/.cargo/bin, run cargo install --locked --path .. The minimum Rust version is 1.88 (rust-version in Cargo.toml).

How to use

Auth

First, set up your API token. Go into your Todoist settings, go to Integrations and copy out the API token. Plug it into the tool:

doist auth MY_TOKEN

Now you're authenticated and can use the other functions of the tool.

List tasks

Listing tasks and then working with them interactively is the recommended way to work with the CLI.

By default the list view shows todays tasks and lets you work with them:

doist
# Alternatively: `doist list` or `doist l`.

This will allow you to type parts of the output until you select the task you want to work with (fuzzy search). Selecting will allow you to select various other subcommands, like closing, changing due dates or even editing tasks.

You can also disable interactive mode to pipe use the output somewhere else:

doist list --nointeractive
# Alternatively: `doist l -n`

By default all interactive commands have a filter applied to show the most relevant tasks. See the documentation to see what inputs are accepted. To then use the filter, add it to the command parameters:

doist list --filter "all"
# Alternatively: `doist l -f all`

Interactive (continuous) mode

To continue to use doist list with the currently applied filters after each action (so you can close multiple tasks one after the other for example), a super-interactive (continuous) mode is also available. This makes the experience closer to the official app.

doist list --interactive
# Alternatively: `doist -i`

To close out of this mode, press ESC during the main list selection.

Adding tasks

A quick way to add a task is:

doist add "Do the laundry" --desc "I always forget" --due "tomorrow"
# Alternatively: `doist a "Do the laundry" -D "I always forget" -d tomorrow`

Only the task name is required, everything else will assume a default of nothing.

Interactive task creation

Another way to fully interactively create tasks is:

doist create
# Alternatively: `doist A`

Which will prompt you for the task name and then give you an interactive menu where you can fill in the details as necessary.

More about tasks

It's also possible to provide the task with a priority:

doist add "Party hard" --priority 1
# Alternatively: `doist a "Party hard" -p1`

There are several other things you can do to add richer information to a task. All inputs can be partially provided and will fuzzy match to the closest name you probably had in mind:

# Adding project information
doist add "Party hard" --project "personal"
# Alternatively: `doist a "Party hard" -P personal`

# Adding section information. Will automatically attach to the correct project,
# but setting the project will narrow it down.
doist add "Party hard" --section "weekend"
# Alternatively: `doist a "Party hard" -S weekend`
doist add "Party hard" --project personal --section weekend
# Alternatively: `doist a "Party hard" -P personal -S weekend`

# Multiple labels can be provided when creating tasks as well
doist add "Party hard" --label dance --label happy
# Alternatively: `doist a "Party hard" -L dance -L happy`

Instead of providing names to be matched, you can also directly provide their API IDs if you use this tool for automated tooling.

Closing tasks

A quick way to close one of todays tasks is:

doist close
# Alternatively: `doist c`

And then fuzzy finding the task you want to close. Submitting the ID directly also works if you're more comfortable with that:

doist close "BIG_ID_FROM_API"
# Alternatively: `doist c BIG_ID_FROM_API`

View details

To view details of tasks and the comments asssociated with a task:

doist view
# Alternatively: `doist v`

This accepts the same parameters as doist list for task selection.

Configuration setup

Disable colors

If you're not a fan of emojis or colors, you can disable all doist-induced colors by setting the environment variable NO_COLOR:

NO_COLOR=1 doist

Custom default filter

If you don't like the default filter of (today | upcoming), you can set a different default filter in the ~/.config/doist/config.toml like this:

default_filter="all"

See the Todoist article on filtering for more information.

Help

Feel free to browse the help output for more help:

doist help