diff --git a/doc/source/man/keystone.rst b/doc/source/man/keystone.rst
index 506fc2b83..10d9d93cb 100644
--- a/doc/source/man/keystone.rst
+++ b/doc/source/man/keystone.rst
@@ -1,6 +1,6 @@
-========================================
-:program:`keystone` command line utility
-========================================
+==============================================================
+:program:`keystone` command line utility (pending deprecation)
+==============================================================
 
 .. program:: keystone
 .. highlight:: bash
@@ -18,6 +18,14 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
+.. WARNING::
+
+    The :program:`keystone` command line utility is pending deprecation. The
+    `OpenStackClient unified command line utility
+    <http://docs.openstack.org/developer/python-openstackclient/>`_ should be
+    used instead. The :program:`keystone` command line utility only supports V2
+    of the Identity API whereas the OSC program supports both V2 and V3.
+
 The :program:`keystone` command line utility interacts with services providing
 OpenStack Identity API (e.g. Keystone).