Bashio helper library
Bashio is the bash function library shipped for ApexOS add-ons. It wraps the
Supervisor REST API and common shell chores (option parsing, logging,
validation, JSON handling) so add-on scripts stay small. All official add-ons
that ship shell entrypoints use it, and it is available in the ApexOS base
images (the matter_server add-on, for example, pins BASHIO_VERSION: 0.17.5
as a build argument).
Source: github.com/apexinfosysindia/bashio. The library is a set of files
under lib/, one per function family, loaded by the bashio entry script.
Usage in a script:
#!/usr/bin/env bashio
bashio::log.info "Starting up..."
if bashio::config.has_value 'password'; then
PASSWORD=$(bashio::config 'password')
fi
How it talks to the Supervisor
Bashio reads two environment variables at load time:
SUPERVISOR_API— API base URL, defaulthttp://supervisorSUPERVISOR_TOKEN— the Bearer token the Supervisor injects into every add-on container
Almost every family below is a thin wrapper around one function:
bashio::api.supervisor <method> <resource> [<raw|json>] [<jq-filter>]
Makes an authenticated call to the Supervisor API.
$1HTTP method (GET/POST)$2API resource (e.g./addons/self/info)$3for GET:trueto return the raw response instead of the parsed.data; for POST: the JSON body to send$4optional jq filter applied to the result
Errors (401/403/404/405, transport failures, result: error payloads) are
logged and reported through the return code. On success the function prints
the .data object (optionally filtered).
Functions return 0 on success and 1 on failure (__BASHIO_EXIT_OK /
__BASHIO_EXIT_NOK), so predicates compose directly with if.
Many read-side wrappers cache API responses in /tmp/.bashio (see
bashio::cache.*) — restart-relevant values are fetched
once per container run.
Add-on options: bashio::config
The family you will use most. It reads this add-on's user configuration
(fetched from /addons/self/options/config and cached).
| Function | Arguments | Behavior |
|---|---|---|
bashio::config <key> [<default>] | option key (jq path, so server.port works), optional default | Prints the value; arrays print one element per line; prints the default (or null) when unset. |
bashio::config.exists <key> | key | True if the option exists in the config. |
bashio::config.has_value <key> | key | True if set and non-empty. |
bashio::config.is_empty <key> | key | True if unset or empty. |
bashio::config.equals <key> <value> | key, value | True if the option equals the value. |
bashio::config.true <key> / bashio::config.false <key> | key | Boolean tests. |
bashio::config.require <key> [<reason>] | key, optional reason | Logs a fatal explanation and exits the add-on when the option is missing. |
bashio::config.suggest <key> [<reason>] | key, optional reason | Warns when the option is unset. |
bashio::config.suggest.true <key> [<reason>] / .suggest.false | key, reason | Warn when a boolean is not enabled / not disabled. |
bashio::config.require.username [<key>] / .suggest.username | key (default username) | Enforce or recommend a username option. |
bashio::config.require.password [<key>] / .suggest.password | key (default password) | Enforce or recommend a password option. |
bashio::config.is_safe_password <key> | key | Checks the password against the HaveIBeenPwned range API; a config option i_like_to_be_pwned: true bypasses the check with a warning. |
bashio::config.require.safe_password [<key>] / .suggest.safe_password | key (default password) | Enforce or recommend a non-leaked password. |
bashio::config.require.ssl [<ssl-key>] [<certfile-key>] [<keyfile-key>] | defaults ssl, certfile, keyfile | When SSL is enabled, verifies both file options are set and the files exist under /ssl/; exits fatally otherwise. |
Logging: bashio::log.*
bashio::log.log <level> <message> underpins level helpers
bashio::log.trace, .debug, .info, .notice, .warning, .error,
.fatal (plus bare bashio::log for default output).
bashio::log.level <level> changes verbosity at runtime.
Levels (numeric): OFF 0, FATAL 1, ERROR 2, WARNING 3, NOTICE 4,
INFO 5 (default), DEBUG 6, TRACE 7, ALL 8. Output format defaults to
[{TIMESTAMP}] {LEVEL}: {MESSAGE} with a %T timestamp, and messages are
colorized per level.
System information: bashio::info.*
bashio::info [<cache-key>] [<jq-filter>] returns the Supervisor's generic
info object; the helpers select single fields:
bashio::info.supervisor, bashio::info.apexos (Core version),
bashio::info.os, bashio::info.hostname, bashio::info.machine,
bashio::info.arch, bashio::info.channel, bashio::info.supported_arch,
bashio::info.logging, bashio::info.timezone, bashio::info.supported,
bashio::info.docker, bashio::info.operating_system, bashio::info.state.
Services and discovery
| Function | Arguments | Behavior |
|---|---|---|
bashio::services <service> [<key>] | service name (mqtt, mysql), optional field | Returns the service's connection object, or a single field from it (e.g. bashio::services mqtt "host"). Requires the matching services: declaration in config.yaml. |
bashio::services.available <service> | service | True if a provider for the service is registered. |
bashio::services.publish <service> <json> | service, JSON config | Publishes this add-on as a provider (requires provide rights). |
bashio::services.delete <service> | service | Removes the published config. |
bashio::discovery <service> <json> | service, JSON config | Announces a discovery payload to ApexOS Core. |
bashio::discovery.delete <uuid> | discovery UUID | Deletes a discovery announcement. |
Add-on management: bashio::addon.* / bashio::addons
bashio::addons [<slug>] [<cache-key>] [<jq-filter>] is the generic accessor
(no slug = list all add-ons). Nearly every attribute of an add-on has a getter
taking an optional slug that defaults to self:
- Lifecycle:
bashio::addon.start|restart|stop|install|rebuild|uninstall|update [<slug>],bashio::addons.reload,bashio::addons.installed [<slug>] - Identity/metadata:
.name,.hostname,.dns,.description,.long_description,.url,.repository,.version,.version_latest,.update_available,.state,.arch,.machine,.stage,.startup,.boot,.build,.auto_update,.detached,.available,.advanced - Options:
bashio::addon.options [<slug>](full object),bashio::addon.option <key> [<value>] [<slug>](get — or set/unset when a value is given, via the options API),bashio::addon.config(the validated config of this add-on; backsbashio::config) - Network/ports:
.network,.network_description,.port <container-port> [<slug>],.port_description,.ip_address,.webui - Privileges (mirroring
config.yaml):.host_network,.host_pid,.host_ipc,.host_dbus,.privileged,.apparmor,.devices,.udev,.uart,.usb,.gpio,.kernel_modules,.devicetree,.docker_api,.full_access,.apexos_api,.apexos_role,.apexos(minimum Core version),.apexos_core_api,.auth_api,.stdin,.protected,.rating,.video,.audio,.audio_input,.audio_output - Ingress:
.ingress,.ingress_entry,.ingress_url,.ingress_port - Docs/branding:
.icon,.logo,.has_documentation,.has_changelog,.documentation,.changelog - Runtime:
.watchdog,.logs,.stats,.cpu_percent,.memory_usage,.memory_limit,.memory_percent,.network_tx,.network_rx,.blk_read,.blk_write
Two guards for protection mode:
bashio::require.protected— exits fatally unless protection mode is onbashio::require.unprotected— exits fatally (with a "PROTECTION MODE IS ENABLED!" explanation) unless the user disabled protection mode for this add-on
Platform components
Each system component has the same shape of family — a generic accessor plus
field getters, update, logs, and stats counters
(cpu_percent, memory_usage, memory_limit, memory_percent,
network_tx, network_rx, blk_read, blk_write):
| Family | Extra functions beyond the common set |
|---|---|
bashio::supervisor.* | ping, reload, version, arch, channel, healthy, supported, timezone, country, logging, ip_address, wait_boot, debug, debug_block, addons, addons_repositories |
bashio::core.* | start, stop, restart, rebuild, check, version, arch, machine, image, custom, boot, port, ssl, watchdog — controls the ApexOS Core service |
bashio::host.* | reload, shutdown, reboot, hostname, features, operating_system, kernel, chassis, deployment, cpe, disk_free, disk_total, disk_used, logs |
bashio::os.* | update, config_sync, version, version_latest, update_available, board, boot |
bashio::network.* | reload, host_internet, supervisor_internet, interfaces, interface, name, type, enabled, connected, ipv4_method/ipv6_method, ipv4_address/ipv6_address, ipv4_nameservers/ipv6_nameservers, ipv4_gateway/ipv6_gateway |
bashio::dns.* | update, reset, restart, host, locals, servers, logs |
bashio::audio.* | update, reload, restart, host, logs |
bashio::cli.*, bashio::multicast.*, bashio::observer.* | update (+ restart/logs/host where applicable) and version/stats getters for the CLI, multicast, and observer plugins |
bashio::repositories / bashio::repository.* | Store repositories: repository.name|source|url|maintainer <slug> |
Hardware: bashio::hardware.*
bashio::hardware [<cache-key>] [<jq-filter>] returns the system hardware
object; helpers: bashio::hardware.serial, .input, .disk, .gpio,
.usb.
Utilities
| Family | Functions | Notes |
|---|---|---|
bashio::var.* | true, false, has_value, is_empty, equals <value> <equals>, json <k> <v>..., json_string | var.json builds a JSON object from key/value pairs; prefix a value with ^ to emit it as a number/boolean instead of a string. |
bashio::jq | bashio::jq <json-or-file> <filter>, plus jq.exists, jq.has_value, jq.is, jq.is_boolean, jq.is_string, jq.is_object, jq.is_number, jq.is_array | Accepts a JSON string or a path to a JSON file. |
bashio::fs.* | directory_exists, file_exists, device_exists, socket_exists | Filesystem predicates. |
bashio::string.* | lower, upper, replace | String helpers. |
bashio::cache.* | exists <key>, get <key>, set <key> <value>, flush | Backing store for API-response caching (default dir /tmp/.bashio). |
bashio::exit.* | ok, nok [<message>], die_if_false | Terminate the script with a proper exit code. |
bashio::pwned.* | is_safe_password <password>, occurances <password>, pwned | HaveIBeenPwned range-API lookups used by the password helpers. |
Debug tracing
Every function logs itself with bashio::log.trace, so setting the log level
to TRACE (bashio::log.level trace) prints each bashio call with its
arguments — handy when an add-on misbehaves on a user's device.