Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Creating and Installing Add ons

inkarkat edited this page · 7 revisions add-ons let you add new actions or change (override) default actions. Visit the Add-on Directory to find browse available add-ons.

Installing Add-ons

Add-ons can be installed into the $HOME/.todo.actions.d directory, or any other directory configured via $TODO_ACTIONS_DIR. Create this directory with the following bash shell commands:

mkdir -p ~/.todo.actions.d

You must name add-ons after the action you want to add or override. For
example, create a new “review” action by installing an add-on to
.todo.actions.d/review. After installing the add-on, you must make it
executable; for example:

chmod +x ~/.todo.actions.d/review

Use the new or overridden action the normal way. For example: review

You can force to use a default action instead of an
overridden action by prefixing the action’s name with the word,
“command”. For example: command ls

Creating Add-ons

Add-ons may be written in any programming language your operating system
supports. The first command-line argument to the add-on will be the
action called or the word “usage”; the remaining arguments, if any, will
be those provided by the user. For example:

harding@ziggy:~$ _dummy_action foo bar
First argument: _dummy_action
Remaining arguments:
	* foo
	* bar

If the first argument is usage, you should provide a short usage
message that will be displayed when the user calls “ -h”. will also provide your script with several environmental
variables including the following documented in’s usage message:


and the following environmental variables not documented in the usage

  • TODO_SH — name of the script, use in the usage message
  • TODO_FULL_SH — complete path to calling script, use for invoking
  • TODOTXT_CFG_FILE — complete path to user’s configuration file
  • TODO_DIR — complete path to the todo.txt file

Creating Add-ons: Examples

Aliasing Add-ons

You may want to allow short aliases for those new commands (e.g. “pv” as alias for “projectview”)

There is a small issue if you simply duplicate or symlink the add-on file: the corresponding help snippet will be duplicated as well in the output of the help command. To avoid that, you can create aliases by creating short add-ons such as this example (replace projectview by the command you want to call with your alias):

[ "$1" = "usage" ] && exit 0
"$TODO_FULL_SH" projectview "$@"
Something went wrong with that request. Please try again.