Creating and Installing Add ons

Ali Karbassi edited this page Jul 6, 2018 · 1 revision 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:

$ _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 message:

  • 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 "$@"
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.