commit 76769d2f941b929e27012c68e58eceb94af6da88
Author: Stavros Sachtouris <saxtouri@admin.grnet.gr>
Date:   Thu Dec 5 15:31:59 2013 +0200

    Update docs up to usage
    
    Refs: #4692

diff --git a/docs/commands.rst b/docs/commands.rst
index 65334c4..9576561 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -321,7 +321,7 @@ Showcase: Reserve and attach IP to server
 .. Note:: In kamaki shell, / is used to access top-level command groups while
     working in command group contexts
 
-network (Compute/Cyclades)
+network (Network/Cyclades)
 --------------------------
 
 .. code-block:: text
@@ -404,6 +404,8 @@ Showcase: Connect a network to a VM
 container (Storage/Pithos+)
 ---------------------------
 
+.. code-block:: text
+
     info      Get information about a container
     modify    Modify the properties of a container
     create    Create a new container
@@ -414,6 +416,8 @@ container (Storage/Pithos+)
 group (Storage/Pithos+)
 -----------------------
 
+.. code-block:: text
+
     create    Create a group of users
     list      List all groups and group members
     delete    Delete a user group
@@ -421,6 +425,8 @@ group (Storage/Pithos+)
 sharer (Storage/Pithos+)
 ------------------------
 
+.. code-block:: text
+
     info      Details on a Pithos+ sharer account (default: current account)
     list      List accounts who share file objects with current user
 
diff --git a/docs/setup.rst b/docs/setup.rst
index b69fd99..f818689 100644
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -552,8 +552,8 @@ or a specific method from a service (e.g., create_server @ cyclades)::
     $ kamaki livetest cyclades create_server
 
 
