Managing to-do lists on the command line with Taskwarrior

Managing to-do lists is something of a universal necessity. While some people handle them mentally or on paper, others resort to a web-based tool or a mobile application. For those preferring the command line, the MIT-licensed Taskwarrior offers a flexible solution with a healthy community and lots of extensions.

Getting started with Taskwarrior is straightforward, but it also supports sophisticated functionality, including projects, due dates, dependencies, user-defined metadata, and hook scripts. The program's philosophy describes values such as openness, low friction, no performance penalty for unused features, extensibility, and a focus on doing one thing well. Taskwarrior does not dictate a specific methodology for users to manage their to-do list. It provides advanced functionality enabling users to integrate the program into their existing workflows. The documentation lists some workflow examples, some of them including elements from Getting Things Done and Kanban methodologies.

Taskwarrior has been in development since 2006. On March 24, the project released Taskwarrior 3.0. Most Linux distributions are still packaging an older version, but downloading and building Taskwarrior 3.0 is a simple process if a reasonably recent version of the Rust toolchain (1.70 or later) is installed. I did stumble upon a build error; however, this was a known issue that was solved by removing a line in the project's Cargo.toml file.

Simple

In its simplest form, using Taskwarrior only requires knowledge of three subcommands: "task add <description>" to add a task to the to-do list, "task <ID> done" to mark a task as done, and "task list" to get a list of all tasks. After adding a task, Taskwarrior shows its ID, which can be used to refer to the task in other commands, for instance to mark it as done.

One potential hiccup is that this ID represents the task's index in the list of all pending tasks. After marking a task as done, the IDs of all subsequent tasks decrement by one. This change, however, only takes effect after a command displaying IDs is executed. Therefore, after listing the tasks and looking up their IDs, the IDs can be safely used in commands to mark various tasks as done. But as soon as a new "task list" command is executed, the IDs will be changed to consecutive numbers again. In practice, this is a non-issue for me. As the shell history shows the previously entered Taskwarrior commands with the IDs of the tasks, I rarely need to explicitly ask for the IDs with a "task list" command.

Taskwarrior has a built-in set of sensible defaults, which can be overridden individually in a configuration file. On its first use, the "task" command creates a minimal configuration file where the user can add configuration options. The "task show" command reveals all defaults and overrides. For a complete description of all supported configuration options, the configuration file's man page can be consulted with "man taskrc". The configuration file can be manually edited, or modified using the "task config" command.

Advanced

Taskwarrior implements many commands using a flexible command-line syntax, which gives access to its advanced functionality. The general form of its syntax is:

    task [<filter>] [<command>] [<modifications> | <miscellaneous>]

A command like "task 12 done" uses 12 as a filter to exclusively mark the task with ID 12 as done. However, a filter can also be a tag like "+work" or an attribute value like "status:pending". Filters can be used to restrict the tasks in the list output. For example, "task project:Book list" shows only the tasks assigned to the project "Book".

Tags are simply single-word alphanumeric labels, and a task may have any number of them. Additionally, a task can be linked to a project, which is a way to group tasks; each task can only be linked to a single project, though each project can have multiple subprojects. Tags and projects assist in filtering tasks conveniently.

Modifications are often used with the "modify" command, which allows users to change tasks after adding them. For instance, this command adds the task with ID 12 to the project Book:

    task 12 modify project:Book

In a similar way, a due date can be assigned to a task:

    task 12 modify due:tomorrow

Furthermore, a task can have a scheduled date (representing the earliest opportunity to work on a task), a wait date (which keeps the task hidden until the specified date), and an until date (the date after which the task is automatically deleted). All these types of dates are optional.

Some commands accept neither a filter nor modifications, but do accept miscellaneous arguments. An example of this is the "show" command, which displays the values of configuration options, such as in "task show verbose".

Recurring tasks are also supported. The following command adds a new task on the first day of every month until the end of March 2026:

    task add Pay the rent due:1st recur:monthly until:2026-03-31

