bashio

name	bashio
description	This skill should be used when the user asks to "use bashio", "read config with bashio", "log messages in an add-on", "call the Supervisor API", or mentions bashio functions, Home Assistant add-on development, or s6-overlay scripts.

Bashio for Home Assistant Add-ons

Bashio provides a function library for accessing Home Assistant Supervisor features from shell scripts within add-ons. Use bashio to read configuration, log messages, interact with services, and control the Supervisor.

Purpose

Simplify Home Assistant add-on development by providing tested, documented functions for common operations. Avoid reinventing wheels for configuration access, logging, API calls, and service discovery.

When to Use This Skill

Use this skill when:

• Creating new Home Assistant add-ons
• Adding configuration reading to scripts
• Implementing logging in add-on services
• Calling Supervisor or Home Assistant APIs
• Setting up s6-overlay service scripts
• Checking service availability (Mariana Board, MySQL, etc.)
• Debugging add-on initialization or runtime issues

Core Concepts

Script Shebang

Always use bashio's shebang to ensure the library loads:

#!/usr/bin/with-contenv bashio

This automatically sources bashio and provides access to all functions.

Log Levels

Bashio supports hierarchical log levels controlled by the log_level add-on option:

• trace - Extremely verbose, every function call
• debug - Diagnostic messages for development
• info - Normal operational messages (default)
• warning - Non-fatal issues needing attention
• error - Fatal errors, service will likely stop

Core Workflow

Step 1: Read Add-on Configuration

Access options from config.yaml using bashio::config:

# Read a string value
app_port=$(bashio::config 'port')

# Read with default value if not set
log_level=$(bashio::config 'log_level' 'info')

# Check if a boolean option is true
if bashio::config.true 'ssl'; then
    bashio::log.info "SSL is enabled"
fi

# Check if option has a value
if bashio::config.has_value 'api_key'; then
    api_key=$(bashio::config 'api_key')
fi

# Require an option or exit with error
bashio::config.require 'username'

Common config functions:

• bashio::config <key> - Get value (returns null if not set)
• bashio::config <key> <default> - Get with default
• bashio::config.true <key> - Check if boolean is true
• bashio::config.false <key> - Check if boolean is false
• bashio::config.has_value <key> - Check if has non-empty value
• bashio::config.require <key> - Require or exit fatal
• bashio::config.require.username - Require username
• bashio::config.require.password - Require password

Step 2: Log Messages

Use structured logging with proper severity levels:

# Basic logging (colors automatically applied)
bashio::log.info "Starting application..."
bashio::log.notice "Configuration loaded"
bashio::log.warning "Using default values"
bashio::log.error "Failed to connect to database"

# Debug logging (only shown when log_level is debug/trace)
bashio::log.debug "API endpoint: ${api_url}"

# Fatal error (stops service)
bashio::log.fatal "Required configuration missing!"

# Colored messages (rarely needed, levels are preferred)
bashio::log.green "Success!"
bashio::log.red "Critical error!"

Step 3: Access Supervisor API

Call Supervisor endpoints without manual authentication:

# Restart Home Assistant
bashio::core.restart

# Get Home Assistant version
ha_version=$(bashio::core.version)

# Check for updates
if bashio::core.update_available; then
    bashio::log.notice "Home Assistant update available"
fi

# Get add-on info
my_version=$(bashio::addon.version 'self')
addon_name=$(bashio::addon.name)

# Get ingress URL
ingress_url=$(bashio::addon.ingress_url)

# Check if a service is available
if bashio::services.available 'mysql'; then
    bashio::log.info "MySQL service is running"
fi

# Get service configuration
mysql_host=$(bashio::services 'mysql' 'host')
mysql_port=$(bashio::services 'mysql' 'port')

Step 4: Network Operations

Wait for services or ports to be ready:

# Wait for a TCP port (default: localhost, 60s timeout)
bashio::net.wait_for 8080

# Wait for specific host
bashio::net.wait_for db.example.com 5432 120