-The unit tests
-""""""""""""""
+Unit tests
+""""""""""
 
 Kamaki features a set of unit tests for the kamaki.clients package. This set is
 not used when kamaki is running. Instead, it is aimed to developers who debug
diff --git a/docs/usage.rst b/docs/usage.rst
index 7d852cf..c224dda 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,68 +1,87 @@
 Usage
 =====
 
-Kamaki offers command-line interfaces that implement specific command
-specifications. A detailed list of the command specifications can be found in
-`Commands <commands.html>`_ section. This guide covers the generic usage of
-both interfaces.
+Kamaki features commands of the form::
 
-What's more, kamaki offers a clients library for the development of external
-client applications for Synnefo. The clients library API is detailed in the
-`Clients lib <developers/code.html#the-clients-api>`_ section.
+  [kamaki] <object> <action> [identifier(s)] <non-positional arguments>
+  e.g., 
+  kamaki user info --username=user@example.com
+
+A detailed list of the command specifications can be found in
+`Commands <commands.html>`_ section.
+
+All commands can run either from the host shell or through the kamaki
+interactive shell:
+
+.. code-block:: console
+
+  #  Run from host shell
+  $ kamaki user info
+  ... RESULTS ...
+
+  #  Run from kamaki interactive shell
+  $ kamaki-shell
+  [kamaki]: user info
+  ... RESULTS ...
+
+In the later, the term "one-command" will be user to refer to running kamaki
+commands from host shell, while the term "shell" will refer to the kamaki's own
+interactive shell
+
+.. note:: This section refers to the kamaki CLI. Developers and people who write
+  scripts, should rather use the the
+  `Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki
+  CLI.
 
 Quick Setup
 -----------
 
-Kamaki interfaces rely on a list of configuration options. A detailed guide for
-setting up kamaki can be found in the `Setup <setup.html>`_ section.
+Kamaki interfaces rely on a list of configuration options. Check the
+`Setup <setup.html>`_ guide for a full list.
 
-As rule of the thump, it is enough to set the authentication URL and user token
-for the cloud kamaki should communicate with by default:
+As rule of the thump, it is enough to set a cloud authentication URL and TOKEN:
 
 .. code-block:: console
     :emphasize-lines: 1
 
-    Example 1.1: Set authentication URL, user token and cloud alias "default"
+    Example 1.1: Set authentication URL, user token for cloud alias "default"
 
     $ kamaki config set cloud.default.url <authentication URL>
     $ kamaki config set cloud.default.token myt0k3n==
 
 .. note:: The term *default* can be replaced by any arbitary term chosen by
-    the user. This term will serve as a cloud alias for kamaki users, and can
-    be easily modified.
+    the user.
 
 Shell vs one-command
 --------------------
-Kamaki users can access Synnefo services through either the interactive shell
-or the one-command interface. In practice, both systems rely on the same
-command set implementations and API clients, with identical responses and error
-messages. Still, there are some differences.
+
+Kamaki users can access Synnefo services through either the kamaki shell or the
+one-command interface. Both systems feature identical responses and error
+messages, since they rely on the same internal command and library API
+implementation. However, there are some minor differences.
 
 In favor of interactive shell:
 
-* tab completion for commands (if supported by the user shell)
-* session history with ↑ or ↓ keys (if supported by the user shell)
-* shorter commands with command context switching
+* shorter commands (context switching)
+* tab completion for commands (if supported by host shell)
+* kamaki-specific history with ↑ or ↓ keys (if supported by host shell)
 * re-run old commands with /history
 
 In favor of one-command:
 
-* can be used along with advanced shell features (pipelines, redirection, etc.)
+* users take advantage of host shell features (pipelines, redirection, etc.)
 * can be used in shell scripts
-* prints debug and verbose messages if needed
 
 Run as shell
 ^^^^^^^^^^^^
 To use kamaki as a shell, run:
 
-* without any parameters or arguments
-
 .. code-block:: console
     :emphasize-lines: 1
 
     Example 2.2.1: Run kamaki shell
 
-    $ kamaki
+    $ kamaki-shell
 
 * with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
     '- - version'.
@@ -72,8 +91,20 @@ To use kamaki as a shell, run:
 
     Example 2.2.2: Run kamaki shell with custom configuration file
 
-    $ kamaki -c myconfig.file
+    $ kamaki-shell -c myconfig.file
+
+    Example 2.2.3: Run kamaki shell so as to use a specific cloud
+
+    $ kamaki-shell --cloud=my_demo_cloud
+
+    Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests)
+
+    $ kamaki-shell -v
 
+.. note:: Valid arguments can be combined e.g., it is ok to run a shell with
+  verbosity and a specific cloud::
+
+    $ kamaki-shell -v --cloud=my_demo_cloud
 
 Run as one-command
 ^^^^^^^^^^^^^^^^^^
@@ -88,7 +119,7 @@ To use kamaki as an one-command tool, run:
 
     $kamaki -h
 
-* with one or more command parameters:
+* with one or more command parameters (object and, maybe, action):
 
 .. code-block:: console
     :emphasize-lines: 1
@@ -103,10 +134,9 @@ One-command interface
 Using help
 ^^^^^^^^^^
 
-Kamaki help provides information on available commands (description, syntax and
-corresponding optional arguments).
+Kamaki help provides information on commands (description, syntax).
 
-To see the command groups, use -h or --help (example 1.3.1). The
+To see the command groups (objects), use -h or --help (example 1.3.1). The
 following examples demonstrate the help messages of kamaki, in the context of a
 command group (server) and of a command in that group (list).
 
@@ -118,14 +148,13 @@ command group (server) and of a command in that group (list).
 
     $ kamaki -h
     usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
-        [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
+        [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
 
     optional arguments:
       -v, --verbose         More info at response
       -s, --silent          Do not output anything
       -V, --version         Print current version
       -d, --debug           Include debug output
-      -i, --include         Include protocol headers in the output
       -c CONFIG, --config CONFIG
                             Path to configuration file
       -o OPTIONS, --options OPTIONS
@@ -135,18 +164,25 @@ command group (server) and of a command in that group (list).
 
     Options:
      - - - -
-    network: Cyclades/Compute API network commands
-    user: Astakos API commands
-    livetest: Client func. tests on live servers
-    server: Cyclades/Compute API server commands
-    project: Synnefo project management CLI
-    file: Pithos+/Storage API commands
+    resource: Astakos/Account API commands for resources
+    group: Pithos+/Storage user groups
+    network: Networking API network commands
+    subnet: Networking API network commands
+    ip: Networking API floatingip commands
+    image: Cyclades/Plankton API image commands
+    imagecompute: Cyclades/Compute API image commands
+    quota: Astakos/Account API commands for quotas
+    sharer: Pithos+/Storage sharers
+    project: Astakos project API commands
+    user: Astakos/Identity API commands
+    file: Pithos+/Storage object level API commands
+    container: Pithos+/Storage container level API commands
     flavor: Cyclades/Compute API flavor commands
+    server: Cyclades/Compute API server commands
     config: Kamaki configurations
-    image: Cyclades/Plankton API image commands
-    image compute:  Cyclades/Compute API image commands
+    port: Networking API network commands
     history: Kamaki command history
-
+    kamaki-shell: An interactive command line shell
 
 .. code-block:: console
     :emphasize-lines: 1,2
@@ -155,7 +191,7 @@ command group (server) and of a command in that group (list).
     command group
 
     $ kamaki server -h
-    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [-c CONFIG]
+    usage: kamaki server <...> [-v] [-s] [-V] [-d] [-c CONFIG]
                                [-o OPTIONS] [--cloud CLOUD] [-h]
 
     optional arguments:
@@ -163,7 +199,6 @@ command group (server) and of a command in that group (list).
       -s, --silent          Do not output anything
       -V, --version         Print current version
       -d, --debug           Include debug output
-      -i, --include         Include protocol headers in the output
       -c CONFIG, --config CONFIG
                             Path to configuration file
       -o OPTIONS, --options OPTIONS
@@ -174,20 +209,13 @@ command group (server) and of a command in that group (list).
     Options:
      - - - -
     info: Detailed information on a Virtual Machine
-    rename: Set/update a virtual server name
-    delete: Delete a virtual server
-    console: Get a VNC console to access an existing virtual server
-    addr: List the addresses of all network interfaces on a virtual server
-    firewall: Manage virtual server firewall profiles for public networks
+    modify: Modify attributes of a virtual server
     create: Create a server (aka Virtual Machine)
-    list: List Virtual Machines accessible by user
+    list: List virtual servers accessible by user
     reboot: Reboot a virtual server
     start: Start an existing virtual server
     shutdown: Shutdown an active virtual server
-    stats: Get virtual server statistics
-    metadata: Manage Server metadata (key:value pairs of server attributes)
-    resize: Set a different flavor for an existing server
-    wait: Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
+    delete: Delete a virtual server
 
 .. code-block:: console
     :emphasize-lines: 1,2
@@ -196,7 +224,7 @@ command group (server) and of a command in that group (list).
     available user options
 
     $ kamaki server list -h
-    usage: kamaki server list [-v] [-s] [-V] [-d] [-i] [-c CONFIG] [-o OPTIONS]
+    usage: kamaki server list [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS]
                               [--cloud CLOUD] [-h] [--since SINCE] [--enumerate]
                               [-l] [--more] [-n LIMIT] [-j]
 
@@ -207,7 +235,6 @@ command group (server) and of a command in that group (list).
       -s, --silent          Do not output anything
       -V, --version         Print current version
       -d, --debug           Include debug output
-      -i, --include         Include raw connection data in the output
       -c CONFIG, --config CONFIG
                             Path to config file
       -o OPTIONS, --options OPTIONS
@@ -254,7 +281,9 @@ command group (server) and of a command in that group (list).
 Using history
 ^^^^^^^^^^^^^
 
-Kamaki command history is stored in a file at user home (".kamaki.history" by default). To set a custom history file path users must set the history.file config option (see `available config options <setup.html#editing-options>`_).
+Kamaki command history is stored in '${HOME}/.kamaki.history' by default). To
+set a custom history file path users must set the history.file config option
+(more on config options `here <setup.html#editing-options>`_).
 
 Every command is appended at the end of that file. In order to see how to use
 history, use the kamaki help system:
@@ -264,7 +293,6 @@ history, use the kamaki help system:
 
     Example 3.2.1: Available history options
 
-
     $ kamaki history -h
     Options:
      - - - -
@@ -272,13 +300,8 @@ history, use the kamaki help system:
     run  :  Run previously executed command(s)
     show :  Show intersession command history
 
-The following example showcases how to use history in kamaki
-
-.. code-block:: console
-    :emphasize-lines: 1
 
     Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
-    
 
     $ kamaki history clean
     $ kamaki server list
@@ -297,7 +320,8 @@ Debug
 """""
 
 When in debug mode, kamaki outputs some useful debug information (stack trace
-and http logs). Kamaki in debug mode cancels suppression of warning messages.
+and http logs). Kamaki in debug mode cancels the suppression of warning
+messages too.
 
 To run kamaki in debug mode use the -d or --debug option.
 
