Fork me on GitHub


A very fast, simple task manager for the command line, based upon GTD.

Download todolist v0.5.2

Major Changes:

  • Will use .todos.json in home directory if .todos.json does not exist in your current directory.

The latest version of Todolist (including building the source on your own) is on the Github project page.

Download v0.5.2


Mar 14 2017: Todolist v0.5.2 released!

Mar 7 2017: Todolist v0.5.1 released!

Aug 28th 2016: Todolist web has been updated to look + perform much nicer.

Jul 6th 2016: Todolist is now part of homebrew core! Installing todolist is as easy as running brew install todolist.

What is this?

Todolist allows you to manage your tasks in the terminal. It is simple, very fast, and stays out of the way. Todolist is based upon the Getting Things Done method, and has the concept of due dates, projects and contexts.

Todo lists are specific to the directory you are in.


brew install todolist will work just fine if you're using OSX + homebrew.

Simply download + copy the todolist binary to a location in your $PATH.

If you have Golang installed, you can also just run go get

Quick start

1: Initialize your todos repo

First, run todolist init to intialize the .todos.json repo in the directory you are in.

~ todolist init
Todo repo initialized.
2: Add a couple todos

You can add a todo by using the add or a directive:

~ todolist add Chat with @bob about +currentProject due tom
Todo added.
~ todolist a +devops update my master password due fri
Todo added.
3: List todos

This is the heart of the system. You can filter and group your todos. If the built-in filtering is not powerful enough for your tastes, you can always pipe the output to grep!

~ todolist list
1 [ ] tomorrow Talk with @bob about the +bigProject
2 [ ] Fri May 13 +devops update my master password

todolist list takes many arguments. You can filter by a due date:

~ todolist list due tom
1 [ ] tomorrow Talk with @bob about the +bigProject

You can also group by project or context.

~ todolist list by project

1 [ ] tomorrow Talk with @bob about the +bigProject
2 [ ] Fri May 13 +devops update my master password
4: Complete a todo

Completing a todo is done by using todolist complete or todolist c .

~ todolist complete 1
Todo completed.
~ todolist c 2
Todo completed.

Now, if you list your todos, you'll see that all have been completed:

~ todolist list
1 [x] tomorrow Talk with @bob about the +bigProject
2 [x] Fri May 13 +devops update my master password
5: Archive completed todos

Finally, after all the work has been done, you can archive the todos so they are cleared off the list.

You can archive each one individually by running todolist ar [id], but since we have many completed todos today, we can run todolist ac instead, which will archive all completed todos.

~ todolist ac
All completed todos archived.

And that's it! You now know 90% of what you need to in order to use Todolist.

Todo Workflow

Todos can be in one of 3 states:

  • Incomplete - Incomplete todos will show up on all filtering
  • Complete - Completed todos will still show up on all filtering.
  • Archived - Archived todos will only show up when running todolist list archived.

Typically you'll create the todo, complete it, then archive it at the end of the day.

Creating a todolist

You can initialize a todolist by running todolist init. This will create a .todos.json in the directory you are in.

The todolist in your home directory is special. todolist will use the list in your home dir if it does not see a .todos.json in the directory you are in. This allows you to manage your main todolist file even if you are in another directory.

Adding todos

Add a todo by running todolist add or todolist a, and then filling out the details of the todo.

  • +projects and @contexts can be inserted into the todolist body. Currently they can only be one word long.
  • Todolist is expecting the due date at the end.
Due date format
  • For things due today or tomorrow, you can use due today and due tomorrow. You can also use due tod or due tom.
  • For things due this week, you can use the first 3 letters of the day name. For instance, due mon or due thu. Todolist will always look forward, so if today is a Wednesday, and you specify due mon, it will be for next Monday.
  • For specific dates, you can use either due may 2 or due 2 may. The month is always lowercase and 3 letters.


~ todolist a update the staging db with @frank due tom
Todo added.
~ todolist a @pomodoro I need to think about our job tier structure due wed
Todo added.
~ todolist a meet with @jake and @adrian about the +importImprovement project due jun 23
Todo added.
~ todolist l

