Dozens of fancy point-and-click task managers promise to organize your to-do list, but so often power users find that nothing outdoes that trusty old classic: the
todo.txt file. If you’re a command line lover who skips checkboxes and drop-downs to dash off notes and tasks in a regular old text file, or you’re intrigued by the idea and wish your todo.txt chops were stronger, read on.
I’ve been a heavy
todo.txt user for years. Back in 2006, I started developing a command line interface (CLI) to my todo.txt which lets me add to and check off items without launching a full-on text editor. Three years of daily (or at least weekly) use later, version 2.0 of the script is now available. It offers basic to advanced commands for managing your
todo.txt and other text files you might use to capture information, like
maybelater.txt. Let’s take a look.
Who This Is Meant For: If you’re comfortable working in the terminal, changing permissions on a file, and working with Unix-style text commands, then the
todo.txt CLI is for you. If you don’t spend a good amount of time at the command line—either in the Terminal on your Mac, or using a Unix command line or emulator on Windows—you’re going to think this whole thing is arcane and confusing.
You’ve already got CLI religion? Good. Let’s get started on some hot
todo.txt command line action.
- Download the Todo.txt CLI 2.0 zip file and extract it. You’ll get two files. Place both
todo.cfg(the configuration file) and
todo.shin your home directory.
- Open the
todo.cfg filewith your text editor of choice. Set the TODO_DIR variable to the right path for your setup. For example, on my Windows PC, this line reads:
TODO_DIR="C:/Documents and Settings/gina/My Documents"
On my Mac, this line reads:
- Make the
todo.shfile executable by using the command:
chmod +x todo.sh
- (OPTIONAL) Alias the letter t to
todo.shto save keystrokes while you use it. In your
~/.bash_profilefile, add the line:
Now you’re ready to put this script to work!
Before we start, keep in mind that this CLI isn’t trying to reinvent the text editor. If you want to do big bulk edits to a lot of items in your
todo.txt, just open it up in your favourite text editor to do so. But for quick, one-hit access to add items, mark items as complete, or slice and dice your list by project or priority,
todo.sh is for you.
For example, to add a line to your
todo.txt file, at the command line, type:
$us t add "Pick up milk"
Add a few more items for good measure:
$us t add "Pick up the dry cleaning"
$us t add "Clean out the inbox"
Now, to see all the items on your list, use:
$us t ls
The output will look like this:
$us t ls
03 Clean out the inbox
01 Pick up milk
02 Pick up the dry cleaning
TODO: 3 tasks in C:/Documents and Settings/gina/My Documents/todo.txt.
Now, you can reference each item by its ID—which is actually the line number it lives at in the
todo.txt file. For instance, to prioritise task 1 to the highest level—priority A—use this command:
$us t pri 1 A
To mark task 2 as complete, use
todo.sh‘s do action:
$us t do 2
Since a video is worth a million words, see this in action in this screencast demonstration of a to-do list you might find for a crew member on Battlestar Galactica. (Go full-screen to see what’s being typed more clearly.)
If this video clip isn’t clear enough for you, try this alternate high-res location.
Once you’ve got the basics of working with your
todo.txt down, it’s time to dive into more advanced tricks. Here are a few more things this CLI can do.
- Replace or delete a task; append or prepend text to a line. When you want to re-word a task or add a context, project, or additional info to it, use the replace, append, and prepend actions to do so. For example, add “ready at 3PM” to your “Pick up the dry cleaning task” with this command:
$us t append 2 "ready at 3PM"
- See all the contexts and projects in your list. If you’re using the + and @ sign format to signify projects and contexts, use the listcon and listproj (or lsc and lsprj for short) commands to see a short list of all your contexts or projects in your
- Move items from your todo.txt to another text file. Say you’ve decided that the “Learn how to speak French” task is actually something you’re not quite committed to doing—yet. Use
todo.sh‘s mv command to zip that task from
todo.txtto another text file in your todo directory. For example, this command will move it into a
$us t move 10 maybelater.txt
- List the contents of another text file. Since I got so used to working with
todo.txtthis way, there’s now support for working with other text files. For example, you can list the contents of your
maybelater.txtfile using the command:
$us t listfile maybelater.txt
Likewise, you can add a line to another file using:
$us t addto ideas.txt "My bright idea"
You can also search the contents of another text file by adding a keyword after the list command, ala:
$us t lf ideas.txt apple
See all the options available to you using the
todo.sh -h command. The full usage manual is available here.
Further Info and Related Projects
todo.txt CLI has lived over at its official homepage, Todotxt.com, for years now, and although I haven’t posted an update there since 2006, an active mailing list of over 500 members is still going strong. Since this project is open source, happily several other
todo.txt projects have sprung up over the years, including Task, which offers even more features than my little script does.
If you’re a programmer who wants to add to this script or a user with questions or ideas about the
todo.txt CLI, either post them here or consider joining the mailing list for support. For a full history of t
his script’s development—including its three-year hiatus—see its full changelog.
Think using a command line interface to a text file is insane or fantastic (or both)? Tried out
todo.txt? Tell us what you think in the comments.
Gina Trapani, Lifehacker’s founding editor, is still married to her todo.txt file even after a sordid affair with Remember the Milk. Her feature Smarterware appears every Wednesday on Lifehacker.