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

Every three years on September 4, starting from September 4, 2026. The first occurrence is 2026-09-04, followed by 2029-09-04.

from: 2026
every: 3year
on: 9-4

Both on and last can also be followed by a list to specify multiple dates. For example, you can specify every Monday and Saturday of every two-week period.

  every: 2week
  on: [Mon, Sat]

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

trigger can be empty, it will be treated as being closed.

- desc: Practice hobbies
  trigger: []

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

When is the Trigger active?

Each trigger mode can include a from: 2026-9-3 field. This means that the trigger will be skipped before September 3, 2026, and will only be considered on and after September 3, 2026.

For recurring modes, from also serves the additional purpose of determining the first occurrence of the recurrence cycle.

trigger:
  - from: 2026-9-3
    every: Sat
  - from: 2026-9-3
    every: month
    last: Sun

If from is not specified, the trigger is considered always active.