Arithmetic and formatting in date variables

See also: Butler variables, Custom field arithmetic

You can use different date variables to move the date or to change the way the date is displayed. For example, when using the value of a variable like {cardduedate}, you might want to shift the value by a few days or weeks or display it in another timezone such as GMT.

You can use all of the operations described in this article with the date and due date variables and with custom field variables (in custom fields of the "Date" type).

Adding or subtracting from a date variable value

You can add or subtract from the following values of a date variable:

Time Value Example Description
Minutes min {time+30min} 30 minutes after the specified time.
Hours h {cardduedate-2h} Two hours before the card is due.
Days d {date-7d} The date seven days ago.
Working days wd {date+5wd} Five working days after the date.
Weeks w {{%Start Date}+6w} Six weeks after the date in the custom field {{%Start Date}}.
Years y {{%Start Date}+1y} One year after the date in the custom field {{%Start Date}}.

Note: In working days values, {date+1wd} is not the next working day but the date after a working day has passed. This subtle distinction only matters if the date falls on a weekend: Saturday +1 working day is Tuesday. To obtain the next working day, use {datelong+0wd}; to obtain the previous working day, use {datelong-0wd}.

Changing parts of a date value

You can change such parts of the date value as the day of the week, the day of the month, or combine both adjustment operations.

Change the day of the week

To change the days of the week, use the wd value prefixed with the number of the weekday.

Note: When changing the day of the week, wd stands for the day of the week instead of the working day


  • {date=0wd} is the Sunday of the current week.
  • {date=1wd} is the Monday of the current week, and so on.

Change the day of the month

To change the days of the month, use the d value prefixed with the day number. 


  • {date=1d} is the first day of the current month.
  • {date=15d} is the fifteenth day of the current month.
  • {date=31d} is the last day of the current month, regardless of how long the month is.

Combine week and day adjustments

You can both change days of the week ( wd) and days of the month (d) to adjust the date.


  • {date-1w=1wd} is the Monday last week.
  • {date+3m=31d} is the last day of the month three months from now.

Changing the timezone

Butler supports common abbreviations for timezone specifications such as PST, EDT, GMT, and others. 

You can specify a short timezone name such as {{%Start Date}@HKT} (Hong Kong time) or the full timezone name like {date@Australia/Sydney} . You can find a full list of timezones on Wikipedia.

You can also combine timezone changes with adjustment operations. For example, {cardduedate+5wd@PST} is the date in five working days from now in Pacific Time.

Formatting of date values

The value of the date can also be formatted by specifying a pattern after ~. The format specification comes from the moment.js library.


In pattern {date~dddd, MMMM Do YYYY, h:mm:ss a}, the date will have the following format: Thursday, May 31st 2018, 12:00:00 am.

The moment.js library formatting can be particularly useful if you need to generate list or card names. 


when custom field "Start Date" is set by anyone, move the card to list "Week {{%Start Date}=1wd~MMM D} - {{%Start Date}=5wd~MMM D}" . 

This Butler command will automatically move cards to a list depending on the value of a custom field called "Start Date". Lists will be created automatically (if they don't exist), with names formatted as follows: Week May 28th - Jun 1st.

Nested custom field variables (advanced)

You can use the value of a custom field to specify the parameters for date arithmetic or formatting operations. For example: {{%Start Date}+wd@.