Make Colourful ASCII Banners with TOIlet

You will turn a short message into a large terminal banner, add a colour filter, choose a font, and redirect the result safely when you need a file. The examples use TOIlet 0.3, installed from package toilet on this machine. Allow about ten minutes for a first run. You need a shell and the package installed; the normal commands require no elevated privileges.

TOIlet is sometimes confused with FIGlet because it accepts a similar style of command. Its installed manpage describes TOIlet as a separate program with Unicode handling, colour fonts, filters and export formats. The alias figlet-toilet points at the same manual entry here, but the executable to run is toilet.

1. Check the installed command

Start with a read-only version check. This confirms which implementation your shell will run:

command -v toilet
toilet --version
dpkg-query -W -f='${Package} ${Version}\n' toilet

On the reference system, the program reports TOIlet version 0.3 and the Debian package reports toilet 0.3-1.4build1. Package revisions differ between distributions, so keep the version beside any script or output that needs to be reproduced exactly.

2. Render a plain banner

Pass the message as the remaining command-line arguments. TOIlet combines those words into the text it renders:

toilet 'Hello, Linux'

The command prints several rows of large characters to standard output. The exact glyphs depend on the selected font and terminal, but the output should contain a recognisable block-letter banner and end with a zero exit status.

For a quick script check, discard the visual output and inspect the status immediately:

toilet 'build ok' > /dev/null
printf 'exit status: %s\n' "$?"

Expected output is exit status: 0. This checks that TOIlet rendered the message, not that a human would find the chosen font attractive.

3. Make the output colourful

Use the guaranteed --gay shortcut for a rainbow filter, or spell the equivalent filter explicitly:

toilet --gay 'Release 1.0'
toilet -F gay 'Release 1.0'

In an interactive terminal, the output contains ANSI colour escape codes. If you redirect it to a file, those control characters are stored in the file too. That is useful for replaying the banner in a compatible terminal, but confusing when you expected plain text.

List the filters available in this installation before building a less familiar command:

toilet -F list

The reference installation lists crop, gay, metal, flip, flop, rotation filters, left, right and border. Filters can be chained with colons, for example -F crop:border. Several -F options are applied in the order given.

4. Select a font and control width

Fonts are .flf or .tlf files. TOIlet normally looks in the build-time font directory, usually /usr/share/figlet, and then in the current directory. Select one by name:

toilet --font term 'small fallback'

term is a built-in fallback font, so it is a useful diagnostic when a named font cannot be found. To use fonts stored elsewhere, provide the directory explicitly and then the font name:

toilet --directory /usr/share/figlet --font term 'known font'

That example does not change the system directory. It only changes where this invocation looks. If you need to discover installed font filenames, inspect the directory without modifying it:

find /usr/share/figlet -maxdepth 1 -type f \( -name '*.flf' -o -name '*.tlf' \) -printf '%f\n' | sort | head

TOIlet wraps output at 80 columns by default. Set a deliberate width for a narrow terminal or a fixed-width log, or ask it to use the terminal width:

toilet --width 60 'narrow banner'
toilet --termwidth 'fit this terminal'

5. Read from a pipe

With no message argument, TOIlet reads standard input. This makes it useful at the end of a small pipeline:

printf '%s\n' 'Nightly build' | toilet --font term

Keep the input bounded when it comes from another command. A command that continuously produces text, such as a log stream, can keep TOIlet running indefinitely. The manual's example uses tail -f; stop that interactive pipeline with Ctrl-C. Stopping it ends the pipeline and does not alter the source log.

6. Export or save the result safely

TOIlet can export formats recognised by libcaca. Inspect the formats on the installed system first:

toilet -E list

The reference output includes UTF-8 with ANSI codes, HTML, IRC colour codes, PostScript, SVG, TGA and troff. For a browser-oriented export, use the documented shortcut:

toilet --html 'Status banner' > status-banner.html

--html selects HTML output. It does not publish the file, open a browser or create a directory. Check the result before sharing it:

test -s status-banner.html
head -n 5 status-banner.html

cp -- status-banner.html status-banner.html.bak
toilet --html 'Updated banner' > status-banner.html

If the new command fails, restore the backup with cp -- status-banner.html.bak status-banner.html. Remove the backup only after checking the replacement; deleting it is irreversible.

7. Diagnose the common failures

An unknown font usually means the name is not a file in the selected font directory. Retry with the built-in term font, then inspect the directory and choose an exact filename. Do not add a path to --font while also assuming --directory will be ignored; keep the two roles clear.

If colour appears as visible escape characters, the destination is displaying terminal-oriented output as plain text. Use --export html for an HTML file, or omit the colour filter when you need ordinary text. If the banner wraps unexpectedly, set --width explicitly rather than relying on the default 80 columns.

TOIlet's -s default uses the font's smushing information where available, while -S, -k, -W and -o select other character-composition rules. These affect spacing and joins, not the message. Try them on a short sample before putting one into a generated file.