Write scripted automations with the script editor

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.

• 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

actions:
  device: Light B - Living room
  state: on

weekdays:
- MONDAY
- THURSDAY

- type: time.schedule
  at: 10:00 am
  weekdays:
  - MONDAY
  - THURSDAY
- type: time.schedule
  at: SUNSET
  weekdays:
  - MONDAY
  - THURSDAY

YAML language syntax

When you write scripted Routines, use these formatting concepts:

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

weekdays:
- MONDAY
- THURSDAY

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:

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.

starters:
- device: LED lights - Living Room
- type:

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:
- type: assistant.command.OkGoogle
  eventData: query
  is: party time

starters:
- type: device.event.DoorbellPress
  device: Doorbell - Front door

starters:
- type: device.event.PersonDetection
  device: Camera - Backyard 

starters:
- type:  device.state.Volume
  device: TV - Living room
  state:  currentVolume
  greaterThan: 1
  lessThan: 10 

starters:
- type: home.state.HomePresence
  state: homePresenceMode
  is: HOME

starters:
- type: time.schedule
  at: sunrise+30min
  weekdays:
  - MON
  - TUE

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

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

condition:
  type: and
  conditions:
  - type: device.state.OnOff
    device: TV - Living Room
    state: on
    is: true
  - type: time.between
    after: 6:00 pm

condition:
  type: or
  conditions:
  - type: device.state.OnOff
    device: TV - Living Room
    state: on
    is: true
  - type: time.between
    after: 6:00 pm

condition:
  type: not
  condition:
    type: time.between
    after: 6:00pm
    before: 8:00pm

condition:
  type: device.state.TemperatureSetting
  device: My Thermostat - Living Room
  state: thermostatHumidityAmbient
  greaterThan: 55

condition:
  type: home.state.HomePresence
  state: homePresenceMode
  is: HOME

condition:
  type: time.between
  before: 10am
  weekdays:
  - SAT
  - SUN

Actions

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.

actions:
  type: device.command.OnOff
  devices: TV - Living room
  on: true

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

actions:
- type: home.command.Notification
  members:
  - Alex - [email protected]
  - Kim - [email protected]
  title: It’s movie time!
  body: Join me in the living room
 

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."

1. Open home.google.com/automations and sign in to your account.
2. Click Add new .
3. 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.

4. 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.

5. 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

6. 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.
7. 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:

8. 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

9. 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.