Make Colourful ASCII Banners with TOIlet

TOIlet turns a short message into a huge block-letter banner in your terminal, with colour filters, fonts and export formats that FIGlet never had. This guide renders a plain banner, adds colour, picks a font, controls width, reads from a pipe, and saves output safely to a file. About ten minutes for a first run, no elevated privileges needed.

Uses TOIlet 0.3, installed from package toilet. TOIlet is often confused with FIGlet because the commands look similar; the installed manpage describes it 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 actually run is toilet.

1. Check the installed command

Start with a read-only version check, confirming 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 alongside any script or output that needs exact reproduction.

2. Render a plain banner

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

toilet 'Hello, Linux'

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

For a quick script check, discard the visual output and look at the status directly:

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

Expected output is exit status: 0. That confirms 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. Redirect it to a file and those control characters get stored too, useful for replaying the banner in a compatible terminal, confusing if 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 chain with colons, for example -F crop:border, and several -F options apply 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, then in the current directory. Select one by name:

toilet --font term 'small fallback'

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

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

That example does not change the system directory, only where this one invocation looks. To discover installed font filenames without modifying anything:

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 match the terminal:

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

5. Read from a pipe

With no message argument, TOIlet reads standard input, handy 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. Something that produces text continuously, such as a log stream, can keep TOIlet running indefinitely; the manual's own example uses tail -f. Stop that interactive pipeline with Ctrl-C, which ends the pipeline without touching the source log.

6. Export or save the result safely

TOIlet can export formats libcaca recognises. Check what this installation supports 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 only. 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

New command fails? Restore the backup with cp -- status-banner.html.bak status-banner.html. Only remove the backup 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 check 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 separate.

Colour appearing as visible escape characters means the destination is displaying terminal-oriented output as plain text. Use --export html for an HTML file, or drop the colour filter when you need ordinary text. Banner wrapping unexpectedly? Set --width explicitly rather than trusting the default 80 columns.

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