@@ -306,20 +330,21 @@ Verbose
 """""""
 
 Most kamaki commands are translated into http requests. Kamaki clients API
-translated the semantics to REST and handles the response. Users who need to
-have access to these commands can use the verbose mode that presents the HTTP
-Request details as well as the full server response.
+translates command semantics to REST and handles the response. Users who need
+to have access to these commands can use the verbose mode that outputs the
+HTTP Request and Response details along with the (possibly modified) regular
+command output.
 
-To run kamaki in verbose mode use the *-v/- - verbose* option
+To run kamaki in verbose mode use the *-v/- - verbose* argument, it goes with
+everything.
 
 Verbose mode outputs the request and response mode, address and
 headers as well as the size of the data block, if any. Sensitive information
 (x-auth-token header and data body) are omitted by default,. Users who need
 this information may enable it through the log_token and log_data configuration
-options (see next section)
+options
 
-.. tip:: Use the -o runtime option to enable config options on the fly, e.g, to
-    include http data:
+.. tip:: Use the -o argument to include http data in the output:
 
     .. code-block:: console
 
@@ -329,8 +354,8 @@ options (see next section)
 Logging
 """""""
 
-Kamaki keeps its logs in a file specified by the *log_file* option and it
-defaults to *${HOME}/.kamaki.log*. This configuration option can be modified::
+Kamaki logs in a file specified by the *log_file* option which defaults to
+*${HOME}/.kamaki.log*. This configuration option can be modified::
 
     kamaki config set log_file /new/log/file/path
 
