Organise

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 ideas.txt or 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.

Quick Start Guide:

1. 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.sh in your home directory.
2. Open the todo.cfg file with 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:
   TODO_DIR="/Users/gina/Documents/todo"
3. Make the todo.sh file executable by using the command: chmod +x todo.sh
4. (OPTIONAL) Alias the letter t to todo.sh to save keystrokes while you use it. In your ~/.bash_profile file, add the line:
   alias t='~/todo.sh'

Now you’re ready to put this script to work!

Basic Usage

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.

Advanced Usage

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 todo.txt.
• 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.txt to another text file in your todo directory. For example, this command will move it into a maybelater.txt file:
  
  

  $us t move 10 maybelater.txt

• List the contents of another text file. Since I got so used to working with todo.txt this way, there’s now support for working with other text files. For example, you can list the contents of your maybelater.txt file 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

The 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.