Usage

Todoman usage is CLI based (thought there are some TUI bits, and the intentions is to also provide a fully TUI-based interface).

First of all, the classic usage output:

$ todo --help
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/bin/todo", line 11, in <module>
    load_entry_point('todoman==3.8.0', 'console_scripts', 'todo')()
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/pkg_resources/__init__.py", line 489, in load_entry_point
    return get_distribution(dist).load_entry_point(group, name)
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2843, in load_entry_point
    return ep.load()
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2434, in load
    return self.resolve()
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/pkg_resources/__init__.py", line 2440, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/todoman-3.8.0-py3.7.egg/todoman/cli.py", line 17, in <module>
    from todoman.interactive import TodoEditor
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/todoman-3.8.0-py3.7.egg/todoman/interactive.py", line 1, in <module>
    import urwid
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/urwid-2.1.0-py3.7-linux-x86_64.egg/urwid/__init__.py", line 26, in <module>
    from urwid.widget import (FLOW, BOX, FIXED, LEFT, RIGHT, CENTER, TOP, MIDDLE,
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/urwid-2.1.0-py3.7-linux-x86_64.egg/urwid/widget.py", line 27, in <module>
    from urwid.util import (MetaSuper, decompose_tagmarkup, calc_width,
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/urwid-2.1.0-py3.7-linux-x86_64.egg/urwid/util.py", line 61, in <module>
    detected_encoding = detect_encoding()
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/site-packages/urwid-2.1.0-py3.7-linux-x86_64.egg/urwid/util.py", line 58, in detect_encoding
    locale.setlocale(locale.LC_ALL, initial)
  File "/home/docs/checkouts/readthedocs.org/user_builds/todoman/envs/v3.8.0/lib/python3.7/locale.py", line 604, in setlocale
    return _setlocale(category, locale)
locale.Error: unsupported locale setting

The default action is list, which outputs all tasks for all calendars, each with a semi-permanent unique id:

1 [ ] !!! 2015-04-30 Close bank account @work (0%)
2 [ ] !              Send minipimer back for warranty replacement @home (0%)
3 [X]     2015-03-29 Buy soy milk @home (100%)
4 [ ] !!             Fix the iPad's screen @home (0%)
5 [ ] !!             Fix the Touchpad battery @work (0%)

The columns, in order, are:

  • An id.
  • Whether the task has been completed or not.
  • An !!! indicating high priority, !! indicating medium priority, ! indicating low priority tasks.
  • The due date.
  • The task summary.
  • The list the todo is from; it will be hidden when filtering by one list, or if the database only contains a single list.
  • The completed percentage.

The id is retained by todoman until the next time you run the flush command.

To operate on a todo, the id is what’s used to reference it. For example, to edit the Buy soy milk task from the example above, the proper command is todo edit 3, or todo undo 3 to un-mark the task as done.

Editing tasks can only be done via the TUI interface for now, and cannot be done via the command line yet.

Synchronization

If you want to synchronize your tasks, you’ll need something that syncs via CalDAV. vdirsyncer is the recommended tool for this.

Interactive shell

If you install click-repl, todoman gets a new command called repl, which launches an interactive shell with tab-completion.

Integrations

When attempting to integrate todoman into other systems or parse its output, you’re advised to use the --porcelain flag, which will print all output in a pre-defined format that will remain stable regardless of user configuration or version.

The format is JSON, with a single array containing each todo as a single entry (object). Fields will always be present; if a todo does not have a value for a given field, it will be printed as null.

Fields MAY be added in future, but will never be removed.

Sorting

The tasks can be sorted with the --sort argument. Sorting may be done according to the following fields:
  • description
  • location
  • status
  • summary
  • uid
  • rrule
  • percent_complete
  • priority
  • sequence
  • categories
  • completed_at
  • created_at
  • dtstamp
  • start
  • due
  • last_modified