@@ -383,32 +408,27 @@ on, though:
 One-command features
 ^^^^^^^^^^^^^^^^^^^^
 
-Kamaki commands can be used along with advanced shell features.
-
 .. code-block:: console
     :emphasize-lines: 1
 
     Example 3.4.1: List the trash container contents, containing c1_
     
-
-    $ kamaki file list -o cloud.default.pithos_container=trash| grep c1_
-    c1_1370859409.0 20KB
-    c1_1370859414.0 9MB
-    c1_1370859409.1 110B
+    $ kamaki file list -v -o log_token=on
+    ...
+    X-Auth-Token: s0m3-3x4mp1e-70k3n
+    ...
 
 The -o argument can be used to temporarily override various (set or unset)
 options. In one command, all -o option sets are forgotten just after the
 command has been completed, and the previous settings are restored (the
 configuration file is not modified).
 
-The file-list command in example 3.4.1 runs with an explicitly provided
-pithos_account, which temporarily overrides the one probably provided in the
-configuration file (it works even if the user has not set the optional
-pithos_account config option).
+For security reasons, all commands hide the authentication token from outputs
+and the logs. In example 3.4.1 the token is not hided, because of the
+*log_token=on* config option.
 
-.. tip:: There are better ways to list the contents of a container. Example
-    3.4.1 is using this method for demonstration purposes only. The suggested
-    method for listing container contents is *- - container=<container>*
+.. warning:: Complimentary output i.e., http logs and informative messages are
+  printed to standard error stream
 
 Interactive shell
 -----------------
@@ -416,9 +436,10 @@ Interactive shell
 Command Contexts
 ^^^^^^^^^^^^^^^^
 
-The kamaki interactive shell implements the notion of command contexts. Each
-command group is also a context where the users can **enter** by typing the
-group name. If the context switch is successful, the kamaki shell prompt
+The command namespaces in kamaki interactive shell are called **contexts**.
+
+Each command group is also a context where the users can **enter** by typing
+the group name. If the context switch is successful, the kamaki shell prompt
 changes to present the new context ("*file*" in example 4.1.1).
 
 .. code-block:: console
@@ -458,7 +479,7 @@ A user might **browse** through different contexts during one session.
     [config]: exit
     [kamaki]: file
     [file]: list
