Man page
********


todoman
=======

   todoman [OPTIONS] COMMAND [ARGS]...

-[ Options ]-

-v, --verbosity <LVL>

   Either CRITICAL, ERROR, WARNING, INFO or DEBUG

--colour, --color <colour>

   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.

   Options:
      always | auto | never

--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

-c, --config <PATH>

   The config file to use.

--version

   Show the version and exit.

-[ Environment variables ]-

TODOMAN_CONFIG

      Provide a default for "--config"

-[ 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 (default).

lists

   Returns all the lists

move

   Move tasks to another list.

new

   Create a new task with SUMMARY.

path

   Print the path to a task's file.

repl

   Start an interactive shell.

show

   Show details about a task.


Description
===========

Todoman is a simple, standards-based, cli todo (aka: task) manager.
Todos are stored into *icalendar* files, which means you can sync them
via *CalDAV* using, for example, *vdirsyncer*.


Usage
=====

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

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 "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 need something that
syncs via CalDAV. vdirsyncer is the recommended tool for this.


Interactive shell
=================

If click-repl is installed, todoman supports the "repl" command, 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.


Conky
-----

Todoman can be used with Conky  by using one of the shell execution
variables. Given the nature of pimutils utilities, there is no need to
query new information every time conky updates so "execi" will be the
best option most of the time.

Adding "${execi 30 todo}" inside the text section will display the
output of the command and update it every 30 seconds.

A working configuration can be found here.


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"

It is possible to prepend a "-" to a field to sort by that field in
ascending order (by default they are sorted in descending order).

Example:

   todoman list --sort due,-priority


Configuring
===========

You'll need to configure Todoman before the first usage, using its
simple ini-like configuration file.


Configuration File
==================

The configuration file should be placed in
"$XDG_CONFIG_HOME/todoman/config.py". "$XDG_CONFIG_HOME" defaults to
"~/.config" is most situations, so this will generally be
"~/.config/todoman/config.py".

cache_path

   The location of the cache file (an sqlite database). This file is
   used to store todo data and speed up execution/startup, and also
   contains the IDs for todos. If the value is not specified, a path
   relative to "$XDG_CACHE_HOME" will be used. "$XDG_CACHE_HOME"
   generally resolves to "~/.cache/".

      type:
         str

      default:
         ""$XDG_CACHE_HOME/todoman/cache.sqlite3""

color

   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. This can be
   overridden with the "--color" option.

      type:
         str

      default:
         ""auto""

date_format

   The date format used both for displaying dates, and parsing input
   dates. If this option is not specified the system locale's is used.

      type:
         str

      default:
         ""%x""

default_command

   When running "todo" with no commands, run this command.

      type:
         str

      default:
         ""list""

default_due

   The default difference (in hours) between new todo's due date and
   creation date. If not specified, the value is 24. If set to 0, the
   due date for new todos will not be set.

      type:
         int

      default:
         "24"

default_list

   The default list for adding a todo. If you do not specify this
   option, you must use the "--list" / "-l" option every time you add
   a todo.

      type:
         str

      default:
         "None"

default_priority

   The default priority of a task on creation. Highest priority is 1,
   lowest priority is 10, and 0 means no priority at all.

      type:
         int

      default:
         "None"

dt_separator

   The string used to separate date and time when displaying and
   parsing.

      type:
         str

      default:
         "" ""

humanize

   If set to true, datetimes will be printed in human friendly formats
   like "tomorrow", "in one hour", "3 weeks ago", etc.

   If false, datetimes will be formatted using "date_format" and
   "time_format".

      type:
         bool

      default:
         "False"

path

   A glob pattern matching the directories where your todos are
   located. This pattern will be expanded, and each matching directory
   (with any icalendar files) will be treated as a list.

      type:
         str

      default:
         ""~/calendars/""

startable

   If set to true, only show todos which are currently startable;
   these are todos which have a start date today, or some day in the
   past.  Todos with no start date are always considered current.
   Incomplete todos (eg: partially-complete) are also included.

      type:
         bool

      default:
         "False"

time_format

   The date format used both for displaying times, and parsing input
   times.

      type:
         str

      default:
         ""%X""


Sample configuration
====================

The below example should serve as a reference. It will read ics files
from any directory inside "~/.local/share/calendars/", uses the
ISO-8601 date format, and set the due date for new todos in 48hs.

   # A glob expression which matches all directories relevant.
   path = "~/my_calendars/*"
   date_format = "%Y-%m-%d"
   time_format = "%H:%M"
   default_list = "Personal"
   default_due = 48


Color and displayname
=====================

* You can set a color for each task list by creating a "color" file
  containing a color code in the hex format: "#RRGGBB".

* A file named "displayname" indicates how the task list should be
  named and is needed when there are multiple directories sharing a
  name, e.g.: when using multiple $CloudInstances. The default is the
  directory name.

See also relevant documentation for the vdir format.


Timezone
========

Todoman will use the system-wide configured timezone. If this doesn't
work for you, you _may_ override the timezone by specifying the "TZ"
environment variable.

For instruction on changing your system's timezone, consult your
distribution's documentation.


Caveats
=======

Support for the "percent-completed" attribute is incomplete. Todoman
can only mark todos as completed (100%), and will not reflect nor
allow editing for values for "percent > 0 ^ percent < 100".


Contributing
============

For information on contributing, see:
https://todoman.readthedocs.io/en/stable/contributing.html


LICENCE
=======

Todoman is licensed under the ISC licence. See LICENCE for details.
