# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1627591861 -7200
# Node ID 256faf6e951f1f75a19852f6e3f7796eba30b414
# Parent  6d03e8ebf1a6fe5ac0d670048eb92a26821da56b
doc (cli/common): time pattern

diff -r 6d03e8ebf1a6 -r 256faf6e951f doc/libervia-cli/common_arguments.rst
--- a/doc/libervia-cli/common_arguments.rst	Thu Jul 29 22:51:01 2021 +0200
+++ b/doc/libervia-cli/common_arguments.rst	Thu Jul 29 22:51:01 2021 +0200
@@ -217,3 +217,61 @@
   e.g. specifying a template to use::
 
     $ li blog get -O template --oo browser --oo template=/tmp/my_template.html
+
+Time Pattern
+============
+
+When a command expect a date or date with time argument, you can use a "time pattern" (you
+usually see the ``TIME_PATTERN`` as name of the argument in ``--help`` message when it can
+be used).
+
+This is a flexible way to enter a date, you can enter a date in one of the following way:
+
+- the string ``now`` to indicate current date and time;
+- an absolute date using an international format. The parser know many formats (please
+  check dateutil_ package documentation to have a detail of supported formats). Please
+  note that days are specified first and that if no time zone is specified, the local
+  time zone of your computer is assumed;
+- a relative date (or "relative delta"), see below for details on how to construct it;
+- a reference time (``now`` or absolute date as above) followed by a relative delta. If
+  the reference time is not specified, ``now`` is used;
+
+Time pattern is not case sensitive.
+
+.. _dateutil: https://dateutil.readthedocs.io
+
+Relative Delta
+--------------
+
+A relative delta is specified with:
+
+- an optional direction ``+`` for times after reference time or ``-`` for time before reference time (defaulting to ``+``);
+- a number for the quantity of units
+- a unit (e.g. seconds or minutes), see the bellow for details
+- the word ``ago`` which is same as using ``-`` for direction (direction and ``ago`` can't
+  be used at the same time)
+
+Time Units
+----------
+
+The singular or plural form of following units can be used:
+
+- ``s``, ``sec``, ``second``
+- ``m``, ``min``, ``minute``
+- ``h``, ``hr``, ``hour``
+- ``d``, ``day``
+- ``w``, ``week``
+- ``mo``, ``month``
+- ``y``, ``yr``, ``year``
+
+examples
+--------
+
+- ``2022-01-01``: first of January of 2022 at midnight
+- ``2017-02-10T13:05:00Z``: 10th of February 2017 at 13:05 UTC
+- ``2019-07-14 12:00:00 CET``: 14th of July 2019 at 12:00 CET
+- ``10 min ago``: current time minus 10 minutes
+- ``now - 10 m``: same as above (current time minus 10 minutes)
+- ``07/08/2021 +5 hours``: 7 August 2021 at midnight (local time of the computer) + 5
+  hours, i.e. 5 in the morning at local time.
+