From 204f6818b77cc3425e9bb137380fcbdfaa5f15df Mon Sep 17 00:00:00 2001
From: Gauvain Pocentek <gauvain@pocentek.net>
Date: Sat, 18 May 2013 17:11:37 +0200
Subject: describe the gitlab script in README

---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index da2cc2f..72a8925 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@ python-gitlab is a Python module providing access to the GitLab server API.
 
 It supports the v3 api of GitLab.
 
+A CLI tool is also provided (called **gitlab**).
+
 ## Requirements
 
 Only Python 2 is supported for the moment.
@@ -18,7 +20,7 @@ python-gitlab is a work in progress, although already usable. Changes in the API
 
 * Improve documentation
 * Write unit tests
-* Write a command line tool to access GitLab servers
+* Improve the command line tool
 
 ## Code snippet
 
@@ -55,3 +57,74 @@ p.save()
 print p
 `````
 
+## Command line use
+
+To use the command line tool, you need to define which GitLab server(s) can be
+accessed. this can be done in 2 files:
+
+* /etc/python-gitlab.cfg
+* ~/.python-gitlab.cfg
+
+Here's an example of the syntax:
+
+`````
+[global]
+default = local
+
+[local]
+url = http://10.0.3.2:8080
+private_token = vTbFeqJYCY3sibBP7BZM
+
+[distant]
+url = https://some.whe.re
+private_token = thisisaprivatetoken
+`````
+
+The [global] section define which server is accesed by default.
+Each other section defines how to access a server. Only private token
+authentication is supported (not user/password).
+
+Choosing a different server than the default one can be done at run time:
+
+`````
+gitlab --gitlab=distant [command]
+`````
+
+gitlab always requires 2 mandatory arguments.
+
+The first argument is the object type on which we will act, the second one is
+the action:
+
+`````
+gitlab Project list
+`````
+
+The usable objects are those which inherits GitlabObject (yes, the source is
+the doc ATM), and the actions are list, get, create, update, delete.
+
+Some examples:
+
+`````bash
+# list all the projects:
+gitlab Project list
+
+# get a specific project (id 2):
+gitlab Project get 2
+
+# get a list of snippets for this project:
+gitlab ProjectIssue list project_id=2
+# (you're right, this syntax sucks)
+
+# delete a Snippet (id 3):
+gitlab ProjectSnippet delete 3 project_id=2
+
+# update a Snippet:
+gitlab ProjectSnippet update 4 project_id=2 code="My New Code"
+
+# create a Snippet:
+gitlab ProjectSnippet create project_id=2
+Impossible to create object (Missing attribute(s): title, file_name, code)
+
+# oops, let's add the attributes:
+gitlab ProjectSnippet create project_id=2 title="the title" file_name="the name" code="the code"
+`````
-- 
cgit v1.2.1