docs(cli): add auto-generated CLI referencedocs/cli-reference-page

1 files changed, 399 insertions, 0 deletions

diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst
new file mode 100644
index 0000000..10fd73a
--- /dev/null
+++ b/docs/cli-usage.rst
@@ -0,0 +1,399 @@
+####################
+``gitlab`` CLI usage
+####################
+
+``python-gitlab`` provides a :command:`gitlab` command-line tool to interact
+with GitLab servers. It uses a configuration file to define how to connect to
+the servers.
+
+.. _cli_configuration:
+
+Configuration
+=============
+
+Files
+-----
+
+``gitlab`` looks up 3 configuration files by default:
+
+``PYTHON_GITLAB_CFG`` environment variable
+    An environment variable that contains the path to a configuration file
+
+``/etc/python-gitlab.cfg``
+    System-wide configuration file
+
+``~/.python-gitlab.cfg``
+    User configuration file
+
+You can use a different configuration file with the ``--config-file`` option.
+
+Content
+-------
+
+The configuration file uses the ``INI`` format. It contains at least a
+``[global]`` section, and a specific section for each GitLab server. For
+example:
+
+.. code-block:: ini
+
+   [global]
+   default = somewhere
+   ssl_verify = true
+   timeout = 5
+
+   [somewhere]
+   url = https://some.whe.re
+   private_token = vTbFeqJYCY3sibBP7BZM
+   api_version = 4
+
+   [elsewhere]
+   url = http://else.whe.re:8080
+   private_token = CkqsjqcQSFH5FQKDccu4
+   timeout = 1
+
+The ``default`` option of the ``[global]`` section defines the GitLab server to
+use if no server is explicitly specified with the ``--gitlab`` CLI option.
+
+The ``[global]`` section also defines the values for the default connection
+parameters. You can override the values in each GitLab server section.
+
+.. list-table:: Global options
+   :header-rows: 1
+
+   * - Option
+     - Possible values
+     - Description
+   * - ``ssl_verify``
+     - ``True``, ``False``, or a ``str``
+     - Verify the SSL certificate. Set to ``False`` to disable verification,
+       though this will create warnings. Any other value is interpreted as path
+       to a CA_BUNDLE file or directory with certificates of trusted CAs.
+   * - ``timeout``
+     - Integer
+     - Number of seconds to wait for an answer before failing.
+   * - ``api_version``
+     - ``4``
+     - The API version to use to make queries. Only ``4`` is available since 1.5.0.
+   * - ``per_page``
+     - Integer between 1 and 100
+     - The number of items to return in listing queries. GitLab limits the
+       value at 100.
+
+You must define the ``url`` in each GitLab server section.
+
+.. warning::
+
+   If the GitLab server you are using redirects requests from http to https,
+   make sure to use the ``https://`` protocol in the ``url`` definition.
+
+Only one of ``private_token``, ``oauth_token`` or ``job_token`` should be
+defined. If neither are defined an anonymous request will be sent to the Gitlab
+server, with very limited permissions.
+
+.. list-table:: GitLab server options
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - ``url``
+     - URL for the GitLab server
+   * - ``private_token``
+     - Your user token. Login/password is not supported. Refer to `the official
+       documentation`_pat to learn how to obtain a token.
+   * - ``oauth_token``
+     - An Oauth token for authentication. The Gitlab server must be configured
+       to support this authentication method.
+   * - ``job_token``
+     - Your job token. See `the official  documentation`_job-token to learn how to obtain a token.
+   * - ``api_version``
+     - GitLab API version to use. Only ``4`` is available since 1.5.0.
+   * - ``http_username``
+     - Username for optional HTTP authentication
+   * - ``http_password``
+     - Password for optional HTTP authentication
+
+.. _pat: https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html
+.. _job-token: https://docs.gitlab.com/ce/api/jobs.html#get-job-artifacts
+
+CLI
+===
+
+Objects and actions
+-------------------
+
+The ``gitlab`` command expects two mandatory arguments. The first one is the
+type of object that you want to manipulate. The second is the action that you
+want to perform. For example:
+
+.. code-block:: console
+
+   $ gitlab project list
+
+Use the ``--help`` option to list the available object types and actions:
+
+.. code-block:: console
+
+   $ gitlab --help
+   $ gitlab project --help
+
+Some actions require additional parameters. Use the ``--help`` option to
+list mandatory and optional arguments for an action:
+
+.. code-block:: console
+
+   $ gitlab project create --help
+
+Optional arguments
+------------------
+
+Use the following optional arguments to change the behavior of ``gitlab``.
+These options must be defined before the mandatory arguments.
+
+``--verbose``, ``-v``
+    Outputs detail about retrieved objects. Available for legacy (default)
+    output only.
+
+``--config-file``, ``-c``
+    Path to a configuration file.
+
+``--gitlab``, ``-g``
+    ID of a GitLab server defined in the configuration file.
+
+``--output``, ``-o``
+    Output format. Defaults to a custom format. Can also be ``yaml`` or ``json``.
+
+    **Notice:**
+
+        The `PyYAML package <https://pypi.org/project/PyYAML/>`_ is required to use the yaml output option.
+        You need to install it explicitly using ``pip install python-gitlab[yaml]``
+
+``--fields``, ``-f``
+    Comma-separated list of fields to display (``yaml`` and ``json`` output
+    formats only).  If not used, all the object fields are displayed.
+
+Example:
+
+.. code-block:: console
+
+   $ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list
+
+Examples
+========
+
+    **Notice:**
+
+        For a complete list of objects and actions available, see :doc:`/cli-objects`.
+
+List the projects (paginated):
+
+.. code-block:: console
+
+   $ gitlab project list
+
+List all the projects:
+
+.. code-block:: console
+
+   $ gitlab project list --all
+
+List all projects of a group:
+
+.. code-block:: console
+
+   $ gitlab group-project list --all --group-id 1
+
+List all projects of a group and its subgroups:
+
+.. code-block:: console
+
+   $ gitlab group-project list --all --include-subgroups true --group-id 1
+
+Limit to 5 items per request, display the 1st page only
+
+.. code-block:: console
+
+   $ gitlab project list --page 1 --per-page 5
+
+Get a specific project (id 2):
+
+.. code-block:: console
+
+   $ gitlab project get --id 2
+
+Get a specific user by id:
+
+.. code-block:: console
+
+   $ gitlab user get --id 3
+
+Create a deploy token for a project:
+
+.. code-block:: console
+
+   $ gitlab -v project-deploy-token create --project-id 2 \
+        --name bar --username root --expires-at "2021-09-09" --scopes "read_repository"
+
+List deploy tokens for a group:
+
+.. code-block:: console
+
+   $ gitlab -v group-deploy-token list --group-id 3
+
+List packages for a project:
+
+.. code-block:: console
+
+   $ gitlab -v project-package list --project-id 3
+
+List packages for a group:
+
+.. code-block:: console
+
+   $ gitlab -v group-package list --group-id 3
+
+Get a specific project package by id:
+
+.. code-block:: console
+
+   $ gitlab -v project-package get --id 1 --project-id 3
+
+Delete a specific project package by id:
+
+.. code-block:: console
+
+   $ gitlab -v project-package delete --id 1 --project-id 3
+
+Get a list of snippets for this project:
+
+.. code-block:: console
+
+   $ gitlab project-issue list --project-id 2
+
+Delete a snippet (id 3):
+
+.. code-block:: console
+
+   $ gitlab project-snippet delete --id 3 --project-id 2
+
+Update a snippet:
+
+.. code-block:: console
+
+   $ gitlab project-snippet update --id 4 --project-id 2 \
+       --code "My New Code"
+
+Create a snippet:
+
+.. code-block:: console
+
+   $ gitlab project-snippet create --project-id 2
+   Impossible to create object (Missing attribute(s): title, file-name, code)
+   $ # oops, let's add the attributes:
+   $ gitlab project-snippet create --project-id 2 --title "the title" \
+       --file-name "the name" --code "the code"
+
+Get a specific project commit by its SHA id:
+
+.. code-block:: console
+
+   $ gitlab project-commit get --project-id 2 --id a43290c
+
+Get the signature (e.g. GPG or x509) of a signed commit:
+
+.. code-block:: console
+
+   $ gitlab project-commit signature --project-id 2 --id a43290c
+
+Define the status of a commit (as would be done from a CI tool for example):
+
+.. code-block:: console
+
+   $ gitlab project-commit-status create --project-id 2 \
+       --commit-id a43290c --state success --name ci/jenkins \
+       --target-url http://server/build/123 \
+       --description "Jenkins build succeeded"
+
+Use sudo to act as another user (admin only):
+
+.. code-block:: console
+
+   $ gitlab project create --name user_project1 --sudo username
+
+List values are comma-separated:
+
+.. code-block:: console
+
+   $ gitlab issue list --labels foo,bar
+
+Reading values from files
+-------------------------
+
+You can make ``gitlab`` read values from files instead of providing them on the
+command line. This is handy for values containing new lines for instance:
+
+.. code-block:: console
+
+   $ cat > /tmp/description << EOF
+   This is the description of my project.
+
+   It is obviously the best project around
+   EOF
+   $ gitlab project create --name SuperProject --description @/tmp/description
+
+Enabling shell autocompletion
+============================
+
+To get autocompletion, you'll need to install the package with the extra
+"autocompletion":
+
+.. code-block:: console
+
+    pip install python_gitlab[autocompletion]
+
+
+Add the appropriate command below to your shell's config file so that it is run on
+startup. You will likely have to restart or re-login for the autocompletion to
+start working.
+
+Bash
+----
+
+.. code-block:: console
+
+   eval "$(register-python-argcomplete gitlab)"
+
+tcsh
+----
+
+.. code-block:: console
+
+   eval `register-python-argcomplete --shell tcsh gitlab`
+
+fish
+----
+
+.. code-block:: console
+
+   register-python-argcomplete --shell fish gitlab | .
+
+Zsh
+---
+
+.. warning::
+
+    Zsh autocompletion support is broken right now in the argcomplete python
+    package. Perhaps it will be fixed in a future release of argcomplete at
+    which point the following instructions will enable autocompletion in zsh.
+
+To activate completions for zsh you need to have bashcompinit enabled in zsh:
+
+.. code-block:: console
+
+   autoload -U bashcompinit
+   bashcompinit
+
+Afterwards you can enable completion for gitlab:
+
+.. code-block:: console
+
+   eval "$(register-python-argcomplete gitlab)"