-    ... (storage containers listing) ...
+    ... (file listing) ...
     [file]: exit
     [kamaki]: server
     [server]: list
@@ -466,23 +487,38 @@ A user might **browse** through different contexts during one session.
     [server]: exit
     [kamaki]:
 
-Users have the option to avoid switching between contexts: all commands can run
-from the **top context**. As a result, examples 4.1.3 and 4.1.4 are equivalent.
+Users can avoid switching between contexts: all commands can run from the
+**top context** e.g., examples 4.1.3 and 4.1.4 are equivalent.
 
 .. code-block:: console
     :emphasize-lines: 1
 
     Example 4.1.4: Execute different "list" commands from top context
 
-
     [kamaki]: config list
     ... (configuration options listing) ...
     [kamaki]: file list
-    ... (storage container listing) ...
+    ... (file listing) ...
     [kamaki]: server list
     ... (servers listing) ...
     [kamaki]:
 
+While in a context, other contexts are accessible by using a **/** as shown in
+the following example:
+
+.. code-block:: console
+
+  Example 4.1.5: Execute different "list" commands from the config context
+
+  [kamaki]: config
+  [config]: list
+  ... (configuration option listing) ...
+  [config]: /file list
+  ... (file listing) ...
+  [config]: /server list
+  ... (servers listing) ...
+  [config]:
+
 Using Help
 ^^^^^^^^^^
 
@@ -512,7 +548,6 @@ The context-level help results may change from context to context
 
     Example 4.2.1: Get available commands and then get help in a context
 
-
     [kamaki]: help
 
     kamaki commands:
@@ -543,8 +578,8 @@ The context-level help results may change from context to context
 
 In context-level, there is a distinction between kamaki-commands and
 interactive shell commands. The former are available in one-command mode and
-are related to the cloud client setup and use, while the later are
-context-shell functions.
+are the main functionality of kamaki, while the later are used to manage the
+kamaki-shell.
 
 **Command-level help** prints the syntax, arguments and description of a
 specific (terminal) command
@@ -606,193 +641,6 @@ There are many ways of producing a help message, as shown in example 4.2.3
     [file]: /config set -h
     [server]: /config set --help
 
-.. _accessing-top-level-commands-ref:
-
-Accessing top-level commands
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When working in a context, it is often useful to access other contexts or
-top-level commands. Kamaki offers access to top-level commands by using the
-`/` prefix, as shown bellow::
-
-    * access a command "anothercontext cmd1 cmd2 ... cmdN"
-    [context]: /anothercontext cmd1 cmd2 ... cmdN
-
-An example (4.3.1) that showcases how top-level access improves user experience
-is the creation of a server. A server is created with the command server-create. This
-command is called with three parameters:
-
-* the name of the new server
-* the flavor id
-* the image id
-
-An average user would enter the server context and type *create -h* to check the
-syntax of the command. In that point, it would be nice to have some easy way of
-accessing the *flavor* and *image* contexts, to list and pick a flavor id and an
-image id. This is achieved with the / notation, as demonstrated in the following
-example:
-
-.. code-block:: console
-    :emphasize-lines: 1
-
-    Example 4.3.1: Create a server from server context
-
-    [server]: create -h
-    create <name> <flavor id> <image id> ...
-    ...
-    
-    [server]: /flavor list
-    ...
-    43 AFLAVOR
-        SNF:disk_template:  drbd
-        cpu              :  4
-        disk             :  10
-        ram              :  2048
-    
-    [server]: /image compute list
-    1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
-    18a82962-43eb-8f8880af89d7 (Windows 7)
-    531aa018-9a40-a4bfe6a0caff (Windows XP)
-    6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
-    
-    [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
-    ...
-
-An other example (4.3.2) showcases how to acquire and modify configuration
-settings from a different context. In this scenario, the user token expires at
-server side while the user is working. When that happens, the system responds
-with an *(401) UNAUTHORIZED* message. The user can acquire a new token (valid
-for the Astakos identity manager of preference) which has to be set to kamaki.
-
-.. code-block:: console
-    :emphasize-lines: 1
-
-    Example 4.3.2: Token suddenly expires. Set a new token from file context
-
-
-    [file]: list
-    (401) UNAUTHORIZED Access denied
-
-    [file]: /user authenticate
-    (401) UNAUTHORIZED Invalid X-Auth-Token
-
-    [file]: /config get cloud.default.token
-    my3xp1r3dt0k3n==
-
-    [file]: /config set cloud.default.token myfr35ht0k3n==
-
-    [file]: /config get cloud.default
-    cloud.default.url = https://astakos.example.com/astakos/identity/2.0/
-    cloud.default.token = myfr35ht0k3n==
-
-    [file]: list
-    1.  pithos (10MB, 2 objects)
-    2.  trash (0B, 0 objects)
-
-.. note:: The error messages on examples are shortened for clarity. Actual error
-    messages are more helpful and descriptive.
-
-The following example compares some equivalent calls that run
-*user-authenticate* after a *file-list* 401 failure.
-
-.. code-block:: console
-    :emphasize-lines: 1,3,10,17,26
-
-    Example 4.3.3: Equivalent user-authenticate calls after a file-list 401
-
-    * I. without kamaki interactive shell *
-    $ kamaki file list
-    (401) UNAUTHORIZED Access denied
-    $ kamaki user authenticate
-    ...
-    $
-
-    * II. from top-level context *
-    [kamaki]: file list
-    (401) UNAUTHORIZED Access denied
-    [kamaki]: user authenticate
-    ...
-    [kamaki]
-
-    * III. maximum typing *
-    [file]: list
-    (401) UNAUTHORIZED Access denied
-    [file]: exit
-    [kamaki]: user
-    [user]: authenticate
-    ...
-    [user]:
-
-    * IV. minimum typing *
-    [file]: list
-    (401) UNAUTHORIZED Access denied
-    [file]: /user authenticate
-    ...
-    [file]:
-
-.. hint:: To exit kamaki shell while in a context, try */exit*
-
-Using config
-^^^^^^^^^^^^
-
-The configuration mechanism of kamaki is detailed in the
-`setup section <setup.html>`_, it is accessible as *config* and it is common for
-both interaction modes. In specific, the configuration mechanism is implemented
-as  `config`. Using the config commands is as straightforward as in any other
-group of commands.
-
-It is often useful to set, delete or update a value. This can be managed either
-inside the config context or from any command context by using the / prefix.
-
-.. Note:: config updates in kamaki shell persist even after the session is over
-
-All setting changes affect the physical kamaki config file. The config file is
-created automatically at callers' home firectory the first time a config option
-is set, and lives there as *.kamakirc* . It can be edited with any text editor
-or managed with kamaki config commands.
-
-In example 4.4.1 the user is going to work with only one storage container. The
-file commands use the container:path syntax, but if the user sets a container
-name as default, the container name can be omitted.
-
-.. code-block:: console
-    :emphasize-lines: 1
-
-    Example 4.4.1: Set default storage container (cloud alias: default)
-
-
-    [file]: list
-      mycontainer (32MB, 2 objects)
-      pithos (0B, 0 objects)
-      trash (2MB, 1 objects)
-
-    [file]: list mycontainer
-      D mydir/
-      20M mydir/rndm_local.file
-    
-    [file]: /config set cloud.default.pithos_container mycontainer
-
-    [file]: list
-      D mydir/
-      20M mydir/rndm_local.file
-
-After a while, the user needs to work with multiple containers, therefore a
-default container is no longer needed. The *pithos_container* setting can be
-deleted, as shown in example 4.4.2
-
-.. code-block:: console
-    :emphasize-lines: 1
-
-    Example 4.4.2: Delete a setting option (cloud: default)
-
-
-    [file]: /config delete cloud.default.pithos_container
-
-    [file]: list
-      mycontainer (32MB, 2 objects)
-      pithos (0B, 0 objects)
-      trash (2MB, 1 objects)
-
 History modes
 ^^^^^^^^^^^^^
 
