> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar arithmetic (@date)

> @date computes what models count badly: days between two dates, a date plus an offset, a weekday, and expressions like 'last Saturday' or '3 weeks ago'. Pure, offline and read-only.

Language models read dates well and count them badly: how many days between the 14th of March and the 17th of April, what day was last Saturday, what is three weeks before the 5th. `@date` answers those from the calendar instead of from the model's head. Every verb is **pure, offline and read-only**: no file, network or credential is touched, and the tool runs in parallel with others.

It counts from the **current date**, which [`CHATCLI_NOW`](/reference/environment-variables) pins for a whole run, so a conversation replayed from the past reads "last Saturday" against the right day.

```text theme={"system"}
<tool_call name="@date" args='{"cmd":"diff","args":{"from":"2023-03-14","to":"2023-04-17"}}' />
<tool_call name="@date" args='{"cmd":"resolve","args":{"expr":"last saturday"}}' />
<tool_call name="@date" args='{"cmd":"add","args":{"date":"2023-01-31","months":1}}' />
```

| Verb | Arguments | What it does |
| - | - | - |
| `now` | | the current date, weekday and time |
| `diff` | `from`, `to?` (default today) | calendar days, weeks plus days, calendar months plus days, and the elapsed time; it also says how many days it is **counting both end dates**, so an inclusive reading is never a guess |
| `add` | `date?` (default today), `days?`, `weeks?`, `months?`, `years?` | the date that far away (negative = earlier); a month end clamps to the last day of a shorter month, so January 31 plus one month is February 28 |
| `weekday` | `date?` | the weekday of a date |
| `resolve` | `expr`, `as_of?` | `yesterday`, `tomorrow`, `last` or `next` plus a weekday, `N days\|weeks\|months\|years ago`, `in N days\|weeks\|months`, as a concrete date |

Dates are read as `2023-03-14`, `2023/03/14`, `2023-03-14 18:11`, RFC 3339, or the form [`@session`](/context/session-search) prints (`2023-03-14 (Tue) 18:11`); `today` and `now` mean the current date.

## What the answers say

`diff` reports calendar days (the later date minus the earlier one, ignoring the time of day), so a session saved on the 15th at 18:11 and a question on the 18th at 01:48 are **3 days** apart even though 55 hours passed:

```text theme={"system"}
from 2023-04-15 (Sat) 18:11 to 2023-04-18 (Tue) 01:48
calendar days: 3 (4 counting both end dates)
weeks: 0 weeks and 3 days
calendar months: 0 months and 3 days
elapsed: 2d 7h 37m
```

`resolve` states the rule it used. "Last Saturday" is the most recent Saturday **strictly before** the reference date, and "next Friday" the first one strictly after; expressions longer than a week ("3 weeks ago") are labeled approximate, because people mean the days around them.

## Notes

* Offsets are limited to ±100 000 units; a bad date or an unknown expression is an error that says what was expected, never a guess.
* The verbs also accept flat arguments (`{"from":"2023-04-01","to":"2023-04-22"}` is a `diff`).
* The memory guidance given to the agent tells it to use `@date` instead of counting days itself; see [Memory](/context/bootstrap-memory).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.