Todolist

Main menu

• What is this?
• Installation
• Quick start
• Todo workflow
• Rationale

Reference

• Creating a todolist
• Adding todos
• Completing / Uncompleting todos
• Archiving / Unarchiving todos
• Listing, filtering and grouping todos
• Editing todos
• Prioritizing todos
• Expanding existing todos
• Deleting todos
• Running the web view
• .todos.json file format

News

Aug 5 2017: Todolist v0.7 released!

May 25 2017: Todolist v0.6 released!

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.

Installation

One of the following will work:

• brew install todolist will work just fine if you're using homebrew.
• Simply download + copy the todolist binary to a location in your $PATH.
• If you have Golang installed, you can also just run go install github.com/gammons/todolist.

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
all


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
all


1
[ ]
tomorrow
Talk with @bob about the +bigProject



          

You can also group by project or context.

~ todolist list by project

bigProject


1
[ ]
tomorrow
Talk with @bob about the +bigProject


devops


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
all


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.

Examples:

~ 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

Listing completed todos

todolist l completed tod - List all todos completed today

todolist l completed this week - List all todos completed this week

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

Grouping

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

You can edit a todo's subject or due date The syntax is as follows:

todolist e [id] due [due]

Editing a todo's subject

When if you do not include due [date], then just the subject will be edited.

todolist e 56 chat with +bob - rewrite the subject, leaving due date alone Editing a todo's due date

if you only pass due [date], the todo's due date will be updated, and the subject will remain the same.

• todolist e 56 due tom - re-set a todo's due date
• todolist e 56 jun 20 - re-set a todo's due date
• todolist e 56 jun 20 - re-set a todo's due date

Removing a due date

Remove a due date altogether by using due none.

• todolist e 56 due none - remove a due date

Editing a todo's subject and due date

you can also edit a todo's subject and due date all at once.

• todolist e 56 take hang-gliding lessons due tom

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 server on http://localhost:7890 with a nice web view to manage your todos.

The web view is a static site that is hosted on S3, and is built with React / Redux. It is open source.

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": [
      "toVerify"
    ],
    "contexts": [
      "scott"
    ],
    "due": "2016-05-23",
    "completed": false,
    "archived": false
  }]
          

Rationale

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.

I also wanted a todolist that is super fast and easy to grep. Such a tool did no exist, so I built this one!

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. Due dates are a critical part of my workflow, and todo.txt does not provide due dates by default. Due dates are a core part of Todolist, and are treated as such within the featureset. I believe that Todolist is much closer conceptually to how the "big" todo companies do it, e.g. Wunderlist, Todoist, etc.

Limitations

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.

Author

Todolist was created with by Grant Ammons.