--- a/src/source/scripts.rst	Thu Apr 12 18:01:15 2018 +0200
+++ b/src/source/scripts.rst	Fri Apr 20 16:52:49 2018 +0200
@@ -3,3 +3,42 @@
 PyAMS maintenance scripts
 =========================
 
+
+pyams_upgrade
+-------------
+
+
+Pyramid allows to define custom command line scripts for application management. A script called *pyams_upgrade* is
+provided by PyAMS_utils package; this script apply the same process as PyAMS site factory, but can also be used to
+manage **database generations**. The idea behind this is just to allow custom packages to provide a way to check and
+upgrade database configuration away from application startup process:
+
+.. code-block:: bash
+
+    # ./bin/pyams_upgrade webapp/development.ini
+
+
+A **site generation checker** is just a named utility providing :py:class:`pyams_utils.interfaces.site.ISiteGenerations`
+interface. For example, **pyams_security** package provides such utility, to make sure that local site manager
+contains a PyAMS security manager and a principal annotation utility:
+
+.. code-block:: python
+
+    from pyams_utils.site import check_required_utilities
+
+    REQUIRED_UTILITIES = ((ISecurityManager, '', SecurityManager, 'Security manager'),
+                          (IPrincipalAnnotationUtility, '', PrincipalAnnotationUtility, 'User profiles'))
+
+    @utility_config(name='PyAMS security', provides=ISiteGenerations)
+    class SecurityGenerationsChecker(object):
+    """I18n generations checker"""
+
+        generation = 1
+
+        def evolve(self, site, current=None):
+            """Check for required utilities"""
+            check_required_utilities(site, REQUIRED_UTILITIES)
+
+:py:func:`check_required_utilities <pyams_utils.site.check_required_utilities>` is a PyAMS_utils utility function which
+can to used to verify that a set of local utilities are correctly registered with the given names and interfaces.
+