gitlab CLI usage

python-gitlab provides a gitlab command-line tool to interact with GitLab servers. It uses a configuration file to define how to connect to the servers.



gitlab looks up 3 configuration files by default:

PYTHON_GITLAB_CFG environment variable
An environment variable that contains the path to a configuration file
System-wide configuration file
User configuration file

You can use a different configuration file with the --config-file option.


The configuration file uses the INI format. It contains at least a [global] section, and a specific section for each GitLab server. For example:

default = somewhere
ssl_verify = true
timeout = 5

url =
private_token = vTbFeqJYCY3sibBP7BZM
api_version = 4

url =
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.

Global options
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.


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.

GitLab server options
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


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:

$ gitlab project list

Use the --help option to list the available object types and actions:

$ gitlab --help
$ gitlab project --help

Some actions require additional parameters. Use the --help option to list mandatory and optional arguments for an action:

$ 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.


The PyYAML package 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.


$ gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list


List the projects (paginated):

$ gitlab project list

List all the projects:

$ gitlab project list --all

Limit to 5 items per request, display the 1st page only

$ gitlab project list --page 1 --per-page 5

Get a specific project (id 2):

$ gitlab project get --id 2

Get a specific user by id:

$ gitlab user get --id 3

Create a deploy token for a project:

$ 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:

$ gitlab -v group-deploy-token list --group-id 3

Get a list of snippets for this project:

$ gitlab project-issue list --project-id 2

Delete a snippet (id 3):

$ gitlab project-snippet delete --id 3 --project-id 2

Update a snippet:

$ gitlab project-snippet update --id 4 --project-id 2 \
    --code "My New Code"

Create a snippet:

$ 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:

$ gitlab project-commit get --project-id 2 --id a43290c

Get the signature (e.g. GPG or x509) of a signed commit:

$ 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):

$ 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):

$ gitlab project create --name user_project1 --sudo username

List values are comma-separated:

$ 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:

$ cat > /tmp/description << EOF
This is the description of my project.

It is obviously the best project around
$ 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”:

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.


eval "$(register-python-argcomplete gitlab)"


eval `register-python-argcomplete --shell tcsh gitlab`


register-python-argcomplete --shell fish gitlab | .



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:

autoload -U bashcompinit

Afterwards you can enable completion for gitlab:

eval "$(register-python-argcomplete gitlab)"