TODO(1)

okay bestie, you've landed on TODO(1) — the official man page for Todoman 💅✨ (yes the manual name is Todoman, the command name is todo, don't overthink it). grab a matcha, we're getting you fluent in this 🍓

🌸 NAME 🌸

todo — a simple, standards-based, cli todo manager 🎀

🫶 TODO 🫶

(existential naming aside, this is the synopsis — how you actually call the thing)

   todo [OPTIONS] COMMAND [ARGS]...

✨ Options ✨

• -v, --verbosity <LVL> — how chatty it gets. One of CRITICAL, ERROR, WARNING, INFO or DEBUG.
• --colour, --color <colour> — colour control, no cap. By default todoman disables colored output when stdout is not a TTY (that value is auto). Set it to never to turn coloured output off completely, or always to force it on regardless.

Valid options: always | auto | never

• --porcelain — spits out JSON in a format that stays stable no matter your configuration or version. this is the one for scripts 🫶
• -h, --humanize — formats all dates and times in a human friendly way (like, "tomorrow" energy, not timestamp energy).
• -c, --config <PATH> — which config file to use.
• --version — shows the version and exits. iconic.

🔑 Environment variables 🔑

• TODOMAN_CONFIG — provides 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, periodt. Todos live inside icalendar files, which means you can sync them over CalDAV using — for example — vdirsyncer. literally the whole vibe ✨

🦋 USAGE 🦋

Todoman is CLI based (thought there are some TUI bits, and the intentions is to also provide a fully TUI-based interface — yes, that's what the page says, we're keeping it, don't come for me 🙈).

The default action is list, which outputs all tasks for all calendars, each one 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. (so like, don't panic when your IDs shuffle after a flush, that's just how it is 🫠)

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. (yes, we're all waiting, bestie 😭)

🌈 SYNCHRONIZATION 🌈

If you want to synchronize your tasks, you'll need something that syncs via CalDAV. vdirsyncer is the recommended tool for this. trust 🔥

💜 INTERACTIVE SHELL 💜

If click-repl is installed, todoman supports the repl command, which launches an interactive shell with tab-completion. tab-completion is self care, ngl.

⭐ 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. (so your parser is safe, bestie 💖)

🧚 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). yes, that's backwards from what you'd expect, but that's the documented behaviour, so that's what you get 💀

Example:

  todo list --sort due,-priority

🎀 CONFIGURING 🎀

You'll need to configure Todoman before the first usage, using its simple ini-like configuration file. it's giving "one time setup, forever slay".

🌸 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. (yes the page really says "is most situations", we're preserving the lore 🙈)

• 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. so like, partial progress? not happening yet, sorry bestie 😭

💅 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@whynothugo.nl>, et al

⭐ COPYRIGHT ⭐

2015-2023, Hugo Osvaldo Barrera

---

and that's the whole page, bestie 🎀 this was 4.7.0, dated Apr 20, 2026 — now go forth and manage those todos, main character energy only 👑💖