Man page¶
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¶
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
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.
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
Configuring¶
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 tonever
to disable colored output entirely, oralways
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
andtime_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
None, this field is mandatory.
- 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 = "~/.local/share/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.
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.