sachaos/todoist CLI: Local Cache, Filters, and Terminal Workflows

Why sachaos/todoist Targets Terminal-Based Todoist Users

sachaos/todoist solves the problem of managing Todoist without spending each task operation inside the Todoist web interface. It is an unofficial client written in Go and aimed at users who already operate from a terminal. The repository provides commands for listing, adding, modifying, closing, reopening, and deleting tasks. It also exposes projects, labels, completed tasks, karma, and cache synchronization.

The strongest fit is a user who wants Todoist data available to shell scripts while retaining interactive selection when needed. Repository scripts connect the client to peco or fzf, allowing tasks, projects, labels, dates, and URLs to be selected through terminal interfaces. This is a different interaction model from Todoist's web application, which the README identifies as the underlying task service but does not document as a terminal workflow.

The client is not presented as an independent task system. It stores a local cache and synchronizes that cache with todoist.com. Users still need a Todoist API token and a Todoist account. The available commands therefore act as a terminal front end rather than a replacement for Todoist's hosted data.

How Todoist Cache, Commands, and Filters Connect

The repository layout separates task operations into Go source files such as `list.go`, `add.go`, `modify.go`, `close.go`, and `sync.go`. Shared concerns are also visible: `cache.go` handles cached data, `filters.go` and `filter_eval.go` implement filtering, `format.go` controls presentation, and `filter_parser.y` defines a parser that the Makefile converts into `filter_parser.go`.

The CLI uses `github.com/urfave/cli/v2` for command handling and Viper for configuration. Its global output options include `--color`, `--csv`, `--debug`, `--namespace`, `--indent`, and `--project-namespace`. Task listing also accepts `--filter`, with syntax based on Todoist's official filter language. The documented example combines due-date and priority conditions:

todoist list --filter '(overdue | today) & p1'

This query asks the client for tasks that are overdue or due today and have priority `p1`. Because the filter evaluator is implemented locally and the parser has its own source, tests, and generated Go file, filtering is a substantial part of the client rather than a thin command wrapper.

Synchronization is part of normal operation. The README explicitly asks users to run `todoist sync` after registering a token. The Docker image goes further by defining `todoist` as an alias for `todoist sync && todoist`, so commands executed inside that container run a synchronization step first. Outside that setup, cache freshness depends on when the user or surrounding script invokes `sync`.

Installing sachaos/todoist and Registering the API Token

macOS users can install the Homebrew core formula. The README warns that its name is `todoist-cli-go`, because `todoist-cli` belongs to the separate official Doist CLI. This distinction matters for support expectations as well as package selection.

brew install todoist-cli-go

Alternatively, the repository tap provides the unofficial client under another formula:

brew install sachaos/todoist/todoist

For Nix or NixOS, the documented installation command is:

nix-env -iA nixos.todoist

Arch Linux options are documented as `todoist-bin` and `todoist-git` in AUR. Self-building is also possible. The README says Go 1.12 or later is needed for that route, although the current `go.mod` declares `go 1.25`. That discrepancy should be resolved against the local Go toolchain before relying on the source-build instructions.

The first `todoist` invocation prompts for a Todoist API token. The README directs users to Todoist's developer integrations page for that token. After registration, create the initial local cache with:

todoist sync

Configuration normally resides at `$HOME/.config/todoist/config.json`. The documented token is required; color output and two Go date formats are optional. NixOS is an exception: the README places its cache at `~/.todoist.cache.json` and its configuration at `~/.todoist.config.json`.

First Todoist Task Operations with sachaos/todoist

After synchronization, `todoist list` is the simplest real operation. It shows active tasks using the configured output settings. The completed-task commands are narrower because the README states that completed-task listing is available only to premium users.

Adding, modifying, and closing tasks are exposed through separate subcommands. The README does not provide complete argument syntax or copy-paste examples for each command. Consulting those help screens is therefore necessary before writing a non-interactive automation script.

Section management is present, but the README marks it as BETA. The `sections` command includes `list`, `add`, `delete`, `archive`, `unarchive`, `update`, `move`, and `reorder`. Tasks can also be assigned to sections through `--section-name` or `--section-id` on `add` and `modify`. Begin by inspecting the command interface:

