.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "TODO" "1" "Apr 11, 2024" "4.4.0" "Todoman" .SH NAME todo \- a simple, standards-based, cli todo manager .SH TODO .INDENT 0.0 .INDENT 3.5 .sp .EX todo [OPTIONS] COMMAND [ARGS]... .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-v, \-\-verbosity Either CRITICAL, ERROR, WARNING, INFO or DEBUG .UNINDENT .INDENT 0.0 .TP .B \-\-colour, \-\-color By default todoman will disable colored output if stdout is not a TTY (value \fIauto\fP). Set to \fInever\fP to disable colored output entirely, or \fIalways\fP to enable it regardless. .INDENT 7.0 .TP .B Options always | auto | never .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-porcelain Use a JSON format that will remain stable regardless of configuration or version. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-humanize Format all dates and times in a human friendly way .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-config The config file to use. .UNINDENT .INDENT 0.0 .TP .B \-\-version Show the version and exit. .UNINDENT .sp Environment variables .INDENT 0.0 .TP .B TODOMAN_CONFIG .INDENT 7.0 .INDENT 3.5 Provide a default for \fI\%\-\-config\fP .UNINDENT .UNINDENT .UNINDENT .SS cancel .sp Cancel one or more tasks. .INDENT 0.0 .INDENT 3.5 .sp .EX todo cancel [OPTIONS] TODOS... .EE .UNINDENT .UNINDENT .sp Arguments .INDENT 0.0 .TP .B TODOS Required argument(s) .UNINDENT .SS copy .sp Copy tasks to another list. .INDENT 0.0 .INDENT 3.5 .sp .EX todo copy [OPTIONS] IDS... .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-l, \-\-list The list to copy the tasks to. .UNINDENT .sp Arguments .INDENT 0.0 .TP .B IDS Required argument(s) .UNINDENT .SS delete .sp Delete tasks. .sp Permanently deletes one or more task. It is recommended that you use the \fIcancel\fP command if you wish to remove this from the pending list, but keep the actual task around. .INDENT 0.0 .INDENT 3.5 .sp .EX todo delete [OPTIONS] IDS... .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-\-yes .UNINDENT .sp Arguments .INDENT 0.0 .TP .B IDS Required argument(s) .UNINDENT .SS done .sp Mark one or more tasks as done. .INDENT 0.0 .INDENT 3.5 .sp .EX todo done [OPTIONS] TODOS... .EE .UNINDENT .UNINDENT .sp Arguments .INDENT 0.0 .TP .B TODOS Required argument(s) .UNINDENT .SS edit .sp Edit the task with id ID. .INDENT 0.0 .INDENT 3.5 .sp .EX todo edit [OPTIONS] ID .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-\-raw Open the raw file for editing in $EDITOR. Only use this if you REALLY know what you\(aqre doing! .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-start When the task starts. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-due Due date of the task, in the format specified in the configuration. .UNINDENT .INDENT 0.0 .TP .B \-\-location The location where this todo takes place. .UNINDENT .INDENT 0.0 .TP .B \-\-priority Priority for this task .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-category Task categories. Can be used multiple times. .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-interactive Go into interactive mode before saving the task. .UNINDENT .sp Arguments .INDENT 0.0 .TP .B ID Required argument .UNINDENT .SS flush .sp Delete done tasks. This will also clear the cache to reset task IDs. .INDENT 0.0 .INDENT 3.5 .sp .EX todo flush [OPTIONS] .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-\-yes Confirm the action without prompting. .UNINDENT .SS list .sp List tasks (default). Filters any completed or cancelled tasks by default. .sp 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. .INDENT 0.0 .TP .B eg:  \- \fItodo list\(aq shows all unfinished tasks from all lists. \- \(gatodo list work\(aq shows all unfinished tasks from the list \(gawork\fP\&. .UNINDENT .sp This is the default action when running .nf \(ga .fi todo\(aq. .sp The following commands can further filter shown todos, or include those omited by default: .INDENT 0.0 .INDENT 3.5 .sp .EX todo list [OPTIONS] [LISTS]... .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-\-location Only show tasks with location containg TEXT .UNINDENT .INDENT 0.0 .TP .B \-\-grep Only show tasks with message containg TEXT .UNINDENT .INDENT 0.0 .TP .B \-\-sort Sort tasks using fields like : \(dqstart\(dq, \(dqdue\(dq, \(dqpriority\(dq, \(dqcreated_at\(dq, \(dqpercent_complete\(dq etc. For all fields please refer to: <\fI\%https://todoman.readthedocs.io/en/stable/usage.html\fP> .UNINDENT .INDENT 0.0 .TP .B \-\-reverse, \-\-no\-reverse Sort tasks in reverse order (see \-\-sort). Defaults to true. .UNINDENT .INDENT 0.0 .TP .B \-\-due Only show tasks due in INTEGER hours .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-category Only show tasks with specified categories. .UNINDENT .INDENT 0.0 .TP .B \-\-priority Only show tasks with priority at least as high as TEXT (low, medium or high). .UNINDENT .INDENT 0.0 .TP .B \-\-start Only shows tasks before/after given DATE .UNINDENT .INDENT 0.0 .TP .B \-\-startable Show only todos which should can be started today (i.e.: start time is not in the future). .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-status Show only todos with the provided comma\-separated statuses. Valid statuses are \(dqNEEDS\-ACTION\(dq, \(dqCANCELLED\(dq, \(dqCOMPLETED\(dq, \(dqIN\-PROCESS\(dq or \(dqANY\(dq .UNINDENT .sp Arguments .INDENT 0.0 .TP .B LISTS Optional argument(s) .UNINDENT .SS move .sp Move tasks to another list. .INDENT 0.0 .INDENT 3.5 .sp .EX todo move [OPTIONS] IDS... .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-l, \-\-list The list to move the tasks to. .UNINDENT .sp Arguments .INDENT 0.0 .TP .B IDS Required argument(s) .UNINDENT .SS new .sp Create a new task with SUMMARY. .INDENT 0.0 .INDENT 3.5 .sp .EX todo new [OPTIONS] [SUMMARY]... .EE .UNINDENT .UNINDENT .sp Options .INDENT 0.0 .TP .B \-l, \-\-list List in which the task will be saved. .UNINDENT .INDENT 0.0 .TP .B \-r, \-\-read\-description Read task description from stdin. .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-start When the task starts. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-due Due date of the task, in the format specified in the configuration. .UNINDENT .INDENT 0.0 .TP .B \-\-location The location where this todo takes place. .UNINDENT .INDENT 0.0 .TP .B \-\-priority Priority for this task .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-category Task categories. Can be used multiple times. .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-interactive Go into interactive mode before saving the task. .UNINDENT .sp Arguments .INDENT 0.0 .TP .B SUMMARY Optional argument(s) .UNINDENT .SS show .sp Show details about a task. .INDENT 0.0 .INDENT 3.5 .sp .EX todo show [OPTIONS] ID .EE .UNINDENT .UNINDENT .sp Arguments .INDENT 0.0 .TP .B ID Required argument .UNINDENT .SH DESCRIPTION .sp Todoman is a simple, standards\-based, cli todo (aka: task) manager. Todos are stored into \fIicalendar\fP files, which means you can sync them via \fICalDAV\fP using, for example, \fIvdirsyncer\fP\&. .SH USAGE .sp Todoman usage is \fI\%CLI\fP based (thought there are some TUI bits, and the intentions is to also provide a fully \fI\%TUI\fP\-based interface). .sp The default action is \fBlist\fP, which outputs all tasks for all calendars, each with a semi\-permanent unique id: .INDENT 0.0 .INDENT 3.5 .sp .EX 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\(aqs screen @home (0%) 5 [ ] !! Fix the Touchpad battery @work (0%) .EE .UNINDENT .UNINDENT .sp The columns, in order, are: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 An id. .IP \(bu 2 Whether the task has been completed or not. .IP \(bu 2 An \fB!!!\fP indicating high priority, \fB!!\fP indicating medium priority, \fB!\fP indicating low priority tasks. .IP \(bu 2 The due date. .IP \(bu 2 The task summary. .IP \(bu 2 The list the todo is from; it will be hidden when filtering by one list, or if the database only contains a single list. .IP \(bu 2 The completed percentage. .UNINDENT .UNINDENT .UNINDENT .sp The id is retained by \fBtodoman\fP until the next time you run the \fBflush\fP command. .sp To operate on a todo, the id is what\(aqs used to reference it. For example, to edit the \fIBuy soy milk\fP task from the example above, the proper command is \fBtodo edit 3\fP, or \fBtodo undo 3\fP to un\-mark the task as done. .sp Editing tasks can only be done via the TUI interface for now, and cannot be done via the command line yet. .SH SYNCHRONIZATION .sp If you want to synchronize your tasks, you\(aqll need something that syncs via CalDAV. \fI\%vdirsyncer\fP is the recommended tool for this. .SH INTERACTIVE SHELL .sp If you install \fI\%click\-repl\fP, todoman gets a new command called \fBrepl\fP, which launches an interactive shell with tab\-completion. .SH INTEGRATIONS .sp When attempting to integrate \fBtodoman\fP into other systems or parse its output, you\(aqre advised to use the \fB\-\-porcelain\fP flag, which will print all output in a pre\-defined format that will remain stable regardless of user configuration or version. .sp 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 \fBnull\fP\&. .sp Fields MAY be added in future, but will never be removed. .SS Conky .sp Todoman can be used with \fI\%Conky\fP by using one of the shell execution \fI\%variables\fP\&. Given the nature of pimutils utilities, there is no need to query new information every time conky updates so \fBexeci\fP will be the best option most of the time. .sp Adding \fB${execi 30 todo}\fP inside the text section will display the output of the command and update it every 30 seconds. .sp A working configuration can be found \fI\%here\fP\&. .SH SORTING .sp The tasks can be sorted with the \fB\-\-sort\fP argument. Sorting may be done according to the following fields: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBdescription\fP .IP \(bu 2 \fBlocation\fP .IP \(bu 2 \fBstatus\fP .IP \(bu 2 \fBsummary\fP .IP \(bu 2 \fBuid\fP .IP \(bu 2 \fBrrule\fP .IP \(bu 2 \fBpercent_complete\fP .IP \(bu 2 \fBpriority\fP .IP \(bu 2 \fBsequence\fP .IP \(bu 2 \fBcategories\fP .IP \(bu 2 \fBcompleted_at\fP .IP \(bu 2 \fBcreated_at\fP .IP \(bu 2 \fBdtstamp\fP .IP \(bu 2 \fBstart\fP .IP \(bu 2 \fBdue\fP .IP \(bu 2 \fBlast_modified\fP .UNINDENT .UNINDENT .UNINDENT .sp It is possible to prepend a \fB\-\fP to a field to sort by that field in ascending order (by default they are sorted in descending order). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .EX todo list \-\-sort due,\-priority .EE .UNINDENT .UNINDENT .SH CONFIGURING .sp You\(aqll need to configure Todoman before the first usage, using its simple ini\-like configuration file. .SH CONFIGURATION FILE .sp The configuration file should be placed in \fB$XDG_CONFIG_HOME/todoman/config.py\fP\&. \fB$XDG_CONFIG_HOME\fP defaults to \fB~/.config\fP is most situations, so this will generally be \fB~/.config/todoman/config.py\fP\&. .INDENT 0.0 .TP .B 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 \fB$XDG_CACHE_HOME\fP will be used. \fB$XDG_CACHE_HOME\fP generally resolves to \fB~/.cache/\fP\&. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fB\(dq$XDG_CACHE_HOME/todoman/cache.sqlite3\(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B color By default todoman will disable colored output if stdout is not a TTY (value \fBauto\fP). Set to \fBnever\fP to disable colored output entirely, or \fBalways\fP to enable it regardless. This can be overridden with the \fB\-\-color\fP option. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fB\(dqauto\(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B date_format The date format used both for displaying dates, and parsing input dates. If this option is not specified the system locale\(aqs is used. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fB\(dq%x\(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B default_command When running \fBtodo\fP with no commands, run this command. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fB\(dqlist\(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B default_due The default difference (in hours) between new todo\(aqs 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. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type int .TP .B default \fB24\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B default_list The default list for adding a todo. If you do not specify this option, you must use the \fB\-\-list\fP / \fB\-l\fP option every time you add a todo. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fBNone\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type int .TP .B default \fBNone\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B dt_separator The string used to separate date and time when displaying and parsing. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fB\(dq \(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B humanize If set to true, datetimes will be printed in human friendly formats like \(dqtomorrow\(dq, \(dqin one hour\(dq, \(dq3 weeks ago\(dq, etc. .sp If false, datetimes will be formatted using \fBdate_format\fP and \fBtime_format\fP\&. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type bool .TP .B default \fBFalse\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default None, this field is mandatory. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B 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. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type bool .TP .B default \fBFalse\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B time_format The date format used both for displaying times, and parsing input times. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B type str .TP .B default \fB\(dq%X\(dq\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SH SAMPLE CONFIGURATION .sp The below example should serve as a reference. It will read ics files from any directory inside \fB~/.local/share/calendars/\fP, uses the ISO\-8601 date format, and set the due date for new todos in 48hs. .INDENT 0.0 .INDENT 3.5 .sp .EX # A glob expression which matches all directories relevant. path = \(dq~/.local/share/calendars/*\(dq date_format = \(dq%Y\-%m\-%d\(dq time_format = \(dq%H:%M\(dq default_list = \(dqPersonal\(dq default_due = 48 .EE .UNINDENT .UNINDENT .SH COLOR AND DISPLAYNAME .INDENT 0.0 .IP \(bu 2 You can set a color for each task list by creating a \fBcolor\fP file containing a color code in the hex format: \fB#RRGGBB\fP\&. .IP \(bu 2 A file named \fBdisplayname\fP 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. .UNINDENT .sp See also \fI\%relevant documentation for the vdir format\fP\&. .SH TIMEZONE .sp Todoman will use the system\-wide configured timezone. If this doesn\(aqt work for you, you _may_ override the timezone by specifying the \fBTZ\fP environment variable. .sp For instruction on changing your system\(aqs timezone, consult your distribution\(aqs documentation. .SH CAVEATS .sp Support for the \fBpercent\-completed\fP attribute is incomplete. Todoman can only mark todos as completed (100%), and will not reflect nor allow editing for values for \fBpercent > 0 ^ percent < 100\fP\&. .SH CONTRIBUTING .sp For information on contributing, see: \fI\%https://todoman.readthedocs.io/en/stable/contributing.html\fP .SH LICENCE .sp Todoman is licensed under the ISC licence. See LICENCE for details. .SH AUTHOR Hugo Osvaldo Barrera , et al .SH COPYRIGHT 2015-2024, Hugo Osvaldo Barrera .\" Generated by docutils manpage writer. .