diff --git a/docs/user-manual.rst b/docs/user-manual.rst
--- a/docs/user-manual.rst
+++ b/docs/user-manual.rst
@@ -394,7 +394,22 @@
 Update deposit
 --------------
 
-* replace deposit:
+* Update deposit metadata:
+
+  - only possible if the deposit status is ``done``, ``--deposit-id <id>`` and ``--swhid
+    <swhid>`` are provided.
+
+  - by using the ``--metadata`` flag, a path to an xml file
+
+.. code:: console
+
+    $ swh deposit upload \
+      --username name --password secret \
+      --deposit-id 11 \
+      --swhid swh:1:dir:2ddb1f0122c57c8479c28ba2fc973d18508e6420 \
+      --metadata ../deposit-swh.update-metadata.xml
+
+* Replace deposit:
 
   - only possible if the deposit status is ``partial`` and
     ``--deposit-id <id>`` is provided