+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
+changes to present the new context ("*file*" in example 4.1.1).
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.1.1: Start kamaki and switch to file context
+
+
+ $ kamaki
+ [kamaki]: file
+ [file]:
+
+Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in
+Windows) to exit a context and return to the context of origin. If already at
+the top context (kamaki), an exit is equivalent to exiting the program.
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.1.2: Exit file context and then exit kamaki
+
+ [file]: exit
+ [kamaki]: exit
+ $
+
+A user might **browse** through different contexts during one session.
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.1.3: Execute list command in different contexts
+
+ $ kamaki
+ [kamaki]: config
+ [config]: list
+ ... (configuration options listing) ...
+ [config]: exit
+ [kamaki]: file
+ [file]: list
+ ... (storage containers listing) ...
+ [file]: exit
+ [kamaki]: server
+ [server]: list
+ ... (servers listing) ...
+ [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.
+
+.. 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) ...
+ [kamaki]: server list
+ ... (servers listing) ...
+ [kamaki]:
+
+Using Help
+^^^^^^^^^^
+
+There are two help mechanisms: a context-level and a command-level.
+
+**Context-level help** lists the available commands in a context and can also
+offer a short description for each command.
+
+Context-level help syntax::
+
+ * Show available commands in current context *
+ [context]: help
+ ...
+ [context]: ?
+ ...
+
+ * Show help for command cmd *
+ [context]: help cmd
+ ...
+ [context]: ?cmd
+ ...
+
+The context-level help results may change from context to context
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.2.1: Get available commands and then get help in a context
+
+
+ [kamaki]: help
+
+ kamaki commands:
+ ================
+ user config flavor history image network server file ...
+
+ interactive shell commands:
+ ===========================
+ exit help shell
+
+ [kamaki]: ?config
+ Configuration commands (config -h for more options)
+
+ [kamaki]: config
+
+ [config]: ?
+
+ config commands:
+ ================
+ delete get list set
+
+ interactive shell commands:
+ ===========================
+ exit help shell
+
+ [config]: help set
+ Set a configuration option (set -h for more options)
+
+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.
+
+**Command-level help** prints the syntax, arguments and description of a
+specific (terminal) command
+
+Command-level help syntax::
+
+ * Get help for command cmd1 cmd2 ... cmdN *
+ [context]: cmd1 cmd2 ... cmdN -h
+ <syntax>
+
+ <description>
+
+ <arguments and possible extensions>
+
+Command-level help mechanism is exactly the same as the one used in
+one-command mode. For example, it is invoked by using the -h or --help
+parameter at any point.
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.2.2: Get command-level help for config and config-set
+
+
+ [kamaki]: config --help
+ config: Configuration commands
+ delete: Delete a configuration option (and use the default value)
+ get : Show a configuration option
+ list : List configuration options
+ set : Set a configuration option
+
+ [kamaki]: config
+
+ [config]: set -h
+ usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
+
+ Set a configuration option
+
+ optional arguments:
+ -v, --verbose More info at response
+ -d, --debug Include debug output
+ -h, --help Show help message
+ -i, --include Include protocol headers in the output
+ --config CONFIG Path to configuration file
+ -s, --silent Do not output anything
+
+There are many ways of producing a help message, as shown in example 4.2.3
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.2.3: Equivalent calls of command-level help for config-set
+
+
+ [config]: set -h
+ [config]: set --help
+ [kamaki]: config set -h
+ [kamaki]: config set --help
+ [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
+^^^^^^^^^^^^^
+
+There are two history modes: session and permanent. Session history keeps
+record of all actions in a kamaki shell session, while permanent history
+appends all commands to an accessible history file.
+
+Session history is only available in interactive shell mode. Users can iterate
+through past commands in the same session with the ↑ and ↓ keys. Session
+history is not stored, although commands are recorded through the permanent
+history mechanism.
+
+Permanent history is implemented as a command group and is common to both the
+one-command and shell interfaces. In specific, every command is appended in a
+history file (configured as `history_file` in settings, see
+`setup section <setup.html>`_ for details). Commands executed in one-command
+mode are mixed with the ones run in kamaki shell (also see
+:ref:`using-history-ref` section on this guide).
+
+Scripting
+^^^^^^^^^
+
+The history-run feature allows the sequential run of previous command
+executions in kamaki shell.
+
+The following sequence copies and downloads a file from *mycontainer1* ,
+uploads it to *mycontainer2* , then undo the proccess and repeats it with
+history-run
+
+.. code-block:: console
+ :emphasize-lines: 1,12,19,32
+
+ * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
+ [kamaki]: file
+ [file]: copy mycontainer1:somefile mycontainer1:myfile
+ [file]: download mycontainer1:myfile mylocalfile
+ ...
+ Download completed
+ [file]: upload mylocalfile mycontainer2:myfile -f
+ ...
+ Upload completed
+
+ * undo the process *
+ [file]: !rm mylocalfile
+ [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
+ 7. history
+ 8. history show
+
+ *repeat the process *
+ [history]: run 2-4
+ <file copy mycontainer1:somefile mycontainer1:myfile>
+ <file download mycontainer1:myfile mylocalfile>
+ Download completed
+ <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.
+
+OS Shell integration
+^^^^^^^^^^^^^^^^^^^^
+
+Kamaki shell features the ability to execute OS-shell commands from any
+context. This can be achieved by typing *!* or *shell*::
+
+ [kamaki_context]: !<OS shell command>
+ ... OS shell command output ...
+
+ [kamaki_context]: shell <OS shell command>
+ ... OS shell command output ...
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.7.1: Run unix-style shell commands from kamaki shell
+
+
+ [kamaki]: !ls -al
+ total 16
+ drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
+ drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
+ -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
+
+ [kamaki]: shell cp kamaki-logo.png logo-copy.png
+
+ [kamaki]: shell ls -al
+ total 24
+ drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
+ drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
+ -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
+ -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
+
+
+Kamaki shell commits command strings to the outside shell and prints the
+results, without interacting with it. After a command is finished, kamaki shell
+returns to its initial state, which involves the current directory, as shown in
+example 4.8.2
+
+.. code-block:: console
+ :emphasize-lines: 1
+
+ Example 4.8.2: Attempt (and fail) to change working directory
+
+
+ [kamaki]: !pwd
+ /home/username
+
+ [kamaki]: !cd ..
+
+ [kamaki]: shell pwd
+ /home/username