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:
Visit codelab
Important: All household members can check when these Routines run. Routines are for convenience only, not safety- or security-critical use cases. Don't create Routines that could result in injury or harm if they fail to start or stop. Routines can depend on working internet, Wi-Fi, and service availability from both Google and the third parties who manufacture the devices included in Routines. Routines may not always work, and Google isn't responsible for any harm or losses incurred due to failed Routines.
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:
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
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 [, {, ", ',#, or the string contains a colon followed by one or 2 spaces. Quotation marks must match. For example, use " " or ‘ ‘, not " ‘.
|
| 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 sunrise and sunset followed by a duration.
12:30 am13:00:01sunrise / sunsetsunset+30min / sunset-1hour
|
| 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.
2022/01/01 14:002022-12-31 sunrise+30min
|
| Weekday |
MON or MONDAYTUE or TUESDAYWED or WEDNESDAYTHU or THURSDAYFRI or FRIDAYSAT or SATURDAYSUN or SUNDAY
|
| Duration |
A period of time.
30min1hour20sec1hour10min20sec
|
|
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
For more complex automations, the value can be a list containing multiple nested key-value pairs.
starters:
- 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 : followed by a space to separate a key from its value.
|
state: on |
|
Indentation
Indentation indicates structure and hierarchy and defines nested key-pairs.
In the example, the parent key = metadata. The keys name and description are child keys nested under the parent key metadata. The nested keys are each indented by 2 spaces or one tab to indicate their hierarchy.
|
metadata:
name: TV on lights off
description: Turn off lights when TV turns on
|
|
Hyphen
A hyphen followed by a space defines a list item. |
weekdays:
- MONDAY
- THURSDAY
|
|
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:
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.
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
Use an assistant.command starter to start a script when a device with Assistant hears an assistant command that begins with "Ok, Google" or "Hey, Google".
Note: If an automation is started by a voice command and there is an Assistant action in the script, the Assistant action will occur on the device that hears the voice command, even if a different device was specified in your script.
Example: Start your automation when someone says, "Ok, Google party time."
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.
Example: Start your automation when your doorbell is pressed.
starters:
- type: device.event.DoorbellPress
device: Doorbell - Front door
Example: Start your automation when your camera detects a person.
starters:
- type: device.event.PersonDetection
device: Camera - Backyard
Example: Start your automation when your camera detects motion.
starters:
- type: device.event.MotionDetection
device: Camera - Backyard
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
Use a
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.
Note: You can
suppress starters based on device events and device states from reoccurring for a period of time.
Add the state for a device state starter after "device.state". For example, to check if a device is on, you can use device.state.OnOff.
To use a 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 |
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 starter:
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
Use
home.state starter to have your script start based on if you're home or away. This can be detected with
presence sensing.
Example: Start your automation when you are home.
starters:
- type: home.state.HomePresence
state: homePresenceMode
is: HOME
Time starters
Use a 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:
| Comparison keys |
Supported value types |
Example |
before |
Time |
before: sunset |
after |
Time |
after: 7:00 am |
weekdays |
Weekday |
weekdays: MON |
Example: Start your automation on Mondays and Tuesdays, 30 minutes after sunrise.
starters:
- type: time.schedule
at: sunrise+30min
weekdays:
- MON
- TUE
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 are optional restrictions on when your automations should run. If you include conditions, your script will only run if the conditions are met. Many starters can also be used as conditions, and they can be combined with logical operators 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
Use a 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.
Add the state for a device state condition after "device.state". For example, to check if a device is on, you can use device.state.OnOff.
To use a 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:
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
Use a home.state.HomePresence condition to limit when your script can occur based on whether someone is home or away.
Note: Before creating a script that uses the 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:
You can use the following comparison key-value pairs with the 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
Use the time.between condition to limit when your script can occur. You can use the following comparison key-value pairs with the time.between condition:
| Comparison keys |
Supported value types |
Example |
before |
Time |
before: sunset |
after |
Time |
after: 7:00 am |
weekdays |
Weekday |
weekdays: MON |
Example: Only start your automation on weekends before 10am.
condition:
type: time.between
before: 10am
weekdays:
- SAT
- SUN
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.
Note: If an automation is started by a voice command and there is an Assistant action in the script, the Assistant action will occur on the device that hears the voice command, even if a different device was specified in your script.
Example: Use “Turn on living room lights” to turn on all lights in the living room.
actions:
- type: assistant.command.OkGoogle
okGoogle: Turn on living room lights
devices: My Speaker - Room Name
Example: Use “Turn off all lights” to turn off all of your lights set up in your home.
actions:
- type: assistant.command.OkGoogle
okGoogle: Turn off all lights
devices: My Speaker - Room Name
Example: You can have your speakers or displays make an announcement.
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."
Note: Assistant actions that require
Voice Match or
personal results turned on won’t work with household automations created with the script editor.
Use the 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
Use the 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.
Example: Turn on your lights, and turn them off after a 30 second delay.
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."
Note: If you don't have a streaming device, smart lights, or comparable devices, you can still follow along to understand the scripting process, but your script won't run at the end.
- 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, and state, 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 with Volume and changed the state to currentVolume to match the new attribute. We also changed the comparison key-value pairs to 2 nested pairs that create a range: greaterThan: 1 and lessThan: 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
- 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 and Overhead 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
- 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.