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:

   $ todoman --help
   Usage: todoman [OPTIONS] COMMAND [ARGS]...

   Options:
     -v, --verbosity LVL             Either CRITICAL, ERROR, WARNING, INFO or
                                     DEBUG
     --colour, --color [always|auto|never]
                                     By default todoman will disable colored
                                     output if stdout is not a TTY (value
                                     `auto`). Set to `never` to disable colored
                                     output entirely, or `always` to enable it
                                     regardless.
     --porcelain                     Use a JSON format that will remain stable
                                     regardless of configuration or version.
     -h, --humanize                  Format all dates and times in a human
                                     friendly way
     --version                       Show the version and exit.
     --help                          Show this message and exit.

   Commands:
     cancel  Cancel one or more tasks.
     copy    Copy tasks to another list.
     delete  Delete tasks.
     done    Mark one or more tasks as done.
     edit    Edit the task with id ID.
     flush   Delete done tasks.
     list    List tasks.
     move    Move tasks to another list.
     new     Create a new task with SUMMARY.
     show    Show details about a task.

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 (0%)
   2 [ ] !                              Send minipimer back for warranty replacement (0%)
   3 [X] 2015-03-29 Buy soy milk (100%)
   4 [ ] !!             Fix the iPad's screen (0%)
   5 [ ] !!             Fix the Touchad battery (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 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 "todoman edit 3", or "todoman 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 needs 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"
