diff --git a/doc/source/cloner.rst b/doc/source/cloner.rst
new file mode 100644
index 0000000..bb33f82
--- /dev/null
+++ b/doc/source/cloner.rst
@@ -0,0 +1,77 @@
+:title: Zuul Cloner
+
+Zuul Cloner
+===========
+
+Zuul includes a simple command line client that may be used to clone
+repositories with Zuul references applied.
+
+Configuration
+-------------
+
+Clone map
+'''''''''
+
+By default, Zuul cloner will clone the project under ``basepath`` which
+would create sub directories whenever a project name contains slashes.  Since
+you might want to finely tweak the final destination, a clone map lets you
+change the destination on a per project basis.  The configuration is done using
+a YAML file passed with ``-m``.
+
+With a project hierarchy such as::
+
+ project
+ thirdparty/plugins/plugin1
+
+You might want to get ``project`` straight in the base path, the clone map would be::
+
+  clonemap:
+   - name: 'project'
+     dest: '.'
+
+Then to strip out ``thirdparty`` such that the plugins land under the
+``/plugins`` directory of the basepath, you can use regex and capturing
+groups::
+
+  clonemap:
+   - name: 'project'
+     dest: '.'
+   - name: 'thirdparty/(plugins/.*)'
+     dest: '\1'
+
+The resulting workspace will contains::
+
+  project -> ./
+  thirdparty/plugins/plugin1  -> ./plugins/plugin1
+
+
+Zuul parameters
+'''''''''''''''
+
+The Zuul cloner reuses Zuul parameters such as ZUUL_BRANCH, ZUUL_REF or
+ZUUL_PROJECT.  It will attempt to load them from the environment variables or
+you can pass them as parameters (in which case it will override the
+environment variable if it is set).  The matching command line parameters use
+the ``zuul`` prefix hence ZUUL_REF can be passed to the cloner using
+``--zuul-ref``.
+
+Usage
+-----
+The general options that apply are:
+
+.. program-output:: zuul-cloner --help
+
+Clone order
+-----------
+
+When cloning repositories, the destination folder should not exist or
+``git clone`` will complain. This happens whenever cloning a sub project
+before its parent project. For example::
+
+ zuul-cloner project/plugins/plugin1 project
+
+Will create the directory ``project`` when cloning the plugin. The
+cloner processes the clones in the order supplied, so you should swap the
+projects::
+
+  zuul-cloner project project/plugins/plugin1
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fcc0d45..abe8089 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -20,6 +20,7 @@
    reporters
    zuul
    client
+   cloner
    statsd
 
 Indices and tables