Bashio: logging, exit, and errors

These functions write to the log of your app, stop a script, and help with error handling. The function lists on this page are generated from the docblocks in the source of Bashio. The descriptions are the ones in the source, so some still say "addon" where this site says app.

Every leveled function, like bashio::log.info, only writes when the current log level is the same as its own level, or noisier. The levels, from quiet to noisy, are off, fatal, error, warning, notice, info, debug, trace, and all. The default is info.

Bashio reads the starting level from the LOG_LEVEL environment variable, as a number from 0 (off) to 8 (all). To change it from a script, call bashio::log.level with the name of a level:

#!/command/with-contenv bashio

if bashio::config.has_value 'log_level'; then
  bashio::log.level "$(bashio::config 'log_level')"
fi

bashio::log.debug "Only shown when the log level is debug or lower"

The base image of Home Assistant Community Apps does this for you: when your app has a log_level option, a startup service of that image writes the matching number to LOG_LEVEL in the container environment. The Home Assistant base images do not, so call bashio::log.level yourself.

Log messages go to a copy of the standard output that Bashio makes when it loads. That way, a log line inside a function does not end up in the output you capture with $(...). The format is [{TIMESTAMP}] {LEVEL}: {MESSAGE}, and you change it with the LOG_FORMAT and LOG_TIMESTAMP environment variables.

Bashio turns on errexit, errtrace, nounset, and pipefail for your script. A command that fails, or a variable that is not set, stops the script. That is usually what you want in a startup script. When a failure is expected, handle it: add || true, test the command in an if, or run it with bashio::try.

Leveled log functions, colored output, and the log level. Source: lib/log.sh.

• bashio::log.reinitialize_output: Redirects the $LOG_FD fd to a changed STDOUT. If an app script changed the STDOUT (after the $LOG_FD fd was redirected to it, see above), this function redirects the $LOG_FD fd to the new STDOUT. App developers must call this function after changing the STDOUT if they want the log functions to log to the new STDOUT.
• bashio::log: Log a message to output.
  • $*: Message to display
• bashio::log.red: Log a message to output (in red).
  • $*: Message to display
• bashio::log.green: Log a message to output (in green).
  • $*: Message to display
• bashio::log.yellow: Log a message to output (in yellow).
  • $*: Message to display
• bashio::log.blue: Log a message to output (in blue).
  • $*: Message to display
• bashio::log.magenta: Log a message to output (in magenta).
  • $*: Message to display
• bashio::log.cyan: Log a message to output (in cyan).
  • $*: Message to display
• bashio::log.log: Log a message using a log level.
  • $1: Log level
  • $2: Message to display
• bashio::log.trace: Log a message @ trace level.
  • $*: Message to display
• bashio::log.debug: Log a message @ debug level.
  • $*: Message to display
• bashio::log.info: Log a message @ info level.
  • $*: Message to display
• bashio::log.notice: Log a message @ notice level.
  • $*: Message to display
• bashio::log.warning: Log a message @ warning level.
  • $*: Message to display
• bashio::log.error: Log a message @ error level.
  • $*: Message to display
• bashio::log.fatal: Log a message @ fatal level.
  • $*: Message to display
• bashio::log.level: Changes the log level of Bashio on the fly.
  • $1: Log level

Stop the script, with or without an error. bashio::exit.nok logs the message as fatal and exits with code 1. Source: lib/exit.sh.

• bashio::exit.nok: Exit the script as failed with an optional error message.
  • $*: Error message (optional)
• bashio::exit.die_if_false: Exit the script when given value is false, with an optional error message.
  • $1: Value to check if false
  • $*: Error message (optional)
• bashio::exit.die_if_true: Exit the script when given value is true, with an optional error message.
  • $1: Value to check if true
  • $*: Error message (optional)
• bashio::exit.die_if_empty: Exit the script when given value is empty, with an optional error message.
  • $1: Value to check if empty
  • $*: Error message (optional)
• bashio::exit.ok: Exit the script nicely.

Run a command in a subshell with errexit on, and check afterwards whether it failed. Source: lib/try.sh.

• bashio::try: Executes a command/function in a subshell with enabled and effective errexit option and saves its exit status. Use this function to get the exit status of a subshell for a condition (for example 'if') without disabling errexit option in it. All Bashio functions that execute changes through the API and do not return a response depend on enabled errexit option.
  • $*: Command/function and its arguments
• bashio::try.succeeded: Checks whether that last command executed by bashio::try has succeeded.
• bashio::try.failed: Checks whether that last command executed by bashio::try has failed.

The docblock of bashio::try has this example:

~ # function test { false; echo "Don't print it"; }
~ # if ! test; then echo "Print it"; fi
Don't print it
~ # bashio::try test
~ # if bashio::try.failed; then echo "Print it"; fi
Print it

Checks the current log level. Source: lib/debug.sh.

• bashio::debug: Checks if we are currently running in debug mode, based on the log module.

Checks the current log level. Source: lib/trace.sh.

• bashio::trace: Checks if we are currently running in trace mode, based on the log module.

Print the escape codes for terminal colors. The bashio::log.<color> functions use the same colors. Source: lib/color.sh.

• bashio::color.reset: Reset color output (background and foreground colors).
• bashio::color.default: Set default output color.
• bashio::color.black: Set font output color to black.
• bashio::color.red: Set font output color to red.
• bashio::color.green: Set font output color to green.
• bashio::color.yellow: Set font output color to yellow.
• bashio::color.blue: Set font output color to blue.
• bashio::color.magenta: Set font output color to magenta.
• bashio::color.cyan: Set font output color to cyan.
• bashio::color.bg.default: Set font output color background to default.
• bashio::color.bg.black: Set font output color background to black.
• bashio::color.bg.red: Set font output color background to red.
• bashio::color.bg.green: Set font output color background to green.
• bashio::color.bg.yellow: Set font output color background to yellow.
• bashio::color.bg.blue: Set font output color background to blue.
• bashio::color.bg.magenta: Set font output color background to magenta.
• bashio::color.bg.cyan: Set font output color background to cyan.
• bashio::color.bg.white: Set font output color background to white.