todoist sections --help

A global output option can change presentation without changing the selected records. For example, the documented flag `--csv` requests CSV output:

todoist list --csv

The README does not document the precise CSV schema, so scripts should inspect the emitted fields before depending on column positions. It also does not document rollback behavior for destructive commands such as deleting a task or archiving a section.

Adding peco or fzf Selection to sachaos/todoist

The repository includes two shell-function files. `todoist_functions.sh` is documented as the peco-oriented integration, while `todoist_functions_fzf.sh` supports fzf. For a source checkout at the documented GOPATH location, load the peco functions from `.zshrc`:

source "$GOPATH/src/github.com/sachaos/todoist/todoist_functions.sh"

The documented peco key bindings select a task, project, or label. They can also select and close a task, choose a date, and open a selected task's URL in the browser. This creates a keyboard-driven path through common Todoist actions without requiring direct command flags for every selection step.

A Homebrew installation loads site functions from the formula prefix instead:

source $(brew --prefix)/share/zsh/site-functions/_todoist_peco

For fzf, the README gives the corresponding command:

source $(brew --prefix)/share/zsh/site-functions/_todoist_fzf

The shell integrations still depend on a working `todoist` binary, a registered token, and a usable cache. They are conveniences around command execution, not separate Todoist implementations. The README does not document Windows shell setup or a complete fish integration in the repository itself.

sachaos/todoist Constraints, API Changes, and Docker Costs

The largest constraint is Todoist's API transition. According to the README, versions before v0.23 stopped working on 2026-02-10 when Todoist shut down Sync API v9 and REST API v2. Upgrading to v0.23 or later is mandatory, after which users must run `todoist sync`. Task and project IDs also changed from numeric values to alphanumeric values. Scripts or saved workflows that assume numeric identifiers need revision.

The repository is not archived, and its last push was on 2026-07-26. Recent releases include v0.24.0 on 2026-05-02 and v0.23.0 on 2026-01-19. This supports recent development activity, but it does not remove compatibility risk from depending on a third-party client of a hosted API.

Docker offers a self-contained route. The documented sequence clones the repository, builds an image with a token argument, and starts an interactive container:

git clone https://github.com/sachaos/todoist.git
cd todoist
make docker-build token=xxxxxxxxxxxxxxxxxxxx
make docker-run

That workflow requires a Git checkout during image construction. The Dockerfile installs the Go application into the container and writes a token-bearing configuration file. Operators must therefore account for secret handling, cache persistence, and rebuilding when the client or API assumptions change. The README does not document mounting a persistent host cache into the image.

Under the MIT license, the source permits use and modification under that license's terms, but users remain responsible for observing applicable notices and conditions. This is a repository-status observation, not legal advice.

sachaos/todoist Compared with the Todoist Web Interface

The practical alternative is Todoist's web application, which the README calls the underlying web task application. The web interface presents Todoist through its hosted product, while sachaos/todoist exposes operations as CLI commands and retains a local cache. For users who need direct commands, output such as CSV, shell pipelines, or interactive selectors such as peco and fzf, the CLI offers a distinct interaction path. For users who do not need terminal access, maintaining API tokens, caches, and client upgrades adds dependencies without an equally clear benefit.

The official Doist CLI is also relevant as a package and support choice. The README identifies `Doist/todoist-cli` as a different tool and notes that the Homebrew formula names were separated. It does not document the official client's command set, cache design, or platform support, so a detailed feature comparison cannot be established from this repository alone.

Within sachaos/todoist itself, local filter evaluation and cache-backed commands are the main technical differentiators. Its limitations follow from that design. Results depend on synchronization, section behavior is BETA, and the README's help transcript still shows version `0.18.0` even though the repository lists v0.24.0 as a recent release. Users should obtain current command help rather than treating the pasted transcript as the definitive interface for that release.

Editorial conclusion

Adopt sachaos/todoist if terminal-based task management, local cache synchronization, and interactive peco or fzf selection fit your workflow. Do not choose it if you require a formally supported client or stable section management. Verify first that Todoist accepts v0.24.0 for your account, then test `todoist sync`, alphanumeric task and project IDs, and the exact workflows you expect to automate.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sachaos/todoist on GitHub