Provided by: todoman_4.1.0-1_all 
NAME
todoman - a simple, standards-based, cli todo manager
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
cancel
Cancel one or more tasks.
todoman cancel [OPTIONS] TODOS...
Arguments
TODOS Required argument(s)
copy
Copy tasks to another list.
todoman copy [OPTIONS] IDS...
Options
-l, --list <list>
The list to copy the tasks to.
Arguments
IDS Required argument(s)
delete
Delete tasks.
Permanently deletes one or more task. It is recommended that you use the cancel command if
you wish to remove this from the pending list, but keep the actual task around.
todoman delete [OPTIONS] IDS...
Options
--yes
Arguments
IDS Required argument(s)
done
Mark one or more tasks as done.
todoman done [OPTIONS] TODOS...
Arguments
TODOS Required argument(s)
edit
Edit the task with id ID.
todoman edit [OPTIONS] ID
Options
--raw Open the raw file for editing in $EDITOR. Only use this if you REALLY know what
you're doing!
-s, --start <start>
When the task starts.
-d, --due <due>
Due date of the task, in the format specified in the configuration.
--location <location>
The location where this todo takes place.
--priority <priority>
Priority for this task
-i, --interactive
Go into interactive mode before saving the task.
Arguments
ID Required argument
flush
Delete done tasks. This will also clear the cache to reset task IDs.
todoman flush [OPTIONS]
Options
--yes Confirm the action without prompting.
list
List tasks (default). Filters any completed or cancelled tasks by default.
If no arguments are provided, all lists will be displayed, and only incomplete tasks are
show. Otherwise, only todos for the specified list will be displayed.
eg: - todo list' shows all unfinished tasks from all lists. - `todo list work' shows
all unfinished tasks from the list `work.
This is the default action when running
`
todo'.
The following commands can further filter shown todos, or include those omited by default:
todoman list [OPTIONS] [LISTS]...
Options
--location <location>
Only show tasks with location containg TEXT
--category <category>
Only show tasks with category containg TEXT
--grep <grep>
Only show tasks with message containg TEXT
--sort <sort>
Sort tasks using fields like : "start", "due", "priority", "created_at",
"percent_complete" etc. For all fields please refer to: <‐
https://todoman.readthedocs.io/en/stable/usage.html>
--reverse, --no-reverse
Sort tasks in reverse order (see --sort). Defaults to true.
--due <due>
Only show tasks due in INTEGER hours
--priority <priority>
Only show tasks with priority at least as high as TEXT (low, medium or high).
--start <start>
Only shows tasks before/after given DATE
--startable
Show only todos which should can be started today (i.e.: start time is not in the
future).
-s, --status <status>
Show only todos with the provided comma-separated statuses. Valid statuses are
"NEEDS-ACTION", "CANCELLED", "COMPLETED", "IN-PROCESS" or "ANY"
Arguments
LISTS Optional argument(s)
move
Move tasks to another list.
todoman move [OPTIONS] IDS...
Options
-l, --list <list>
The list to move the tasks to.
Arguments
IDS Required argument(s)
new
Create a new task with SUMMARY.
todoman new [OPTIONS] [SUMMARY]...
Options
-l, --list <list>
List in which the task will be saved.
-r, --read-description
Read task description from stdin.
-s, --start <start>
When the task starts.
-d, --due <due>
Due date of the task, in the format specified in the configuration.
--location <location>
The location where this todo takes place.
--priority <priority>
Priority for this task
-i, --interactive
Go into interactive mode before saving the task.
Arguments
SUMMARY
Optional argument(s)
show
Show details about a task.
todoman show [OPTIONS] ID
Arguments
ID Required argument
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 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
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_DIR/todoman/config.py.
$XDG_CONFIG_DIR 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
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.
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.
AUTHOR
Hugo Osvaldo Barrera <hugo@barrera.io>, et al
COPYRIGHT
2015-2022, Hugo Osvaldo Barrera