@@ -827,43 +675,44 @@ history-run
 
     * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
     [kamaki]: file
-    [file]: copy mycontainer1:somefile mycontainer1:myfile
-    [file]: download mycontainer1:myfile mylocalfile
+    [file]: copy /mycontainer1/somefile /mycontainer1/myfile
+    [file]: download /mycontainer1/myfile mylocalfile
     ...
     Download completed
-    [file]: upload mylocalfile mycontainer2:myfile -f
+    [file]: upload mylocalfile /mycontainer2/myfile -f
     ...
     Upload completed
 
     * undo the process *
     [file]: !rm mylocalfile
-    [file]: delete mycontainer1:myfile
-    [file]: delete mycontainer2:myfile
+    [file]: delete /mycontainer1/myfile
+    [file]: delete /mycontainer2/myfile
 
     * check history entries *
     [file]: exit
     [kamaki]: history
     [history]: show
     1.  file
-    2.  file copy mycontainer1:somefile mycontainer1:myfile
-    3.  file download mycontainer1:myfile mylocalfile
-    4.  file upload mylocalfile mycontainer2:myfile -f
-    5.  file delete mycontainer1:myfile
-    6.  file delete mycontainer2:myfile
+    2.  file copy /mycontainer1/somefile /mycontainer1/myfile
+    3.  file download /mycontainer1/myfile mylocalfile
+    4.  file upload mylocalfile /mycontainer2/myfile -f
+    5.  file delete /mycontainer1/myfile
+    6.  file delete /mycontainer2/myfile
     7.  history
     8.  history show
 
     *repeat the process *
     [history]: run 2-4
