Home Assistant Configuration When to Use This Skill Use this skill when... Use ha-automations instead when... Editing configuration.yaml Creating automation rules Setting up integrations Writing automation triggers/actions Managing secrets.yaml Debugging automation logic Organizing with packages Working with automation blueprints Troubleshooting config errors Setting up device triggers Core Configuration Files File Purpose configuration.yaml Main configuration entry point secrets.yaml Sensitive values (passwords, API keys, tokens) automations.yaml Automation rules (usually UI-managed) scripts.yaml Reusable script sequences scenes.yaml Scene definitions customize.yaml Entity customizations packages/*.yaml Modular configuration packages Configuration Structure Basic configuration.yaml homeassistant : name : Home unit_system : metric time_zone : Europe/Helsinki currency : EUR country : FI
External files
customize : !include customize.yaml packages : !include_dir_named packages/
Core integrations
default_config :
Text-to-speech
tts : - platform : google_translate automation : !include automations.yaml script : !include scripts.yaml scene : !include scenes.yaml Secrets Management secrets.yaml:
API keys
openweathermap_api_key : "abc123def456" spotify_client_id : "your_client_id" spotify_client_secret : "your_client_secret"
Database
recorder_db_url : "postgresql://user:pass@localhost/hass"
MQTT
mqtt_username : "homeassistant" mqtt_password : "secure_password"
Network
latitude : 60.1699 longitude : 24.9384 Reference in configuration.yaml: weather : - platform : openweathermap api_key : !secret openweathermap_api_key recorder : db_url : !secret recorder_db_url Include Directives Directive Description Example !include Include single file !include automations.yaml !include_dir_list Include files as list items !include_dir_list sensors/ !include_dir_named Include files as named mappings !include_dir_named packages/ !include_dir_merge_list Merge files into single list !include_dir_merge_list automations/ !include_dir_merge_named Merge files into single mapping !include_dir_merge_named integrations/ !secret Reference from secrets.yaml !secret api_key !env_var Environment variable !env_var DB_PASSWORD Package Organization Packages allow modular configuration by domain: packages/climate.yaml: climate_package : sensor : - platform : template sensors : average_indoor_temp : friendly_name : "Average Indoor Temperature" unit_of_measurement : "°C" value_template :
- { { (states('sensor.living_room_temp') | float + states('sensor.bedroom_temp') | float) / 2 | round(1) } } automation : - alias : "Climate - AC Auto Off" trigger : - platform : numeric_state entity_id : sensor.average_indoor_temp below : 22 action : - service : climate.turn_off target : entity_id : climate.living_room_ac script : climate_cool_down : alias : "Cool Down House" sequence : - service : climate.set_temperature target : entity_id : climate.living_room_ac data : temperature : 20 hvac_mode : cool packages/presence.yaml: presence_package : input_boolean : guest_mode : name : "Guest Mode" icon : mdi : account - multiple binary_sensor : - platform : template sensors : anyone_home : friendly_name : "Anyone Home" device_class : presence value_template :
- { { is_state('person.user1' , 'home') or is_state('person.user2' , 'home') or is_state('input_boolean.guest_mode' , 'on') } } Common Integration Patterns MQTT Configuration mqtt : broker : !secret mqtt_broker port : 1883 username : !secret mqtt_username password : !secret mqtt_password discovery : true discovery_prefix : homeassistant sensor : - name : "Outdoor Temperature" state_topic : "sensors/outdoor/temperature" unit_of_measurement : "°C" device_class : temperature value_template : "{{ value_json.temperature }}" REST Sensors sensor : - platform : rest name : "GitHub Stars" resource : https : //api.github.com/repos/home - assistant/core value_template : "{{ value_json.stargazers_count }}" scan_interval : 3600 headers : Authorization : !secret github_token Template Sensors template : - sensor : - name : "Sun Elevation" unit_of_measurement : "°" state : "{{ state_attr('sun.sun', 'elevation') | round(1) }}" - name : "Daylight Hours" unit_of_measurement : "hours" state :
- { % set sunrise = as_timestamp(state_attr('sun.sun' , 'next_rising')) % } { % set sunset = as_timestamp(state_attr('sun.sun' , 'next_setting')) % } { { ((sunset - sunrise) / 3600) | round(1) } } - binary_sensor : - name : "Workday" state : "{{ now().weekday() < 5 }}" Input Helpers input_boolean : vacation_mode : name : "Vacation Mode" icon : mdi : airplane input_number : target_temperature : name : "Target Temperature" min : 16 max : 28 step : 0.5 unit_of_measurement : "°C" icon : mdi : thermometer input_select : house_mode : name : "House Mode" options : - Home - Away - Sleep - Guest icon : mdi : home input_text : notification_message : name : "Custom Notification" max : 255 input_datetime : alarm_time : name : "Alarm Time" has_date : false has_time : true Configuration Validation Check Configuration
Docker/Container
docker exec homeassistant hass --script check_config
Home Assistant OS
ha core check
Supervised
hassio homeassistant check
Python venv
hass --script check_config -c /path/to/config Common Validation Errors Error Cause Fix found undefined alias Missing !secret value Add to secrets.yaml could not determine a constructor Invalid YAML syntax Check indentation duplicate key Same key defined twice Remove duplicate Platform not found Missing integration Install via UI/HACS Recorder Configuration recorder : db_url : !secret recorder_db_url purge_keep_days : 10 commit_interval : 1 exclude : domains : - automation - updater entity_globs : - sensor.weather_* entities : - sun.sun - sensor.date include : domains : - sensor - binary_sensor - switch Logger Configuration logger : default : warning logs : homeassistant.core : info homeassistant.components.mqtt : debug custom_components.my_integration : debug
Reduce noise
homeassistant.components.websocket_api : error Lovelace Dashboard (YAML Mode)
configuration.yaml
lovelace : mode : yaml resources : - url : /hacsfiles/button - card/button - card.js type : module dashboards : lovelace-home : mode : yaml filename : dashboards/home.yaml title : Home icon : mdi : home show_in_sidebar : true Quick Reference YAML Tips Pattern Example Multi-line string value: >- or value: |- List item - item Inline list [item1, item2] Comment
comment
Anchor &anchor_name Reference anchor_name Merge <<: anchor_name Template Syntax Function Example State value states('sensor.temp') State attribute state_attr('sun.sun', 'elevation') Convert to float states('sensor.temp') | float Round value | round(1) Default value states('sensor.x') | default('unknown') Timestamp as_timestamp(now()) Time delta now() - timedelta(hours=1) Agentic Optimizations Context Command Validate config docker exec homeassistant hass --script check_config 2>&1 | head -50 Find entity usage grep -r "entity_id:" config/ --include=".yaml" Find secret refs grep -r "!secret" config/ --include=".yaml" List packages ls -la config/packages/ Check YAML syntax python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"