Bashio: options

These functions read the options the user set on the Configuration tab of your app. 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.

A few things that are good to know, from the code:

• bashio::config does not read /data/options.json. It gets your options from the Supervisor API, at /addons/self/options/config, and caches the answer. So your script needs SUPERVISOR_TOKEN in its environment: start it with #!/command/with-contenv bashio.
• The key is a jq path, so bashio::config 'logins[0].username' works for nested options.
• An option that is not set returns the default you pass as the second argument, or the text null. A list returns one item per line. An empty string or an empty list returns nothing.
• The require functions log a fatal message and exit the script when the option has no value. The suggest functions only log a warning.
• bashio::config.is_safe_password accepts a password that shows up in Have I Been Pwned when the option i_like_to_be_pwned is true.

#!/command/with-contenv bashio

bashio::config.require 'username'
bashio::config.require.safe_password 'password'

port=$(bashio::config 'port' '8080')

if bashio::config.true 'ssl'; then
  bashio::config.require.ssl
fi

For the options themselves, how to define them and their types, see Add options.

Functions that read and check the options of your app. Source: lib/config.sh.

• bashio::config: Fetches a configuration value from the app config file.
  • $1: Key of the config option
  • $2: Default value for not set config option (optional: defaults to 'null')
• bashio::config.exists: Checks if a configuration option exists in the config file
  • $1: Key of the config option
• bashio::config.has_value: Checks if a configuration option has an actual value.
  • $1: Key of the config option
• bashio::config.is_empty: Checks if a configuration option has an empty value.
  • $1: Key of the config option
• bashio::config.equals: Checks if a configuration option equals a value.
  • $1: Key of the config option
  • $2: Checks if the configuration option matches
• bashio::config.true: Checks if a configuration option is true.
  • $1: Key of the config option
• bashio::config.false: Checks if a configuration option is false.
  • $1: Key of the config option
• bashio::config.is_safe_password: Checks if a password is safe to use, using IHaveBeenPwned.
  • $1: Key of the config option
• bashio::config.require: Require a configuration option to be set by the user.
  • $1: Key of the config option
  • $2: Additional reason why this is needed
• bashio::config.suggest: Suggest on setting a configuration option to the user.
  • $1: Key of the config option
  • $2: Additional reason why this is needed
• bashio::config.suggest.true: Suggest on enabling a configuration option to the user.
  • $1: Key of the config option
  • $2: Additional reason why this is needed
• bashio::config.suggest.false: Suggest on disabling a configuration option to the user.
  • $1: Key of the config option
  • $2: Additional reason why this is needed
• bashio::config.require.username: Require the user to configure a username.
  • $1: Key of the config option (optional: defaults to 'username')
• bashio::config.suggest.username: Suggest to the user to set a username, in case it is not.
  • $1: Key of the config option (optional: defaults to 'username')
• bashio::config.require.password: Checks if the password has been set and exits when it is not.
  • $1: Key of the config option (optional: defaults to 'password')
• bashio::config.suggest.password: Suggest to set a password if it was not set.
  • $1: Key of the config option (optional: defaults to 'password')
• bashio::config.require.safe_password: Require to set a password which is not in HaveIBeenPwned database.
  • $1: Key of the config option (optional: defaults to 'password')
• bashio::config.suggest.safe_password: Suggest to set a password which is not in HaveIBeenPwned database.
  • $1: Key of the config option (optional: defaults to 'password')
• bashio::config.require.ssl: Check if certificate files exists when SSL is enabled.
  • $1: Key of the ssl config option (optional: defaults to 'ssl')
  • $2: Key of the cert file config option (optional: defaults to 'certfile')
  • $3: Key of the cert key file config option (optional: defaults to 'keyfile')