-    <file copy mycontainer1:somefile mycontainer1:myfile>
-    <file download mycontainer1:myfile mylocalfile>
+    <file copy /mycontainer1/somefile /mycontainer1/myfile>
+    <file download /mycontainer1/myfile mylocalfile>
     Download completed
-    <file upload mylocalfile mycontainer2:myfile>
+    <file upload mylocalfile /mycontainer2/myfile>
     Upload completed
 
-For powerfull scripting, users are advised to take advantage of their os shell
-scripting capabilities and combine them with kamaki one-command. Still, the
-history-run functionality might prove handy in many occasions.
+The suggested best practice for scripting is python scripts that import the
+`kamaki.clients` library. Another option is host shell scripting (e.g., bash)
+with kamaki one-command. Still, the history-run functionality might prove handy
+in many occasions.
 
 OS Shell integration
 ^^^^^^^^^^^^^^^^^^^^
diff --git a/kamaki/cli/commands/cyclades.py b/kamaki/cli/commands/cyclades.py
index 7c48dd8..7b87a18 100644
--- a/kamaki/cli/commands/cyclades.py
+++ b/kamaki/cli/commands/cyclades.py
@@ -708,7 +708,7 @@ class server_shutdown(_init_cyclades, _optional_output_cmd, _server_wait):
 
 @command(server_cmds)
 class server_addr(_init_cyclades):
-    """DEPRECATED, use: [kamaki] server info <SERVER_ID> --nics"""
+    """DEPRECATED, use: [kamaki] server info SERVER_ID --nics"""
 
     def main(self, *args):
         raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
@@ -718,7 +718,7 @@ class server_addr(_init_cyclades):
 
 @command(server_cmds)
 class server_console(_init_cyclades, _optional_json):
-    """DEPRECATED, use: [kamaki] server info <SERVER_ID> --vnc-credentials"""
+    """DEPRECATED, use: [kamaki] server info SERVER_ID --vnc-credentials"""
 
     def main(self, *args):
         raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
@@ -727,8 +727,18 @@ class server_console(_init_cyclades, _optional_json):
 
 
 @command(server_cmds)
+class server_rename(_init_cyclades, _optional_json):
+    """DEPRECATED, use: [kamaki] server modify SERVER_ID --name=NEW_NAME"""
+
+    def main(self, *args):
+        raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
+            'Replaced by',
+            '  [kamaki] server info <SERVER_ID> --stats'])
+
+
+@command(server_cmds)
 class server_stats(_init_cyclades, _optional_json):
-    """DEPRECATED, use: [kamaki] server info <SERVER_ID> --stats"""
+    """DEPRECATED, use: [kamaki] server info SERVER_ID --stats"""
 
     def main(self, *args):
         raiseCLIError('DEPRECATED since v0.12', importance=3, details=[