The recurring task does not appear in the list of tasks, however. It has a status of "recurring", so only instances of the template task are created by Taskwarrior and added to the list of tasks, not the template itself. By default, only the next occurrence of the task is added to the list, but the tool can be configured to maintain several additional instances if desired.

Taskwarrior further supports a considerable number of reports for visualizing tasks. This includes burndown charts (seen below) showing the number of pending, active, and completed tasks over time (by day, week, or month), history reports, and lists of projects and tags.

The basic task list command is also a report. Many aspects of its output are configurable. Users can override the filter (which, by default, only shows the pending tasks), the columns (which show metadata for each task), and the task order in the list. Similarly, a "task all" command shows all pending, completed, and deleted tasks.

Extending Taskwarrior

Various external projects exist that extend Taskwarrior's functionality. The Tools page on the project's web site enumerates 870 projects (410 when excluding dormant projects). For instance, taskwarrior-tui and vit implement interactive terminal user interfaces. The Bugwarrior extension can update a local Taskwarrior database from Bugzilla, GitHub, GitLab, and other bug-tracking systems.

Another noteworthy companion tool is Timewarrior, which was created by the same developers as Taskwarrior. A hook script integrates Timewarrior with Taskwarrior to track time whenever a task is active. Hence, starting a task with "task <ID> start" prompts the hook script to begin time tracking in Timewarrior until Taskwarrior stops the task after a "task <ID> stop" command. The "timew summary" command will then show a report of the tracked intervals of the day; users can bring up some charts about the tracked tasks, as well. Timewarrior shares Taskwarrior's simple approach for basic functionality coupled with flexible configurability, as can be seen in its documentation.

Upgrade issues

Taskwarrior 3.0 introduced a completely new task storage and synchronization backend written in Rust: TaskChampion. As a result, users running a 2.x version of Taskwarrior need to export their tasks from Taskwarrior 2 and, after installing Taskwarrior 3, re-import all of their tasks, as explained in the documentation about the upgrade process. After this, the old plaintext data files can be deleted, since the tasks are now stored in a SQLite file.

The upgrade caught some users by surprise, however. For instance, the Arch Linux package didn't provide a migration script nor instructions about the necessary steps. As a result, upgrading the Taskwarrior package on Arch Linux led to an empty task database.

Another breaking change concerns the synchronization functionality. Taskwarrior 2 has its own server for synchronizing to-do lists across machines, "taskd". The documentation still explains this server setup, but Taskwarrior 3 is not compatible with this implementation. For the new version, Taskwarrior developers recommend the use of a cloud-storage backend. However, according to the "task-sync" man page, Google Cloud Platform appears to be the only supported platform at the moment.

The man page offers two alternate options: storing Taskwarrior's data directory on a file sharing service such as Dropbox or Google Drive, or running a TaskChampion sync server. Unfortunately, the latter option suffers from a lack of documentation. In response to an issue about this problem, Taskwarrior developer Dustin J. Mitchell admitted: "I suspect you're not alone in wanting to deploy a self-hosted sync backend. We don't have a great answer for that right now." Thus, users relying on Taskwarrior 2's taskd should probably wait before upgrading to Taskwarrior 3. This includes users of the Flutter-based TaskWarrior Mobile for Android.

Conclusion

More than twelve years after embracing Taskwarrior 2.0 for managing my to-do list and tracking time, I'm still a happy user. My usage pattern has remained relatively unchanged since then, which is a testament to Taskwarrior's non-intrusive nature. Remembering a few commands is enough for my daily work, and its command-line nature makes it easy to integrate into other tools. For instance, I display the ID and description of the currently active task in my tmux status bar. For the rare occasions when I need advanced functionality, the man pages and documentation are excellent. For users spending a lot of time with the command line, Taskwarrior is a great solution for frictionless management of their to-do lists.