Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
todo.txt with a Ruby flair
branch: master

Merge branch 'feature/multifile' of git:// i…

…nto berkes-feature/multifile

latest commit cd0419b40a
Johan Sahlén authored
Failed to load latest commit information.
bin Initialize feature, Scenario create default .todotxt.cfg
lib the --files flag should be able to take a file-path.
spec Feature: List all items from multiple files
.gitignore Initialize feature, Scenario create default .todotxt.cfg
Gemfile Initial commit
MIT-LICENSE.txt Add README and MIT-LICENSE files Document the file behaviour.
Rakefile Add Rake to make sure Travis CI build runs
cucumber.yml Introduce profiles to ignore @todo
todotxt.gemspec Introduce due attribute on Todo


todo.txt with a ruby flair


Todotxt is a ruby CLI interface to work with a todo.txt file



gem install todotxt


Clone from jsahlen/todotxt and do

rake install


Todotxt relies on a configuration file (.todotxt.cfg) in your home directory, which points to the location of your todo.txt. You can run

todotxt generate_cfg

to generate this file, which will then point to ~/todo.txt.


The gem will install a command, todotxt which is used to interact with your todo.txt.

  todotxt add | a TEXT                               # Add a new Todo item
  todotxt append | app ITEM# STRING                  # Append STRING to ITEM#
  todotxt del | rm ITEM#[, ITEM#, ITEM#, ...]        # Remove ITEM#
  todotxt do ITEM#[, ITEM#, ITEM#, ...]              # Mark ITEM# as done
  todotxt dp | depri ITEM#[, ITEM#, ITEM#, ...]      # Remove priority for ITEM#
  todotxt due                                        # List due items
  todotxt edit                                       # Open todo.txt file in your default editor
  todotxt generate_config                            # Create a .todotxt.cfg file in your home folder, containing the path to todo.txt
  todotxt generate_txt                               # Create a sample todo.txt
  todotxt help [TASK]                                # Describe available tasks or one specific task
  todotxt list | ls [SEARCH]                         # List all todos, or todos matching SEARCH
  todotxt listproj | lsproj                          # List all projects
  todotxt lscon | lsc                                # List all contexts
  todotxt lsdone | lsd                               # List all done items
  todotxt move | mv ITEM#[, ITEM#, ITEM#, ...] file  # Move ITEM# to another file
  todotxt prepend | prep ITEM# STRING                # Prepend STRING to ITEM#
  todotxt pri | p ITEM# PRIORITY                     # Set priority of ITEM# to PRIORITY
  todotxt replace ITEM# TEXT                         # Completely replace ITEM# text with TEXT
  todotxt undo | u ITEM#[, ITEM#, ITEM#, ...]        # Mark ITEM# item as not done
  todotxt version                                    # Show todotxt version

Calling simply todotxt will automatically run the ls command.

You can pass the option --file= to point todotxt to another file. You can pass an alias, defined in the configuration, or the path to an arbitrary file.

With a file wishlist, in the configuration defined as "wishlist", you can run:

todotxt ls --file=wishlist

To list all items form this wishlist file. Alternatively you can run:

todotxt ls --file="~/Dropbox/todo/deferred.txt"

To list all items from the file deferred.txt, provided that file exists.

In order to list all items from all files defined in the config, use the --all flag with ls:

todotxt ls --all



Screenshot of Todotxt in a Terminal window using Solarized colors.



Please report any bugs using the GitHub Issue Tracker.

Something went wrong with that request. Please try again.