Adding Tools

Adding Tool Documentation to TooLoo

Adding tools to TooLoo is pretty straight-forward. You fill in a TOML1 template and then tell TooLoo to read it in.

Getting A Blank template

TooLoo will generate a blank template for you to fill in with the following command

tooloo template <command_name>

It will find the command in your PATH and attempt to store a file with the same name + .toml For example, if you have an executable at ~/bin/foo and run tooloo template foo a new file will be created at ~/bin/foo.toml

If the directory isn't writable, or TooLoo can't find the command, it will ask you for the path to another directory where it can be written.

Note that TooLoo does not care where these files live. Keeping them next to the executable, just increases the chances that people will remember to update them when the tool changes. Since TOML is very readable, having it in the same directory as the tool means that people who don't use TooLoo will still see something giving them additional information about the tool.

Another strategy is to create a "tool_docs" directory, and keeping all your TooLoo TOML files in there.

Documentation Details

The comments in the generated template should be enough to convey what your tool is for, and why someone should use it, but here are some additional notes.

Whenever there's a listing of commands, short_description will be used. Depending on your personal usage description may not be worth it. However, if you're exporting and generating a static web site from tooloo you'll definitely want to include a full description.

See for an example of how this looks in a static site.

Documenting Usage

The Usage section of each command is generated on the fly whenever possible. Some commands don't have a --help option or anything similar, in which case you'll need to fill in the fallback_usage. When doing so, be sure to not use any tab characters. They'll muck with the table that's displayed in the terminal.

If your commands usage invocation returns a non-zero exit code TooLoo will look for the word "USAGE" in the output. If it doesn't find it, it will assume that an error was encountered and state that the usage is "UNKNOWN".

Remember when creating your tools, that non-zero exit codes should only be returned when there's an error, and users requesting help or documentation shouldn't be considered an error.

Modifying The Template

The default template has lots of comments in it to get you started. After a while you may want to get rid of them, or maybe add additional fields.

You can find your customizable copy of the default template in XDG_CONFIG_HOME/tooloo/template.toml If you haven't set it explicitly, XDG_CONFIG_HOME usually defaults to ~/.config

Don't worry about accidentally messing it up. If you delete your copy, TooLoo will automatically regenerate it the next time you ask it to make a template for something.

Additional Fields

TooLoo will ignore additional fields that it's not familiar with. The only "gotcha" with adding your own, is that they may conflict with fields used in future versions of TooLoo.


TOML external link icon was chosen because it's easy to read, and a lot of developers really, really like to hate YAML external link icon . If you've got an idea for an easier ingestion format we're happy to hear about it.