1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
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.
.. _cli: https://en.wikipedia.org/wiki/Command-line_interface
.. _tui: https://en.wikipedia.org/wiki/Text-based_user_interface
Synchronization
---------------
If you want to synchronize your tasks, you'll need something that syncs via
CalDAV. `vdirsyncer`_ is the recommended tool for this.
.. _vdirsyncer: https://vdirsyncer.readthedocs.org/en/stable/
Interactive shell
-----------------
If you install `click-repl <https://github.com/untitaker/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`_.
.. _conky: https://conky.cc
.. _variables: https://conky.sourceforge.net/variables.html
.. _here: https://github.com/r4ulill0/todoman/blob/main/docs/examples/conky.conf
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::
todo list --sort due,-priority
|
