/usr/share/doc/python-gitlab/html/cli.html is in python-gitlab-doc 1:1.3.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>gitlab CLI usage — python-gitlab 1.3.0 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.3.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Getting started with the API" href="api-usage.html" />
<link rel="prev" title="Installation" href="install.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="api-usage.html" title="Getting started with the API"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="install.html" title="Installation"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">python-gitlab 1.3.0 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="gitlab-cli-usage">
<h1><code class="docutils literal"><span class="pre">gitlab</span></code> CLI usage<a class="headerlink" href="#gitlab-cli-usage" title="Permalink to this headline">¶</a></h1>
<p><code class="docutils literal"><span class="pre">python-gitlab</span></code> provides a <strong class="command">gitlab</strong> command-line tool to interact
with GitLab servers. It uses a configuration file to define how to connect to
the servers.</p>
<div class="section" id="configuration">
<span id="cli-configuration"></span><h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2>
<div class="section" id="files">
<h3>Files<a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">gitlab</span></code> looks up 2 configuration files by default:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">/etc/python-gitlab.cfg</span></code></dt>
<dd>System-wide configuration file</dd>
<dt><code class="docutils literal"><span class="pre">~/.python-gitlab.cfg</span></code></dt>
<dd>User configuration file</dd>
</dl>
<p>You can use a different configuration file with the <code class="docutils literal"><span class="pre">--config-file</span></code> option.</p>
</div>
<div class="section" id="content">
<h3>Content<a class="headerlink" href="#content" title="Permalink to this headline">¶</a></h3>
<p>The configuration file uses the <code class="docutils literal"><span class="pre">INI</span></code> format. It contains at least a
<code class="docutils literal"><span class="pre">[global]</span></code> section, and a specific section for each GitLab server. For
example:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[global]</span>
<span class="na">default</span> <span class="o">=</span> <span class="s">somewhere</span>
<span class="na">ssl_verify</span> <span class="o">=</span> <span class="s">true</span>
<span class="na">timeout</span> <span class="o">=</span> <span class="s">5</span>
<span class="k">[somewhere]</span>
<span class="na">url</span> <span class="o">=</span> <span class="s">https://some.whe.re</span>
<span class="na">private_token</span> <span class="o">=</span> <span class="s">vTbFeqJYCY3sibBP7BZM</span>
<span class="na">api_version</span> <span class="o">=</span> <span class="s">3</span>
<span class="k">[elsewhere]</span>
<span class="na">url</span> <span class="o">=</span> <span class="s">http://else.whe.re:8080</span>
<span class="na">private_token</span> <span class="o">=</span> <span class="s">CkqsjqcQSFH5FQKDccu4</span>
<span class="na">timeout</span> <span class="o">=</span> <span class="s">1</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">default</span></code> option of the <code class="docutils literal"><span class="pre">[global]</span></code> section defines the GitLab server to
use if no server is explicitly specified with the <code class="docutils literal"><span class="pre">--gitlab</span></code> CLI option.</p>
<p>The <code class="docutils literal"><span class="pre">[global]</span></code> section also defines the values for the default connection
parameters. You can override the values in each GitLab server section.</p>
<table border="1" class="docutils" id="id2">
<caption><span class="caption-text">Global options</span><a class="headerlink" href="#id2" title="Permalink to this table">¶</a></caption>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Option</th>
<th class="head">Possible values</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">ssl_verify</span></code></td>
<td><code class="docutils literal"><span class="pre">True</span></code>, <code class="docutils literal"><span class="pre">False</span></code>, or a <code class="docutils literal"><span class="pre">str</span></code></td>
<td>Verify the SSL certificate. Set to <code class="docutils literal"><span class="pre">False</span></code> 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.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">timeout</span></code></td>
<td>Integer</td>
<td>Number of seconds to wait for an answer before failing.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">api_version</span></code></td>
<td><code class="docutils literal"><span class="pre">3</span></code> ou <code class="docutils literal"><span class="pre">4</span></code></td>
<td>The API version to use to make queries. Requires python-gitlab >= 1.3.0.</td>
</tr>
</tbody>
</table>
<p>You must define the <code class="docutils literal"><span class="pre">url</span></code> in each GitLab server section.</p>
<p>Only one of <code class="docutils literal"><span class="pre">private_token</span></code> or <code class="docutils literal"><span class="pre">oauth_token</span></code> should be defined. If neither
are defined an anonymous request will be sent to the Gitlab server, with very
limited permissions.</p>
<table border="1" class="docutils" id="id3">
<caption><span class="caption-text">GitLab server options</span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Option</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">url</span></code></td>
<td>URL for the GitLab server</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">private_token</span></code></td>
<td>Your user token. Login/password is not supported. Refer to <a class="reference external" href="https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html">the official
documentation</a> to learn how to obtain a token.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">oauth_token</span></code></td>
<td>An Oauth token for authentication. The Gitlab server must be configured
to support this authentication method.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">api_version</span></code></td>
<td>GitLab API version to use (<code class="docutils literal"><span class="pre">3</span></code> or <code class="docutils literal"><span class="pre">4</span></code>). Defaults to <code class="docutils literal"><span class="pre">4</span></code> since
version 1.3.0.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">http_username</span></code></td>
<td>Username for optional HTTP authentication</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">http_password</span></code></td>
<td>Password for optional HTTP authentication</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="cli">
<h2>CLI<a class="headerlink" href="#cli" title="Permalink to this headline">¶</a></h2>
<div class="section" id="objects-and-actions">
<h3>Objects and actions<a class="headerlink" href="#objects-and-actions" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal"><span class="pre">gitlab</span></code> 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:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project list
</pre></div>
</div>
<p>Use the <code class="docutils literal"><span class="pre">--help</span></code> option to list the available object types and actions:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab --help
<span class="gp">$</span> gitlab project --help
</pre></div>
</div>
<p>Some actions require additional parameters. Use the <code class="docutils literal"><span class="pre">--help</span></code> option to
list mandatory and optional arguments for an action:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project create --help
</pre></div>
</div>
</div>
<div class="section" id="optional-arguments">
<h3>Optional arguments<a class="headerlink" href="#optional-arguments" title="Permalink to this headline">¶</a></h3>
<p>Use the following optional arguments to change the behavior of <code class="docutils literal"><span class="pre">gitlab</span></code>.
These options must be defined before the mandatory arguments.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--verbose</span></code>, <code class="docutils literal"><span class="pre">-v</span></code></dt>
<dd>Outputs detail about retrieved objects. Available for legacy (default)
output only.</dd>
<dt><code class="docutils literal"><span class="pre">--config-file</span></code>, <code class="docutils literal"><span class="pre">-c</span></code></dt>
<dd>Path to a configuration file.</dd>
<dt><code class="docutils literal"><span class="pre">--gitlab</span></code>, <code class="docutils literal"><span class="pre">-g</span></code></dt>
<dd>ID of a GitLab server defined in the configuration file.</dd>
<dt><code class="docutils literal"><span class="pre">--output</span></code>, <code class="docutils literal"><span class="pre">-o</span></code></dt>
<dd>Output format. Defaults to a custom format. Can also be <code class="docutils literal"><span class="pre">yaml</span></code> or <code class="docutils literal"><span class="pre">json</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">--fields</span></code>, <code class="docutils literal"><span class="pre">-f</span></code></dt>
<dd>Comma-separated list of fields to display (<code class="docutils literal"><span class="pre">yaml</span></code> and <code class="docutils literal"><span class="pre">json</span></code> output
formats only). If not used, all the object fields are displayed.</dd>
</dl>
<p>Example:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab -o yaml -f id,permissions -g elsewhere -c /tmp/gl.cfg project list
</pre></div>
</div>
</div>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>List the projects (paginated):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project list
</pre></div>
</div>
<p>List all the projects:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project list --all
</pre></div>
</div>
<p>Limit to 5 items per request, display the 1st page only</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project list --page <span class="m">1</span> --per-page <span class="m">5</span>
</pre></div>
</div>
<p>Get a specific project (id 2):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project get --id <span class="m">2</span>
</pre></div>
</div>
<p>Get a specific user by id:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab user get --id <span class="m">3</span>
</pre></div>
</div>
<p>Get a list of snippets for this project:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project-issue list --project-id <span class="m">2</span>
</pre></div>
</div>
<p>Delete a snippet (id 3):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project-snippet delete --id <span class="m">3</span> --project-id <span class="m">2</span>
</pre></div>
</div>
<p>Update a snippet:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project-snippet update --id <span class="m">4</span> --project-id <span class="m">2</span> <span class="se">\</span>
--code <span class="s2">"My New Code"</span>
</pre></div>
</div>
<p>Create a snippet:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project-snippet create --project-id <span class="m">2</span>
<span class="go">Impossible to create object (Missing attribute(s): title, file-name, code)</span>
<span class="gp">$</span> <span class="c1"># oops, let's add the attributes:</span>
<span class="gp">$</span> gitlab project-snippet create --project-id <span class="m">2</span> --title <span class="s2">"the title"</span> <span class="se">\</span>
--file-name <span class="s2">"the name"</span> --code <span class="s2">"the code"</span>
</pre></div>
</div>
<p>Define the status of a commit (as would be done from a CI tool for example):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project-commit-status create --project-id <span class="m">2</span> <span class="se">\</span>
--commit-id a43290c --state success --name ci/jenkins <span class="se">\</span>
--target-url http://server/build/123 <span class="se">\</span>
--description <span class="s2">"Jenkins build succeeded"</span>
</pre></div>
</div>
<p>Use sudo to act as another user (admin only):</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> gitlab project create --name user_project1 --sudo username
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="docutils literal"><span class="pre">gitlab</span></code> CLI usage</a><ul>
<li><a class="reference internal" href="#configuration">Configuration</a><ul>
<li><a class="reference internal" href="#files">Files</a></li>
<li><a class="reference internal" href="#content">Content</a></li>
</ul>
</li>
<li><a class="reference internal" href="#cli">CLI</a><ul>
<li><a class="reference internal" href="#objects-and-actions">Objects and actions</a></li>
<li><a class="reference internal" href="#optional-arguments">Optional arguments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="install.html"
title="previous chapter">Installation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="api-usage.html"
title="next chapter">Getting started with the API</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/cli.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="api-usage.html" title="Getting started with the API"
>next</a> |</li>
<li class="right" >
<a href="install.html" title="Installation"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">python-gitlab 1.3.0 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2013-2018, Gauvain Pocentek, Mika Mäenpää.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|