todo.txt-cli: a shell script for a plain-text task list

What todo.txt-cli actually manages

The project is a shell script, todo.sh, that reads and writes a todo.txt file. That is the whole scope. Tasks are lines of text, and the README's own example shows the shape a task takes: todo.sh add "THING I NEED TO DO +project @context". The +project and @context tokens are part of the todo.txt format rather than a database schema, which is why the file stays readable in any editor and diffable in any version control system.

The audience is narrow and specific. If your tasks need to survive a laptop reinstall, a cloud drive is enough because the file is the state. If you want the command line to be the interface, the project gives you one. If you want a GUI, a mobile client or a server that syncs devices for you, the README does not offer those; it points at the wider community around the todo.txt format instead.

How todo.sh, todo.cfg and the completion script fit together

Three files carry the design. todo.sh is the executable that parses the action and the task number or description. todo.cfg is a configuration template with a commented-out list of options, and the README states that no configuration is required but most users tweak it, for instance by relocating the task directory with the TODO_DIR variable or changing colours and highlighting. todo_completion is a bash completion script installed alongside the command.

The Makefile shows where each piece lands. It defaults to /usr/local/bin for the executable, /usr/local/etc for the config template, and /usr/local/share/bash-completion/completions for completion. Those paths are overridable through INSTALL_DIR, CONFIG_DIR and BASH_COMPLETION, and the Makefile only consults those variables when they are defined. The version string is not hardcoded: GEN-VERSION-FILE generates a VERSION-FILE that both todo.sh and the Makefile include, so a source checkout and a packaged release can report the same version.

That architecture is the reason the project is small. There is no daemon, no index and no background process. Every command is a fresh read and write of a text file, and the only persistent configuration is whatever you put in todo.cfg.

Installing todo.txt-cli and adding a first task

On macOS the README gives a Homebrew route. The first command installs the package, and the second copies the configuration template into place without overwriting anything you already have, because of the -n flag.

brew install todo-txt

cp -n $(brew --prefix)/opt/todo-txt/todo.cfg ~/.todo.cfg

On Linux the README builds from source with the Makefile. make builds, make install places the files, and make test runs the test suite.

make
make install
make test

The Makefile accepts path overrides if the defaults do not match your system. The README shows this form while noting that overriding the legacy locations is not recommended.

make install CONFIG_DIR=/etc INSTALL_DIR=/usr/bin BASH_COMPLETION=/etc/bash_completion.d

Arch users are pointed at the AUR package todotxt. Once installed, the README's example is the first real use: add a task, with a project tag and a context tag attached to the description.

todo.sh add "THING I NEED TO DO +project @context"

The README does not print the expected output of that command. What it does say is that the full action set lives in USAGE.md, and that todo.sh help lists the locations it searches for a configuration file passed with -d CONFIG_FILE. The README recommends copying the template into one of those locations even when a global configuration already exists, so your edits survive a package upgrade.

Where the shell-script approach stops being the right tool

The README is a Unix document. macOS and Linux get explicit installation sections; Windows does not. There is a bash completion script in the repository, which ties the interactive experience to bash rather than to any shell. If your working environment is Windows without a Unix-like layer, the documented path does not exist.

There is also no sync story inside the project. The README mentions relocating the task directory onto a cloud drive as a user tweak, not as a feature. Conflict resolution when two machines edit the same file is left to whatever syncs the directory. A version control workflow has the same property: git will show you the conflict, but todo.sh will not merge it.

The third boundary is the data model. Tasks are lines, and the project does not impose priorities, due dates or recurrence beyond what the todo.txt format and the action set support. If you want a calendar view, reminders that fire on a phone, or a web interface, this is the wrong layer. The README's support section sends questions to GitHub Discussions and bug reports to GitHub Issues, which is the shape of a project maintained by its users rather than a product team.

todo.txt-cli against a task app with its own database

The obvious alternative is a task application that stores its data in its own database and ships clients for desktop and mobile. The difference is not convenience, it is ownership of the format. In an app, the database is the product and export is a feature that may or may not exist. Here the file is the product: you can open todo.txt in any editor, grep it, commit it, or move it between machines with cp.

That trade cuts both ways. You gain portability and lose the guarantees an application gives you. There is no server to resolve conflicts, no schema migration, and no support contract. The README's community links (Gitter, Reddit, GitHub Discussions) are where the format's ecosystem lives, and the project treats other clients as part of that ecosystem rather than as competitors. If you want the format without the shell script, the README does not name those clients, but it does frame the project as one implementation of a shared convention.

Maintenance, releases and the GPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-06. The release history shows v2.14.0 on 2026-09-01, v2.13.0 on 2024-12-25, and v2.12.0 on 2020-08-12. The gap between 2.12.0 and 2.13.0 was roughly four years, so the cadence is irregular and a long quiet period is not evidence that the project is dead. Judge it by the changelog rather than by the calendar.

Upgrade cost is low by construction. The installed artefacts are a script, a config template and a completion file, and the Makefile regenerates the version file at build time. The README warns that a global configuration location is not a substitute for your own copy, which is the one upgrade hazard: if you edit the template in place instead of copying it, a package upgrade can replace your settings. Copying it to one of the locations listed by todo.sh help avoids that.

The licence is GNU General Public License v3.0, per the README and the LICENSE file. That is a copyleft licence, so redistributing a modified todo.sh carries obligations. The README does not discuss commercial use, and this is not legal advice; read the licence text if you plan to ship a modified copy inside a product.

Editorial conclusion

Adopt todo.txt-cli if you already live in a terminal and want your task list as a text file you can diff, back up or sync yourself; install it with make install or brew install todo-txt and copy todo.cfg before you add anything. Skip it if you need a Windows-native client, a mobile app or a database-backed service, because the project is a shell script and the README points to the todo.txt ecosystem for those. Before committing, run todo.sh help to see the configuration file locations it lists, then check USAGE.md for the action set, since the README itself only shows add.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. todotxt/todo.txt-cli on GitHub