# Wait before starting dependent service
bashio::log.info "Waiting for database..."
bashio::net.wait_for "${db_host}" "${db_port}"

Step 5: File System Operations

Create directories with proper ownership:

# Create directory in /data (persistent)
bashio::fs.mkdir '/data/config'

# Create directory in /tmp (ephemeral)
bashio::fs.mkdir '/tmp/cache'

# Check if file exists
if bashio::fs.file_exists '/ssl/fullchain.pem'; then
    bashio::log.info "SSL certificate found"
fi

# Copy file with bashio (preserves permissions)
bashio::fs.cp '/tmp/config.yaml' '/data/config.yaml'

Step 6: JSON Parsing with jq

Parse JSON responses from APIs:

# Get add-on info as JSON
addon_info=$(bashio::api.supervisor GET '/addons/self/info' false)

# Extract specific field using bashio's jq wrapper
name=$(bashio::jq "${addon_info}" '.name')
version=$(bashio::jq "${addon_info}" '.version')

# Check if path exists in JSON
if bashio::jq.exists "${response}" '.data.config'; then
    config=$(bashio::jq "${response}" '.data.config')
fi

Common Patterns

Reading All Options at Once

Load configuration into variables:

#!/usr/bin/with-contenv bashio

# Read all configuration
server_port=$(bashio::config 'port' '8095')
ssl_enabled=$(bashio::config 'ssl' 'false')
certfile=$(bashio::config 'certfile')
log_level=$(bashio::config 'log_level' 'info')

# Use the values
bashio::log.info "Starting on port ${server_port}"
if bashio::config.true 'ssl'; then
    bashio::log.info "SSL enabled with ${certfile}"
fi

Service Discovery Pattern

Check for optional dependencies:

# MariaDB is optional
if bashio::services.available 'mariadb'; then
    db_host=$(bashio::services 'mariadb' 'host')
    db_port=$(bashio::services 'mariadb' 'port')
    db_user=$(bashio::services 'mariadb' 'username')
    db_pass=$(bashio::services 'mariadb' 'password')
    bashio::log.info "Using MariaDB service"
else
    # Use internal SQLite
    bashio::log.notice "No MariaDB service found, using SQLite"
fi

Conditional SSL Certificate Validation

Validate SSL configuration only when enabled:

if bashio::config.true 'ssl'; then
    bashio::config.require.ssl 'ssl' 'certfile' 'keyfile'
    cert_path="/ssl/$(bashio::config 'certfile')"
    key_path="/ssl/$(bashio::config 'keyfile')"
    bashio::log.info "Using SSL: ${cert_path}"
fi

Log Level Control

Set log level dynamically:

# Read log level from config or default to info
log_level=$(bashio::config 'log_level' 'info')

# Set bashio's internal log level
bashio::log.level "${log_level}"

# Now debug/trace logs only show when configured
bashio::log.debug "This only shows if log_level is debug or trace"

s6-Overlay Integration

Initialization Scripts (cont-init.d)

Create scripts in /etc/cont-init.d/ for one-time setup:

#!/usr/bin/with-contenv bashio
# /etc/cont-init.d/01-setup.sh

bashio::log.info "Setting up configuration..."

# Create directories
bashio::fs.mkdir '/data/config'
bashio::fs.mkdir '/data/cache'

# Generate config from template
# (use bashio to read options and generate file)

Service Scripts (services.d)

Create run and finish scripts for services:

#!/usr/bin/with-contenv bashio
# /etc/services.d/myapp/run

# Wait for dependencies
bashio::net.wait_for 8080

# Start the application
bashio::log.info "Starting application..."
exec /app/myapp --config /data/config.yaml

#!/usr/bin/with-contenv bashio
# /etc/services.d/myapp/finish

# Cleanup when service stops
bashio::log.info "Stopping application..."

Error Handling

Graceful Exits

Use bashio exit functions for proper error codes:

# Successful exit
bashio::exit.ok

# Exit with error message
bashio::exit.nok "Failed to start service"

