The script feature makes it possible to post-process Bard outputs arbitrarily with script files.

Scripts are defined per output. To configure, set the script option on the relevant output, for example:

file = "songbook.html"
script = "foo"

The script name is specified without the file extension. The extension is assumed automatically based on the operating system:

OSScript nameActual filename
Linux &

The script file should be placed in the output directory, and it is also executed in the output directory (i.e., with the current directory being set to the output directory).

Note: On Linux/Unix, the script .sh file should have the executable permission bit set so the user running Bard can also run the script file.

Environment variables

The following environment variables are set by Bard when running the script:

OUTPUTFull path to the output file for which the script is executed.
OUTPUT_STEMOnly the ‘stem’ part of the output filename, i.e., the filename without the extension.
OUTPUT_DIRFull path to the output directory.
PROJECT_DIRFull path to the project directory, i.e., where the bard.toml file is located.
BARDFull path to the Bard executable that was called to build the project.

Example: All chords in the book

In this example, we’ll define a script that will export all the chords in the songbook as a JSON array. We’ll be using the jq program to do this.

First, let’s add a JSON output with a script file set:

file = "songbook.json"
script = "chords"

Then, we’ll create a file named, set the exec bit (chmod 755, and write the following contents


jq '[ .songs[].blocks[].paragraphs[][] | select(.type == "i-chord").chord ] | unique' "$OUTPUT" > "${OUTPUT_STEM}-chords.json"

After building the project, a file named songbook-chords.json should be generated in the output directory. It should contain a list similar to this: