Simple Cue

Named, one-shot scheduled triggers for Home Assistant. Set a cue by name and datetime — when the time comes, Simple Cue executes the stored action and fires a simple_cue_triggered event. No helper entities, no template hacks.

---

Installation (HACS)

1. Add this repo as a custom repository in HACS (type: Integration)
2. Search for Simple Cue and install
3. Restart Home Assistant
4. Go to Settings → Devices & Services → Add Integration → Simple Cue and click Submit — no configuration is required

---

How It Works

Call simple_cue.set from any automation or script with a name, a datetime, and an optional list of actions. Simple Cue stores the cue, waits, then:

1. Fires a simple_cue_triggered event (for any external listeners)
2. Executes the stored action list directly via HA's script engine

No external Action Dispatcher automation is needed.

---

Services

simple_cue.set

Field	Type	Required	Description
name	string	Yes	Unique slug (e.g. coffee)
datetime	string	Yes	When the cue should fire
action	list	No	HA-native action(s) to execute

Setting a cue with an existing name replaces it.

The datetime field

Accepts natural language or an ISO-8601 string.

Important

The natural language parser matches exact phrases only. Copy expressions from the table below exactly. Unrecognised strings fail silently — check Settings → System → Logs for Could not parse datetime errors.

Expression	Meaning
tomorrow at 7am	Tomorrow at 07:00 local time
tomorrow at 6:30am	Tomorrow at 06:30 local time
today at 17:30	Today at 17:30 local time
in 2 hours	2 hours from now
in 30 minutes	30 minutes from now
in 3 days	3 days from now
next friday at 9pm	The coming Friday at 21:00
monday at noon	Next Monday at 12:00
midnight	Start of tomorrow (00:00)
noon	12:00 today (or tomorrow if already past)
2025-06-01T08:00:00	ISO-8601 exact datetime

Time formats: 5am · 5pm · 5:30am · 17:00 · noon · midnight

Day formats: today · tomorrow · monday – sunday · next monday – next sunday

Common mistakes:

You type	Why it fails
tommorow at 5am	Typo
tomorrow @ 5am	Use at, not @
in a couple hours	Needs a number
this friday at 9pm	Use next friday or bare friday

The action field

Uses HA's native action format — the same syntax as automation actions. In the UI you get the full visual action builder.

Single action:

action: simple_cue.set
data:
  name: living_room_lights_off
  datetime: "today at 6:45pm"
  action:
    - action: light.turn_off
      target:
        entity_id: light.living_room

Multiple actions (sequence):

action: simple_cue.set
data:
  name: bedtime_routine
  datetime: "today at 11pm"
  action:
    - action: light.turn_off
      target:
        entity_id: light.all_lights
    - action: lock.lock
      target:
        entity_id: lock.front_door
    - action: climate.set_temperature
      target:
        entity_id: climate.thermostat
      data:
        temperature: 68

No action (event-only — your own automation handles it):

action: simple_cue.set
data:
  name: coffee
  datetime: "tomorrow at 6:30am"

simple_cue.cancel

Field	Type	Description
name	string	Cue name to cancel

simple_cue.cancel_all

Removes every active cue.

---

Events

When a cue fires, simple_cue_triggered is emitted before the action executes.

event_type: simple_cue_triggered
event_data:
  name: living_room_lights_off
  datetime: "2025-06-01T21:00:00+00:00"
  action:
    - action: light.turn_off
      target:
        entity_id: light.living_room

The action key is always present. It is null when no action was provided.

---

Entities

sensor.simple_cue_{name}

One entity per active cue, removed automatically when the cue fires or is cancelled.

Attribute	Type	Description
name	string	Cue slug
remaining	string	Human-readable countdown (e.g. "2h 14m")
action	list / null	Stored action payload, or null

State is the fire datetime in local time (ISO-8601).

sensor.simple_cue_count

Always present. Shows the total number of active cues.

Attribute	Type	Description
cues	dict	name → fire datetime for all active cues
cues_with_actions	int	Count of active cues carrying an action payload

---

Example: Coffee Machine

# Automation 1 — schedule the cue (with inline action)
alias: "Coffee — Schedule Cue"
triggers:
  - trigger: state
    entity_id: input_boolean.coffee_tomorrow
    to: "on"
actions:
  - action: simple_cue.set
    data:
      name: coffee
      datetime: "tomorrow at 6:30am"
      action:
        - action: switch.turn_on
          target:
            entity_id: switch.coffee_machine
  - action: input_boolean.turn_off
    target:
      entity_id: input_boolean.coffee_tomorrow

Or use the event-only pattern and react separately:

# Automation 1 — schedule the cue (no action)
alias: "Coffee — Schedule Cue"
triggers:
  - trigger: state
    entity_id: input_boolean.coffee_tomorrow
    to: "on"
actions:
  - action: simple_cue.set
    data:
      name: coffee
      datetime: "tomorrow at 6:30am"
  - action: input_boolean.turn_off
    target:
      entity_id: input_boolean.coffee_tomorrow

# Automation 2 — react when the cue fires
alias: "Coffee — Brew"
triggers:
  - trigger: event
    event_type: simple_cue_triggered
    event_data:
      name: coffee
actions:
  - action: switch.turn_on
    target:
      entity_id: switch.coffee_machine

---

Action Dispatcher Automation (Legacy)

Note: As of v2.0.0, Simple Cue executes action payloads internally. The Action Dispatcher automation below is no longer required for new installations. It is preserved here for reference and backward compatibility.

alias: "Simple Cue — Action Dispatcher"
description: >
  Legacy: executes structured action payloads when a cue fires.
  Not needed for v2.0.0+ installations.
triggers:
  - trigger: event
    event_type: simple_cue_triggered
conditions:
  - condition: template
    value_template: "{{ trigger.event.data.action is not none }}"
actions:
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ trigger.event.data.action is mapping }}"
        sequence:
          - action: "{{ trigger.event.data.action.action }}"
            target: "{{ trigger.event.data.action.get('target', {}) }}"
            data: "{{ trigger.event.data.action.get('data', {}) }}"
      - conditions:
          - condition: template
            value_template: "{{ trigger.event.data.action is sequence }}"
        sequence:
          - repeat:
              for_each: "{{ trigger.event.data.action }}"
              sequence:
                - action: "{{ repeat.item.action }}"
                  target: "{{ repeat.item.get('target', {}) }}"
                  data: "{{ repeat.item.get('data', {}) }}"
mode: queued
max: 20

---

Troubleshooting

Cue fires but action doesn't execute

• Check Settings → System → Logs for errors from simple_cue
• Open Developer Tools → Events, listen for simple_cue_triggered, and verify the action field looks correct
• Confirm the entity_id and action name (e.g. light.turn_off) are valid

"Could not parse datetime" in logs

• The natural language parser is strict — see the accepted expressions table above
• Use ISO-8601 for exact datetimes: 2025-06-01T21:00:00

---

Migrating from v1.x

Action payloads stored with the old service: key format are automatically converted to the new action: key format on first load. No manual changes are needed.

---

License

MIT