# Require specific conditions
if ! bashio::fs.file_exists '/data/config.yaml'; then
    bashio::log.fatal "Configuration file not found!"
    bashio::exit.nok
fi

Config Validation

Validate required options before starting:

#!/usr/bin/with-contenv bashio

# Require authentication
bashio::config.require.username 'username'
bashio::config.require.password 'password'

# Require SSL if enabled
if bashio::config.true 'ssl'; then
    bashio::config.require.ssl
fi

bashio::log.info "Configuration validated successfully"

Additional Resources

Reference Files

For comprehensive documentation of all bashio functions:

• references/log-functions.md - Complete logging reference
• references/config-functions.md - Configuration reading patterns
• references/api-functions.md - Supervisor API calls
• references/service-discovery.md - Service integration patterns

Bashio Source Code

The complete bashio library source code is available in references/lib/ for detailed reference:

Core Libraries:

• lib/bashio - Main bashio entry point
• lib/bashio.sh - Core library loader
• lib/const.sh - Constants and definitions

Configuration & Options:

• lib/config.sh - Configuration reading functions (bashio::config.*)
• lib/options.sh - Options.json parsing

Logging:

• lib/log.sh - All logging functions (bashio::log.*)
• lib/debug.sh - Debug logging helpers
• lib/trace.sh - Trace-level logging

Add-on & Supervisor API:

• lib/addons.sh - Add-on information functions (bashio::addon.*)
• lib/core.sh - Home Assistant core functions (bashio::core.*)
• lib/supervisor.sh - Supervisor API calls
• lib/api.sh - Generic API request helpers

Services & Discovery:

• lib/services.sh - Service discovery (bashio::services.*)
• lib/discovery.sh - Service discovery helpers

Network & Hardware:

• lib/net.sh - Network utilities (bashio::net.*)
• lib/network.sh - Network interface functions
• lib/dns.sh - DNS operations
• lib/hardware.sh - Hardware information
• lib/host.sh - Host system functions

File System:

• lib/fs.sh - File system operations (bashio::fs.*)

Utilities:

• lib/jq.sh - JSON parsing with jq (bashio::jq.*)
• lib/string.sh - String manipulation
• lib/color.sh - Terminal color codes
• lib/exit.sh - Exit code helpers
• lib/var.sh - Variable operations
• lib/cache.sh - Caching functions
• lib/cli.sh - CLI argument parsing
• lib/os.sh - Operating system detection
• lib/info.sh - System information
• lib/observer.sh - Observer pattern utilities

Home Assistant Features:

• lib/audio.sh - Audio subsystem functions
• lib/multicast.sh - Multicast operations
• lib/repositories.sh - Repository management

When to consult the source:

• Need exact parameter details for a function
• Want to understand function implementation
• Debugging unexpected behavior
• Looking for additional functions not covered in this guide
• Need to see available options for complex functions

Example Files

Working examples in examples/:

• examples/read-config.sh - Configuration reading patterns
• examples/service-setup.sh - s6-overlay service script
• examples/with-ssl.sh - SSL certificate handling
• examples/service-discovery.sh - Optional dependency checks

Official Resources

• Bashio GitHub Repository - Official source and documentation
• Home Assistant Add-ons Documentation
• s6-overlay Documentation
• references/lib/ - Complete bashio source code copied from docs/bashio/lib/ for offline reference

Best Practices

DO:

• Use #!/usr/bin/with-contenv bashio shebang
• Source bashio at the start of scripts
• Use appropriate log levels (info for normal, debug for diagnostics)
• Require critical configuration with bashio::config.require
• Use bashio::net.wait_for for service dependencies
• Log all significant operations for debugging
• Use bashio's jq wrapper for JSON parsing

DON'T:

• Manually parse /data/options.json (use bashio::config)
• Directly call Supervisor API without authentication (use bashio::api.supervisor)
• Hardcode service discovery (use bashio::services.available)
• Use echo for logging (use bashio::log.info)
• Ignore return codes from bashio functions
• Skip validating SSL when enabled