Todoister

Todoister is a simple Todoist CLI client written in Go. Use it to quickly manage your Todoist tasks and projects when working in the terminal.

It also provides a much better export feature than the standard CSV backups: The Todoister export command supports structured JSON or YAML with configurable depth for nested directories.

Todoister is still a work in progress. More features like task editing, tag management, etc. coming soon.

Installation

For Linux and macOS, use:

curl -sfL https://todoister.layfellow.net/installer.sh | sh

This script fetches the latest binary for your platform and installs it in ~/.local/bin or ~/bin.

For Windows … huh, I don’t use Windows, so there are no releases for it, but the Linux binary should work under WSL 2.

Alternatively, if you have Go (version 1.24 or later), you can download, compile and install Todoister with:

go install github.com/layfellow/todoister@latest

Configuration

You need a Todoist API token; log in to your Todoist account and create one here.

Then write a ~/.config/todoister/config.toml or ~/.todoister.toml file and set the token:

token = "your-todoist-API-token"

The full format of the configuration file is:

# You should at least set this.
token = ""

# Log file when running non-interactively.
# Default is $HOME/.cache/todoister/out.log
[log]
name = ""

# Argument and options for `todoister export`.
# Defaults are path: current directory, format: json, depth: 0
[export]
path = ""
format = ""
depth = 0

Configuration alternatives

Instead of a configuration file, you can use an environment variable for the token:

export TODOIST_TOKEN='your-todoist-API-token'

Or pass the token directly via the command line:

todoister --token='your-todoist-API-token' command ...

The --token option takes precedence over the environment variable, which in turn overrides the configuration file.

Export

You can run todoister export in a cron job as a way create automatic Todoist backups in a sane format. You can set the export options in the configuration file, so you don’t have to edit the cron tab.

[export]
path = ""
format = ""
depth = 0

For instance, instead of todoister export --yaml -d 3 ~/projects just run todoist export with:

[export]
path = "$HOME/projects"
format = "yaml"
depth = 3

When running as a cron job, todoister export logs its activity to a log file as set in:

[log]
name = "/path/to/log/file.log"

Log format

Logs follow the structured logging format and are auto-rotated. No logs are written in interactive mode.