1 [ ] tomorrow update the staging db with @frank
2 [ ] Wed Jun 22 @pomodoro I need to think about our job tier structure
3 [ ] Thu Jun 23 meet with @jake and @adrian about the +importImprovement project

Completing and un-completing todos

todolist complete [id] or todolist c [id] - complete a todo by its id.

todolist uncomplete [id] or todolist uc [id] - un-complete a todo by its id.

Archiving and unarchiving todos

todolist archive [id] or todolist ar [id] - archive a todo by its id.

todolist unarchive [id] - unarchive a todo by its id.

Listing, filtering, and grouping todos

todolist list or todolist l - list all unarchived todos

todolist l archived - list all archived todos

Note: By default, Todolist will always filter archived todos. You can only see archived todos by running todo list archived.

Filtering by due date

todolist l agenda - List todos due today or are overdue

todolist l overdue - List all todos that are overdue

todolist l due today or todo l due tod- List all todos due today

todolist l due tomorrow or todo l due tomorrow- List all todos due tomorrow

Filtering by a day of the week

todolist l due mon - List all todos due

todolist l due this week - List all todos due this week.

Showing all todos

todolist l due tomorrow or todolist l due tomorrow- List all todos due tomorrow


Todos can be grouped by project or context.

todolist l by p- List all todos by project

todolist l by c- List all todos by context

Editing todos

Todolist currently supports editing a due date only. If you need to fully edit a todo, it is recommended to delete and re-add the todo.

todolist e [id] due [due] - edit a todo's due date.


  • todolist e 133 due tod - edit todo with id 133 and set its due date to today.
  • todolist e 56 due jun 20 - edit todo with id 56 and set its due date to June 20..

Prioritizing todos

You can add priority to a todo. Priority is either on or off. When prioritized, a todo is printed in bold.

todolist p [id] - prioritize a todo.

todolist prioritize [id] - prioritize a todo.

todolist up [id] - un-prioritize a todo.

todolist unprioritize [id] - prioritize a todo.

Expanding existing todos

Todolist supports expanding existing todos. This feature helps you add more details to replace vague todos. The syntax is

todolist ex [id] +[project]: todo1[,todo2...]

If there is a todo like this:

13 [ ] Sat Jan 28 Write the thesis

which is obviously not clear enough. One may then apply this feature:

  • todolist ex 13 +thesis: get latex template due Jan 22, meet prof. due Jan 23, organize data due Jan 24, Introduction and Abstract due Jan 27

The list would become:

14 [ ] Sun Jan 22 get latex template
15 [ ] Mon Jan 23 meet prof.
16 [ ] Tue Jan 24 organize data
17 [ ] Wed Jan 25 Introduction and Abstract

Deleting todos

todolist delete [id] or todolist d [id] will do the job.

You can delete all archived todos using todolist gc. This is handy because it will free up all of the ids that were used by the archived todos.

The web view

todolist web

This runs a simple web servier on http://localhost:7890 with a nice web view to manage your todos.

A simple demo is available here.

.todos.json file format

.todos.json stores todos in a very simple format, and is simple enough to be self-explanitory. See below for an example todo stored in .todos.json.

    "id": 110,
    "subject": "+toVerify did @scott put zuora alerting in place?",
    "projects": [
    "contexts": [
    "due": "2016-05-23",
    "completed": false,
    "archived": false


I appreciate simple tools that adhere to the Unix philosophy. Being an avid Wunderlist user, I was hoping to rewrite the 30% of Wunderlist that I actually use as a simple command-line tool.

How does this differ from todo.txt?

While todo.txt is an excellent project with a great ecosystem, it just didn't serve my needs. I really needed dates on my todos, and by default, todo.txt does not provide this. I believe that Todolist is much closer conceptually to how the "big" todo companies do it, e.g. Wunderlist, Todoist, etc.


Todolist will have a hard time adding a todo that has a keyword in it. For instance:

todolist a when is the +bigProject due?

will strip the word due off the end.


Todolist was created with by Grant Ammons.