The script editor allows you to write your own automations to create advanced Household Routines with Google Home for web or in the Google Home app. To write scripted automations, you need to know a few basics about the YAML scripting language, how to structure your script, and how to use the components that make up your script.
The script editor is currently available in Public Preview. You can access the script editor with Google Home for web or in the mobile Google Home app after you've joined Public Preview.
Learn more about creating automations with the script editor:- Create advanced smart home automations with the script editor
- Supported starters, conditions, and actions
- Visit our codelab for a guided example of creating your first script
- Practice for writing a scripted automation and example scripts
YAML scripting language basics
The script editor uses YAML, a flexible scripting language that allows you to enter line-by-line instructions for things you want your devices to do and when you want them to occur. These instructions are written in the form of key-value pairs.
Key-value pairs
YAML is written as a series of key-value pairs:
name: TV on lights off
In this example, the key = name
, and the value = TV on lights off
.
The key is essentially the keyword for an element you want to use. Each key must be unique, but the order of your keys doesn't matter. Each key-value pair starts on a new line.
The value associated with a key can be in the form of several different data types.
Data Types
Primitives
The primitive data type includes all the basic data types supported by the script editor.
Primitive Forms | Types of Values |
---|---|
Bool |
|
Number | Integer or decimal number |
String |
Plain text String values only need quotes if they begin with |
Date |
Month and Day. Format is MM-DD or MM/DD.
|
Time |
Time can use either AM/PM format or 24H format. Seconds are optional. You can also use time relative to the sun. For example, you can use the keywords
|
DateTime |
Year, Month, Day, and Time of the Day. You must include a space between the Date and the Time. Date format is YYYY-MM-DD or YYYY/MM/DD. Time format is same as "Time" above. Time zones aren't supported.
|
Weekday |
|
Duration |
A period of time.
|
ColorHex |
A 6-digit hexadecimal code that represents a color. There is no leading #.
|
Temperature |
Temperature data. Always add C or F to denote Celsius or Fahrenheit.
|
ColorTemperature |
Color temperature in Kelvin.
|
Structures: Nested key-value pairs
The structure data type is a "block" or data structure containing multiple key-value pairs. These key-value pairs are nested under a single parent key, with each level of nesting indented by the same number of spaces or tabs to indicate hierarchy.
actions: device: Light B - Living room state: on
In this example, the parent key = actions
. The value for actions
is 2 nested key-value pairs:
- Pair 1: child key =
device
; value =Light B - Living room
- Pair 2: child key =
state
; value =on
Lists: Keys with multiple values
To include multiple values with a single key, create a list with a hyphen before each list item. A list can use either structure or primitive data type values, but not both at the same time.
weekdays: - MONDAY - THURSDAY
In the example, the key = weekdays
, and the value = a list that includes Monday
and Thursday
.
Advanced structures: Combined nested pairs and lists
- type: time.schedule at: 10:00 am weekdays: - MONDAY - THURSDAY - type: time.schedule at: SUNSET weekdays: - MONDAY - THURSDAY
In this example, the parent key = starters
. This parent key's value = a list where each list item includes multiple key-value pairs.
Some types of keys require the values to be in specific formats, while other keys inherit characteristics based on a device's capabilities. Learn how specific starters, conditions, and actions are structured.
YAML language syntax
When you write scripted Routines, use these formatting concepts:
Concept | Example |
---|---|
Colon YAML uses a colon |
state: on |
Indentation Indentation indicates structure and hierarchy and defines nested key-pairs. In the example, the parent key = |
|
Hyphen A hyphen followed by a space defines a list item. |
|
Comments Use the pound sign # to add comments or notes to your script. Comments are ignored by the automation engine and won't affect your automation. |
# This is a comment. It will be ignored. |
The script editor template
When you create a new automation, the script editor provides you with an empty template to write your script, using this structure:
metadata |
contains the name of your automation and a description |
automations |
defines your automation behavior |
starters |
defines the triggers that initiate your automation |
condition |
defines restrictions on when your automation should run (optional) |
actions |
defines the actions that occur in your automation |
The template is broken down into 2 main blocks: metadata and automations. Automations is then further broken down into sections for starters, conditions, and actions.
Metadata and automations blocks
The script editor template contains 2 top-level parent keys, or blocks: metadata
and automations
.
The metadata
block contains the name and description of your automation. This is only used to help you identify your automation.
metadata: name: TV time description: When TV is on, turn on lights
The automations
block is the core of your automation script. This is where you define your automation's behavior using starters, conditions, and actions.
automations: starters: # e.g. Motion detected condition: # e.g. Between 2 times actions: # e.g. Turn on lights
To better understand how to use the script editor, visit our codelab, review example scripts, or learn how to format individual starters, conditions, and actions in the Google Home Developer Center.
Auto-complete
The script editor helps guide you through writing your script by providing auto-complete suggestions based on available starters, conditions, and actions when:
- Your cursor is located where there are valid options. For example, after "
- type:
".- You type code with valid suggestions. You'll find the list of suggestions filter as you type.
You manually start auto-complete using the Ctrl+Space shortcut.
Press Enter to select a suggestion from the list. Auto-complete will fill in additional fields based on the structure you select.
Tip: You can use auto-complete to find which device states or commands are available for your device and which devices are available for a certain device state or command.
To find which device states or commands are available for your device, when writing your script, enter the "device:
" key first, and then the "type:
" key. The auto-complete feature will show you a list of states or commands available for that device.
Example
starters: - device: LED lights - Living Room - type:
To find which devices are available for a certain device state or command, enter the "type:
" key first, and then "device:
" key. The auto-complete feature will show you a list of available devices in your home that support that state or command.
Example
starters: - type: device.state.OnOff - device:
Starters, conditions, and actions
Automations are made up of device starters, conditions, and actions. These components define your automation's behaviors.
Some starters, conditions, and actions require a specific type of comparison key-value pair to help complete the automation logic and let your script know what you want evaluated. The value must be a compatible data type. For example, a light's on
state can be either true
or false
. To start the automation if the light is on, you'd use:
state: on is: true
Below you'll find details about the different starters, conditions, and actions available. For a complete list of starters, conditions, and actions, visit the Google Home Developer Center.
Starters
The starters section of your script is where you specify what will cause your script to run. Starters are based on things your device can do or attributes that can be changed, including device states, time, and device events. For example, you may use a light bulb that has the OnOff
, Brightness
, and ColorSetting
states. To include multiple starters, list each starter beginning with the key " - type:
". Your script must meet at least one starter condition for it to run.
Check out the complete list of supported starters.
Starter types
Assistant starters
assistant.command
starter to start a script when a device with Assistant hears an assistant command that begins with "Ok, Google" or "Hey, Google".starters: - type: assistant.command.OkGoogle eventData: query is: party time
Device event starters
Use a device.event
starter to have your script start when a specific event occurs, for example when someone rings your doorbell or a sensor detects something. Note: Not all events can be supported.
starters: - type: device.event.DoorbellPress device: Doorbell - Front door
starters: - type: device.event.PersonDetection device: Camera - Backyard
Example: Start your automation when your camera detects motion.
Note:
- Camera events require a compatible Nest camera, doorbell, or display and event detection set up.
- Some camera events may require a Nest Aware subscription or a camera to be line-powered. For example, sound detection will only work on Nest Cam (outdoor or indoor, battery) when wired.
- You can suppress starters based on device events and device states from reoccurring for a period of time.
Device state starters
device.state
starter to have your automation start based on the state of a device. States are characteristics of a device, for example when the temperature of your thermostat reaches a specific temperature, if a light turns on or off, or when a supported sensor reaches a defined threshold.
device.state
". For example, to check if a device is on, you can use device.state.OnOff
.device.state
starter, begin with 3 keys: type
, device
, and state
, followed by at least one comparison key-value pair.Key | Value | Example |
type |
The device state starter, beginning with device.state |
device.state.ArmDisarm |
device |
Name as shown in Google Home app with room name: Device name - Room name |
Alarm - Front Door |
state |
The starter's field or state data that you want to check. Find the starter you want to use in the Google Home Developer Center to find "Supported Fields" or "State Data". |
isArmed |
You can use the following comparison key-value pairs with the device.state starter:
Comparison keys | Supported value types | Example |
---|---|---|
is |
String | Number | Bool | Dynamic | is: on |
isNot |
String | Number | Bool | Dynamic | isNot: cast |
greaterThan |
String | Number | Bool | Dynamic | greaterThan: 1 |
lessThan lessThanOrEqualTo |
String | Number | Bool | Dynamic | lessThan: 10 |
suppressFor |
Duration | suppressFor: 1hour |
Example: Start your automation if your TV volume is between 1 and 10.
starters: - type: device.state.Volume device: TV - Living room state: currentVolume greaterThan: 1 lessThan: 10
Home state starters
home.state
starter to have your script start based on if you're home or away. This can be detected with presence sensing.starters: - type: home.state.HomePresence state: homePresenceMode is: HOME
Time starters
time
starter to start your automation based on specific days and times. You can use the following comparison key-value pairs with the time starter:How to suppress starters
Use the comparison key suppressFor
to tell your automation to ignore a starter for a period of time. For example, when your camera detects someone, announce “Someone is at the door”, and then don’t make the announcement again for the next 10 minutes even if the camera still detects someone.
Example: When someone walks through my hall in the morning for the first time, open all my blinds and then suppress this starter for the next 20 hours.
metadata:
name: Open Blinds
description: Open blinds in the morning after motion detected
automations:
starters:
- type: device.event.MotionDetection
device: Camera - Hallway
suppressFor: 20hours
condition:
type: time.between
after: 5:00
before: 12:00
actions:
- type: device.command.OpenClose
openPercent: 100
devices:
- Blinds1 - Living Room
- Blinds2 - Family Room
Conditions
and
, or
, and not
to express more complex condition checks.type: or conditions: - type: time.between before: sunrise after: sunset weekdays: - MON - TUE - type: device.state.Volume device: My TV - Living Room state: currentVolume greaterThan: 1 lessThan: 10
In this example, there is one time condition and one device.state
condition. This script will run if it's between sunset and sunrise on a Monday or Tuesday, or if the TV volume is between 1 and 10.
You can use the following condition types:
Condition operators
AND condition
When you use the and
condition, your script will only run if all of the child conditions are met.
Example: Start your automation if the TV is on AND the time is after 6pm.
condition: type: and conditions: - type: device.state.OnOff device: TV - Living Room state: on is: true - type: time.between after: 6:00 pm
OR condition
When you use the or
condition, your script will run when any of the child conditions occur.
Example: Start your automation if the TV is on OR the time is after 6pm.
condition: type: or conditions: - type: device.state.OnOff device: TV - Living Room state: on is: true - type: time.between after: 6:00 pm
NOT condition
When you use the or
condition, your script can't run if the child condition occurs.
Example: Start your automation if the time isn't between 6pm and 8pm.
condition: type: not condition: type: time.between after: 6:00pm before: 8:00pm
Device state conditions
device.state
condition to limit when your script can occur based on a device's state when your script starts. Device.state
conditions are similar to device.state
starters, except instead of telling your script when to start, they limit the situations in which your script can occur.device.state
". For example, to check if a device is on, you can use device.state.OnOff
.device.state
condition, begin with 3 keys: type
, device
, and state
, followed by at least one comparison key-value pair.Key | Value | Example |
---|---|---|
type |
The device state condition, beginning with device.state |
device.state.OnOff |
device |
Name as shown in Google Home app with room name: Device name - Room name |
Chromecast - Living Room |
state |
The starter state that you want to check Find the device state condition you want to use in the Google Home Developer Center. |
state: on |
Tip: To find which device states are available for your device, enter the "device:
" key first and then the "type:
" key in your script. Auto-complete will show you a list of states available for that device.
You can use the following comparison key-value pairs with the device.state
condition:
Comparison keys | Supported value types | Example |
---|---|---|
is |
String | Number | Bool | Dynamic | is: on |
isNot |
String | Number | Bool | Dynamic | isNot: cast |
greaterThan |
String | Number | Bool | Dynamic | greaterThan: 1 |
lessThan lessThanOrEqualTo |
String | Number | Bool | Dynamic | lessThan: 10 |
Example: Start your automation if your thermostat detects a humidity level higher than 55%.
condition: type: device.state.TemperatureSetting device: My Thermostat - Living Room state: thermostatHumidityAmbient greaterThan: 55
Home state conditions
home.state.HomePresence
condition to limit when your script can occur based on whether someone is home or away.home.state.HomePresence
condition, make sure you set up presence sensing in the Google Home app and that presence sensing is working as expected. Home presence can be determined by the location of your household's phones, sensors in some Nest devices, or by manually switching Home or Away in the Google Home app.Learn more about presence sensing and home and away Routines:
home.state.HomePresence
condition:Comparison keys | Supported value types | Example |
---|---|---|
is |
String ("HOME" or "AWAY") | is: away |
isNot |
String ("HOME" or "AWAY") | isNot: HOME |
for |
Duration | for: 30min |
suppressFor |
Duration | suppressFor: 1hour |
Example: The home.state.HomePresence
condition will start the automation if your presence is set to HOME.
condition: type: home.state.HomePresence state: homePresenceMode is: HOME
Time conditions
time.between
condition to limit when your script can occur. You can use the following comparison key-value pairs with the time.between
condition:Actions
The actions section of your script is where you list what you want your devices to do. To include multiple actions, list each action beginning with the key "- type:
". Your script must have at least one action for it to run. Most actions begin with device.command
.
You can use the following action types:
Assistant actions
Use the assistant.command
action with your speakers or displays to have Assistant complete actions like “Turn off all lights” or “Tell me the weather.”
By using Assistant commands you can command devices by room or for your entire home without using specific device names. This can save you time as future devices added to the Home app can automatically work with this command. Assistant commands require a compatible speaker or display to run the action.
actions: - type: assistant.command.OkGoogle okGoogle: Turn on living room lights devices: My Speaker - Room Name
actions: - type: assistant.command.OkGoogle okGoogle: Turn off all lights devices: My Speaker - Room Name
actions: - type: assistant.command.Broadcast devices: - My Speaker 1 - Room Name - My Speaker 2 - Room Name message: It’s dinner time.
Assistant actions also allow you to perform custom actions like:
- "Play Hello by Adele from YouTube Music on bedroom speaker."
- "Play funny cat videos from YouTube on Living Room Display."
- "What's the weather like tomorrow?"
- "Tell me a joke."
- "Show me the driveway camera on home office display."
Device actions
device.command
action to control or adjust a device. Each action command has its own set of characteristics and structure. You can add commands to your script by adding the command action for a device after "device.command
". For example, to turn on a device, you can use device.command.OnOff
. A device.command
action must include the following info:Key | Value | Example |
---|---|---|
type |
The device action, beginning with device.command |
device.command.OpenClose |
devices |
Name of device as shown in Google Home app with room name: Device name - Room name. To include multiple devices, create a list. | Blinds - Bedroom |
Tip: To find which actions or commands are available for your device, enter the "device:" key first and then the "type:" key, auto-complete will show you a list of actions available for that device.
Many device.command
actions have additional keys that specify the required input for the command. For example, device.command.ThermostatTemperatureSetpoint
requires a thermostatTemperatureSetpoint
key-value pair to tell the thermostat the new temperature you want it set to.
To learn more about how to use commands, find the related action at the Google Home Developer Center and follow the structure for the action you want to use.
Example: Turn on the TV in your living room.
actions: type: device.command.OnOff devices: TV - Living room on: true
Example: Turn on a light, and turn it off after 5 minutes.
actions:
- type: device.command.OnOff
devices: Light A - Living Room
on: true
- type: time.delay
for: 5min
- type: device.command.OnOff
devices: Light A - Living Room
on: false
Notification actions
Use the home.command.Notification
action to have your script send notifications to the mobile devices of home members. For example, you can get notifications when appliances connected to smart plugs turn off or go offline.
actions: - type: home.command.Notification members: - Alex - cloudysanfrancisco@gmail.com - Kim - jeffersonloveshiking@gmail.com title: It’s movie time! body: Join me in the living room
Time actions
time.delay
action to have your script wait a defined amount of time between 2 actions in your list instead performing all actions at once. You can add multiple delays to your script. For example, you can have your script wait 10 seconds between each action.actions: - type: device.command.OnOff devices: - Bedside Lamp - Bedroom - Ceiling Light - Bedroom on: true - type: time.delay for: 30sec - type: device.command.OnOff devices: - Bedside Lamp - Bedroom - Ceiling Light - Bedroom on: false
Resources
Practice writing a script
To get started, we'll create a very simple, but popular automation: "Turn off the lights when the TV turns on."
- Open home.google.com/automations and sign in to your account.
- Click Add new .
- Fill out the metadata information. In this script, the name =
TV on lights off
, and the description =Turn off lights when TV turns on.
Make sure you format your script correctly.metadata: name: TV on lights off description: Turn off lights when TV turns on.
- To add starters, create a new line, indent this with 2 spaces or press Tab once, and input "
starters:
". Then, on the next line, indent again and input "- type:
".Tip:- To create a new line, press Shift Enter.
- To include multiple starters, each starter should begin with a hyphen and a space.
metadata: name: TV on lights off description: Turn off lights when TV turns on automations: starters: - type:Note: The script editor will help you with the structure by providing auto-complete suggestions based on available starters. To choose from the suggestions, use your keyboard’s arrow keys to select one, then press Enter to insert it.
- Add the
device.state
starter. Remember, to use a device.state starter, you need 3 keys:type,
device
, andstate
, followed by at least one comparison key-value pair. The script editor will help you with the structure by providing auto-complete suggestions based on available starters, conditions, and actions. In this script:- Type =
device.state.OnOff
. This is the device's state that will be evaluated to start our automation. - Device =
Chromecast - Living Room
. This is the name of our device as it appears in the Google Home app. - State =
on
. On is the supported field or State data for the OnOff device state. - The comparison key-value pair =
is: true
. The value for this comparison key is a primitive data type. The script will run if the TV is on.metadata: name: TV on lights off description: Turn off lights when TV turns on automations: starters: - type: device.state.OnOff device: Chromecast - Living Room state: on is: true
For comparison, let's check a similar script with a different starter. In the script below, the automation starts when the volume is between 1 and 10, rather than when the TV turns on. To make this change, we replaced the
OnOff
state withVolume
and changed the state tocurrentVolume
to match the new attribute. We also changed the comparison key-value pairs to 2 nested pairs that create a range:greaterThan: 1
andlessThan: 10
. For more examples, here is a complete list of starters you can use.metadata: name: TV on lights off description: Turn off lights when TV turns on automations: starters: - type: device.state.Volume device: Chromecast - Living Room state: currentVolume greaterThan: 1 lessThan: 10
- Type =
- Click Save to save your script at any time. When you save a script, the script editor automatically validates your script and checks for errors. An invalid script can't run.
- Now add an action to your script. To add actions, create a new line, indent this with 2 spaces or press Tab once, and input "
actions:
". Then, on the next line, indent again and input "- type
".Tip:- To create a new line, press Shift Enter.
- To include additional actions, each action should begin with a hyphen and a space.
metadata: name: TV on lights off description: Turn off lights when TV turns on. automations: starters: - type: device.state.OnOff device: Chromecast - Living Room state: on is: true actions: - type:
- To turn off our lights, we'll use the
device.command
action. To use the device.command action, we'll include the following info:- Type =
device.command.OnOff
. This is the name of the command or action.Note: Commands can have multiple commands nested underneath your devices, and each command has its own state. - Devices = a list containing
Floor Lamp - Living Room
andOverhead Light - Living Room
. These are the names of our lights, as they appear in the Google Home app. To include multiple lights, we listed each device on separate lines, each beginning with a hyphen. - The command's desired state =
on: false
. This line tells our lights to turn off.metadata: name: TV on lights off description: Turn off lights when TV turns on. automations: starters: - type: device.state.OnOff device: Chromecast - Living Room state: on is: true actions: - type: device.command.OnOff devices: - Floor Lamp - Living Room - Overhead Light - Living Room on: false
- Type =
- Click Save to save your script. If there are no errors, your script will automatically activate: whenever your TV turns on, your light will turn off. If you're not ready for your script to run yet, pause your script by turning Activate off.
For more practice, try changing some of your script to use different starters, data types, multiple actions, or an additional condition like time.between
. You can also review example scripts and check out codelab to learn more. For detailed info about starters, actions, and conditions, check out the Google Home Developer Center.
Help with scripted automations
- Find help with scripts and learn what others are working on in the Google Home Automation community.
- For automations to work, scripts must use valid code. If an error exists, a message appears. Learn more about errors and warnings in the script editor.
- To validate your code, click or tap Validate in the script editor or try to save your script. Here are some common errors:
- Make sure you use the correct device name in the format Device name - Room name. If you're not sure, check the name of your device in the Google Home app.
- Make sure your device supports the function you want it to perform. You can also use auto-complete to find available options.
- Make sure you include an action. Actions are required for an automation to run.
- If the script saves, but the automation doesn't behave as expected, manually confirm that each component in your script works. For example, if you wrote a script to turn on the light and change the brightness at sunset, try completing these tasks with an assistant command to confirm that each individual function works. You can also check that:
- Your device is added or linked in the Google Home app.
- Your device is connected and online.
- The device name, starters, conditions, and actions are written correctly.
Note: Manufacturers may change device traits when they perform updates and this can cause scripts to stop working. You can use auto-complete to help update affected scripts. - Your script has proper indentation and formatting.
- With Google Home for web, you can also access Automation logs below your script to check your automation’s history and to identify potential problems. Learn more about the types of messages you see in the Automation logs.
- Try using the script editor’s experimental generative AI feature to describe the automation you want and it will draft a script for you to review and edit.
- Learn more about the basics of Routines and how to troubleshoot them.
- Learn more about creating and editing scripted automations.