Skip to content

How to trigger a plan?

Calendar Mode

Does not depend on other information — you can directly determine if it matches based on the current date.

First, recurring type:

  every: 6-12

Second, one-shot type — the trigger is removed after execution:

  on: 2025-8-26

A shortcut for "every day":

  every: day

Multiple dates can be specified using a list:

  every: [Sat, Sun] # matches every Saturday and Sunday

Note that when using on, such as on: [Sat, Sun], matching any one date will remove the entire trigger. If you want to remove only the matching one, you can use on as multiple independent triggers:

  trigger:
  - on: Sat
  - on: Sun

Trigger Examples

Recurring:

  • June 12th every year: every: 6-12
  • Every Wednesday: every: Wednesday or every: Wed
  • The 15th of every month: every: 15
  • Every day in August: every: August or every: Aug

One-shot:

  • On July 15th: on: 7-15
  • On the next 5th: on: 5
  • On August 26, 2025: on: 2025-8-26 — note that every: 2025-8-26 also only fires once, but differs in that it won't be auto-deleted

Note: if you specify the 31st but the month has no such day, it will not trigger at month-end. The mode strictly adheres to the specified date.

Lunar Calendar Dates

Compared to the Gregorian calendar, you need to prefix the date with 农历 (lunar calendar). If specifying a leap month, append 闰 at the end.

  every: 农历6-12闰

Spaces are also allowed:

  every: 农历 6-12 闰

Additionally, you can use the 24 solar terms after every:

  every: 立秋

Gregorian Repeating Mode

The task date is determined based on relative descriptions.

Specify dates by week and day, within a monthly or yearly cycle.

  • Set a start date: from: 2025-11-19. Must include the year. If the month is omitted, it defaults to January; if the day is also omitted, it defaults to the 1st. In some cases, this parameter can be omitted, such as for monthly or yearly cycles.
  • Set a cycle: every N days, weeks, months, a specific month, or years — every: 3week, every: 2month, every: June, every: year.
  • Set a specific day, described by day number or weekday: 3rd day on: 3d, last day on: -1day or last: day, first Monday on: Monday, last Friday on: -Fri or last: Fri.

A Specific Day Each Month/Year

First Monday of every month:

  every: month
  on: Monday

Second-to-last day of every month:

  every: month
  on: -2d

Last Saturday of every month:

  every: month
  last: Sat   # equivalently, last: 1Sat

Second-to-last Saturday of every month:

  every: month
  last: 2Sat

Last Saturday of every June:

  every: June
  last: Sat

Last Saturday of every year:

  every: year
  last: Sat

Every N Days/Weeks/Months/Years

Without on or last, the from date is the first day, and the trigger fires every time the every interval passes. Examples below.

Every 16 days, fires on 2025-08-11, 2025-08-27, 2025-09-12, ...

  from: 2025-8-11
  every: 16d

Every 3 weeks, fires on 2025-11-21, 2025-12-12, ...

  from: 2025-11-21
  every: 3week

Every 2 months, fires on 2025-11-21, 2026-01-21, ...

  from: 2025-11-21
  every: 2month

Every 2 years, fires on 2025-11-21, 2027-11-21, ...

  from: 2025-11-21
  every: 2year

For once a year, you can simply use every: 11-21.

Note: if from is the 31st of a month, and the next month has no 31st, it will fire on the last day of that month (e.g., the 30th).

A Specific Day within Every N Days/Weeks/Months/Years

Starting from November 21, 2025, on the Wednesday of the first week in every 3-week cycle. This means it fires on November 19 (already past), December 10, ...

  from: 2025-11-21
  every: 3week
  on: Wed  # on: 3d also works

Starting from August 2025, on the 7th-to-last day of the first month in every 2-month cycle. This means it fires on August 25, October 25, ...

  from: 2025-8
  every: 2month
  last: 7d

Starting from 2025, runs on the 3rd day of the first year in every 2-year cycle:

  from: 2025
  every: 2year
  on: 3d

The date specified by from doesn't need to be precise to the day. If the cycle is in years, year-level precision is fine; if in days, day-level precision is needed. For weekly cycles, any day within the starting week works and represents that entire week.

There is one constraint: it only looks for matches within the first unit of each cycle — the first week of every N weeks, the first month of every N months, etc. If you want it to match a later unit in the cycle, adjust the from date accordingly.

Dependency Mode

Keywords: if, after, and before. if is followed by a tag, and multiple conditions can be combined with and and or. after and before are followed by a duration in days or weeks: 2d, Sat. Both after and before can be used together.

You may want Plan B to trigger along with Plan A, or Plan B to trigger a certain number of days before or after Plan A. This relationship can be described as: Plan B's trigger depends on Plan A's trigger.

First, add a tag to Plan A:

- desc: Plan A
  every: 1-11
  tag: plan_a

To trigger simultaneously, simply use if with the tag:

- desc: Plan B
  if: plan_a

2 days after Plan A triggers (January 13):

  if: plan_a
  after: 2d

6 days before Plan A triggers (January 5):

  if: plan_a
  before: 6d

The first Saturday before Plan A triggers (not counting the same day, January 4):

  if: plan_a
  before: Sat

The second Saturday before Plan A triggers (December 28):

  if: plan_a
  before: 2Sat

If a plan's timing is uncertain — for example, future support for triggering on rainy days — plans that depend on it cannot guarantee they will fire.

Compound Mode

If a plan has multiple trigger conditions, put all triggers in a list.

Fire the plan every Saturday and the last Sunday of every month:

- desc: Practice hobbies
  trigger:
  - every: Sat
  - every: month
    last: Sun

Note that if a plan uses trigger, you cannot also place triggers at the top level. The following is illegal:

  every: month
  last: Sun
  trigger:
  - every: Sat

Relationships Between Triggers

The above fires when any trigger is satisfied — an "OR" relationship.

If all trigger conditions must be satisfied — an "AND" relationship — specify it as follows.

For example, "the last day of the month AND that day is a Saturday":

  trigger:
  - every: month
    last: day
  - every: Sat
  match: all  # default is any

Except

Keyword: except, followed by tags and calendar-mode content, with list support.

When except is satisfied, the plan will not fire, even if other triggers are also satisfied.

- desc: Every day, except Sunday
  every: day
  except: Sun

Delayed Execution

Keyword: delay_if, followed by tags and calendar-mode content, with list support.

When a plan has been triggered but delay_if is also satisfied, the trigger is suppressed. The plan will execute immediately the next time delay_if is no longer satisfied, and a delay notice will be shown.

For example: if there's work on Saturday, postpone to the next day:

  every: Sat
  delay_if: workday   # workday is a custom tag