4 Kamaki features commands of the form::
6 [kamaki] <object> <action> [identifier(s)] <non-positional arguments>
8 kamaki user info --username=user@example.com
10 A detailed list of the command specifications can be found in
11 `Commands <commands.html>`_ section.
13 All commands can run either from the host shell or through the kamaki
16 .. code-block:: console
22 # Run from kamaki interactive shell
27 In the later, the term "one-command" will be user to refer to running kamaki
28 commands from host shell, while the term "shell" will refer to the kamaki's own
31 .. note:: This section refers to the kamaki CLI. Developers and people who write
32 scripts, should rather use the the
33 `Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki
39 Kamaki interfaces rely on a list of configuration options. Check the
40 `Setup <setup.html>`_ guide for a full list.
42 As rule of the thump, it is enough to set a cloud authentication URL and TOKEN:
44 .. code-block:: console
47 Example 1.1: Set authentication URL, user token for cloud alias "default"
49 $ kamaki config set cloud.default.url <authentication URL>
50 $ kamaki config set cloud.default.token myt0k3n==
52 .. note:: The term *default* can be replaced by any arbitary term chosen by
58 Kamaki users can access Synnefo services through either the kamaki shell or the
59 one-command interface. Both systems feature identical responses and error
60 messages, since they rely on the same internal command and library API
61 implementation. However, there are some minor differences.
63 In favor of interactive shell:
65 * shorter commands (context switching)
66 * tab completion for commands (if supported by host shell)
67 * kamaki-specific history with ↑ or ↓ keys (if supported by host shell)
68 * re-run old commands with /history
70 In favor of one-command:
72 * users take advantage of host shell features (pipelines, redirection, etc.)
73 * can be used in shell scripts
77 To use kamaki as a shell, run:
79 .. code-block:: console
82 Example 2.2.1: Run kamaki shell
86 * with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
89 .. code-block:: console
92 Example 2.2.2: Run kamaki shell with custom configuration file
94 $ kamaki-shell -c myconfig.file
96 Example 2.2.3: Run kamaki shell so as to use a specific cloud
98 $ kamaki-shell --cloud=my_demo_cloud
100 Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests)
104 .. note:: Valid arguments can be combined e.g., it is ok to run a shell with
105 verbosity and a specific cloud::
107 $ kamaki-shell -v --cloud=my_demo_cloud
111 To use kamaki as an one-command tool, run:
113 * with the '-h' or '--help' arguments (help for kamaki one-command)
115 .. code-block:: console
118 Example 2.3.1: Kamaki help
122 * with one or more command parameters (object and, maybe, action):
124 .. code-block:: console
127 Example 2.3.2: List servers managed by user
131 One-command interface
132 ---------------------
137 Kamaki help provides information on commands (description, syntax).
139 To see the command groups (objects), use -h or --help (example 1.3.1). The
140 following examples demonstrate the help messages of kamaki, in the context of a
141 command group (server) and of a command in that group (list).
143 .. code-block:: console
146 Example 3.1.1: kamaki help shows available parameters and command groups
150 usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
151 [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS] [--cloud CLOUD] [-h]
154 -v, --verbose More info at response
155 -s, --silent Do not output anything
156 -V, --version Print current version
157 -d, --debug Include debug output
158 -c CONFIG, --config CONFIG
159 Path to configuration file
160 -o OPTIONS, --options OPTIONS
161 Override a config value
162 --cloud CLOUD Chose a cloud to connect to
163 -h, --help Show help message
167 resource: Astakos/Account API commands for resources
168 group: Pithos+/Storage user groups
169 network: Networking API network commands
170 subnet: Networking API network commands
171 ip: Networking API floatingip commands
172 image: Cyclades/Plankton API image commands
173 imagecompute: Cyclades/Compute API image commands
174 quota: Astakos/Account API commands for quotas
175 sharer: Pithos+/Storage sharers
176 project: Astakos project API commands
177 user: Astakos/Identity API commands
178 file: Pithos+/Storage object level API commands
179 container: Pithos+/Storage container level API commands
180 flavor: Cyclades/Compute API flavor commands
181 server: Cyclades/Compute API server commands
182 config: Kamaki configurations
183 port: Networking API network commands
184 history: Kamaki command history
185 kamaki-shell: An interactive command line shell
187 .. code-block:: console
188 :emphasize-lines: 1,2
190 Example 3.1.2: Cyclades help contains all first-level commands of Cyclades
194 usage: kamaki server <...> [-v] [-s] [-V] [-d] [-c CONFIG]
195 [-o OPTIONS] [--cloud CLOUD] [-h]
198 -v, --verbose More info at response
199 -s, --silent Do not output anything
200 -V, --version Print current version
201 -d, --debug Include debug output
202 -c CONFIG, --config CONFIG
203 Path to configuration file
204 -o OPTIONS, --options OPTIONS
205 Override a config value
206 --cloud CLOUD Chose a cloud to connect to
207 -h, --help Show help message
211 info: Detailed information on a Virtual Machine
212 modify: Modify attributes of a virtual server
213 create: Create a server (aka Virtual Machine)
214 list: List virtual servers accessible by user
215 reboot: Reboot a virtual server
216 start: Start an existing virtual server
217 shutdown: Shutdown an active virtual server
218 delete: Delete a virtual server
220 .. code-block:: console
221 :emphasize-lines: 1,2
223 Example 3.1.3: Help for command "server list" with syntax, description and
224 available user options
226 $ kamaki server list -h
227 usage: kamaki server list [-v] [-s] [-V] [-d] [-c CONFIG] [-o OPTIONS]
228 [--cloud CLOUD] [-h] [--since SINCE] [--enumerate]
229 [-l] [--more] [-n LIMIT] [-j]
231 List Virtual Machines accessible by user
234 -v, --verbose More info at response
235 -s, --silent Do not output anything
236 -V, --version Print current version
237 -d, --debug Include debug output
238 -c CONFIG, --config CONFIG
240 -o OPTIONS, --options OPTIONS
241 Override a config value
242 --cloud CLOUD Chose a cloud to connect to
243 -h, --help Show help message
244 --status STATUS filter by status (ACTIVE, STOPPED, REBOOT, ERROR,
246 --enumerate Enumerate results
247 --name-suffix NAME_SUFF
248 filter by name suffix (case insensitive)
249 --image-id IMAGE_ID filter by image id
250 --metadata META filter by metadata key=values
251 -j, --json show headers in json
253 --user-id USER_ID filter by user id
254 --id-like ID_LIKE print only if id contains this (case insensitive)
255 --id-suffix ID_SUFF filter by id suffix (case insensitive)
256 --since SINCE show only items since date (' d/m/Y H:M:S ')
257 -l, --details show detailed output
258 --name NAME filter by name
259 --more output results in pages (-n to set items per page,
261 --name-prefix NAME_PREF
262 filter by name prefix (case insensitive)
263 -n LIMIT, --number LIMIT
264 limit number of listed virtual servers
265 --id-prefix ID_PREF filter by id prefix (case insensitive)
266 --user-name USER_NAME
268 --name-like NAME_LIKE
269 print only if name contains this (case insensitive)
270 --metadata-like META_LIKE
271 print only if in key=value, the value is part of
273 --flavor-id FLAVOR_ID
277 Use filtering arguments (e.g., --name-like) to manage long server lists
279 .. _using-history-ref:
284 Kamaki command history is stored in '${HOME}/.kamaki.history' by default). To
285 set a custom history file path users must set the history.file config option
286 (more on config options `here <setup.html#editing-options>`_).
288 Every command is appended at the end of that file. In order to see how to use
289 history, use the kamaki help system:
291 .. code-block:: console
294 Example 3.2.1: Available history options
299 clean: Clean up history (permanent)
300 run : Run previously executed command(s)
301 show : Show intersession command history
304 Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
306 $ kamaki history clean
309 $ kamaki history show
310 1. kamaki server list
311 2. kamaki history show
312 $ kamaki history show --match server
313 1. kamaki server list
314 3. kamaki history show --match server
322 When in debug mode, kamaki outputs some useful debug information (stack trace
323 and http logs). Kamaki in debug mode cancels the suppression of warning
326 To run kamaki in debug mode use the -d or --debug option.
332 Most kamaki commands are translated into http requests. Kamaki clients API
333 translates command semantics to REST and handles the response. Users who need
334 to have access to these commands can use the verbose mode that outputs the
335 HTTP Request and Response details along with the (possibly modified) regular
338 To run kamaki in verbose mode use the *-v/- - verbose* argument, it goes with
341 Verbose mode outputs the request and response mode, address and
342 headers as well as the size of the data block, if any. Sensitive information
343 (x-auth-token header and data body) are omitted by default,. Users who need
344 this information may enable it through the log_token and log_data configuration
347 .. tip:: Use the -o argument to include http data in the output:
349 .. code-block:: console
351 $ kamaki server list -v -o log_data=on
357 Kamaki logs in a file specified by the *log_file* option which defaults to
358 *${HOME}/.kamaki.log*. This configuration option can be modified::
360 kamaki config set log_file /new/log/file/path
362 Kamaki logs http request and response information, namely the method, URL,
363 headers and data size. Sensitive information (data and token header) are
364 omitted by default. There are some configuration options that can switch them
367 * HTTP data blocks are not logged by default
368 to enable logging the full http bodies, set log_data to `on`::
370 kamaki config set log_data on
372 to disable it, set it to `off`::
374 kamaki config set log_data off
378 kamaki config delete log_data
380 * X-Auth-Token header is not logged by default
381 to enable logging the X-Auth-Token header, set log_token to `on`::
383 kamaki config set log_token on
385 to disable it, set it to `off`::
387 kamaki config set log_token off
391 kamaki config delete log_token
393 * The information (pid, name, date) of the processes that handle http requests
394 is not logged by default, because if they are, logs are difficult to read.
395 Still, they are useful for resolving race condition problems, so to enable
396 logging proccess information::
398 kamaki config set log_pid on
400 to disable it, set if to off::
402 kamaki config set log_pid off
406 kamaki config delete log_pid
411 .. code-block:: console
414 Example 3.4.1: List the trash container contents, containing c1_
416 $ kamaki file list -v -o log_token=on
418 X-Auth-Token: s0m3-3x4mp1e-70k3n
421 The -o argument can be used to temporarily override various (set or unset)
422 options. In one command, all -o option sets are forgotten just after the
423 command has been completed, and the previous settings are restored (the
424 configuration file is not modified).
426 For security reasons, all commands hide the authentication token from outputs
427 and the logs. In example 3.4.1 the token is not hided, because of the
428 *log_token=on* config option.
430 .. warning:: Complimentary output i.e., http logs and informative messages are
431 printed to standard error stream
439 The command namespaces in kamaki interactive shell are called **contexts**.
441 Each command group is also a context where the users can **enter** by typing
442 the group name. If the context switch is successful, the kamaki shell prompt
443 changes to present the new context ("*file*" in example 4.1.1).
445 .. code-block:: console
448 Example 4.1.1: Start kamaki and switch to file context
455 Type **exit** (alternatively **ctrl-D** in (X)nix systems or **ctrl-Z** in
456 Windows) to exit a context and return to the context of origin. If already at
457 the top context (kamaki), an exit is equivalent to exiting the program.
459 .. code-block:: console
462 Example 4.1.2: Exit file context and then exit kamaki
468 A user might **browse** through different contexts during one session.
470 .. code-block:: console
473 Example 4.1.3: Execute list command in different contexts
478 ... (configuration options listing) ...
482 ... (file listing) ...
486 ... (servers listing) ...
490 Users can avoid switching between contexts: all commands can run from the
491 **top context** e.g., examples 4.1.3 and 4.1.4 are equivalent.
493 .. code-block:: console
496 Example 4.1.4: Execute different "list" commands from top context
498 [kamaki]: config list
499 ... (configuration options listing) ...
501 ... (file listing) ...
502 [kamaki]: server list
503 ... (servers listing) ...
506 While in a context, other contexts are accessible by using a **/** as shown in
507 the following example:
509 .. code-block:: console
511 Example 4.1.5: Execute different "list" commands from the config context
515 ... (configuration option listing) ...
517 ... (file listing) ...
518 [config]: /server list
519 ... (servers listing) ...
525 There are two help mechanisms: a context-level and a command-level.
527 **Context-level help** lists the available commands in a context and can also
528 offer a short description for each command.
530 Context-level help syntax::
532 * Show available commands in current context *
538 * Show help for command cmd *
544 The context-level help results may change from context to context
546 .. code-block:: console
549 Example 4.2.1: Get available commands and then get help in a context
555 user config flavor history image network server file ...
557 interactive shell commands:
558 ===========================
562 Configuration commands (config -h for more options)
572 interactive shell commands:
573 ===========================
577 Set a configuration option (set -h for more options)
579 In context-level, there is a distinction between kamaki-commands and
580 interactive shell commands. The former are available in one-command mode and
581 are the main functionality of kamaki, while the later are used to manage the
584 **Command-level help** prints the syntax, arguments and description of a
585 specific (terminal) command
587 Command-level help syntax::
589 * Get help for command cmd1 cmd2 ... cmdN *
590 [context]: cmd1 cmd2 ... cmdN -h
595 <arguments and possible extensions>
597 Command-level help mechanism is exactly the same as the one used in
598 one-command mode. For example, it is invoked by using the -h or --help
599 parameter at any point.
601 .. code-block:: console
604 Example 4.2.2: Get command-level help for config and config-set
607 [kamaki]: config --help
608 config: Configuration commands
609 delete: Delete a configuration option (and use the default value)
610 get : Show a configuration option
611 list : List configuration options
612 set : Set a configuration option
617 usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
619 Set a configuration option
622 -v, --verbose More info at response
623 -d, --debug Include debug output
624 -h, --help Show help message
625 -i, --include Include protocol headers in the output
626 --config CONFIG Path to configuration file
627 -s, --silent Do not output anything
629 There are many ways of producing a help message, as shown in example 4.2.3
631 .. code-block:: console
634 Example 4.2.3: Equivalent calls of command-level help for config-set
639 [kamaki]: config set -h
640 [kamaki]: config set --help
641 [file]: /config set -h
642 [server]: /config set --help
647 There are two history modes: session and permanent. Session history keeps
648 record of all actions in a kamaki shell session, while permanent history
649 appends all commands to an accessible history file.
651 Session history is only available in interactive shell mode. Users can iterate
652 through past commands in the same session with the ↑ and ↓ keys. Session
653 history is not stored, although commands are recorded through the permanent
656 Permanent history is implemented as a command group and is common to both the
657 one-command and shell interfaces. In specific, every command is appended in a
658 history file (configured as `history_file` in settings, see
659 `setup section <setup.html>`_ for details). Commands executed in one-command
660 mode are mixed with the ones run in kamaki shell (also see
661 :ref:`using-history-ref` section on this guide).
666 The history-run feature allows the sequential run of previous command
667 executions in kamaki shell.
669 The following sequence copies and downloads a file from *mycontainer1* ,
670 uploads it to *mycontainer2* , then undo the proccess and repeats it with
673 .. code-block:: console
674 :emphasize-lines: 1,12,19,32
676 * Download mycontainer1:myfile and upload it to mycontainer2:myfile *
678 [file]: copy /mycontainer1/somefile /mycontainer1/myfile
679 [file]: download /mycontainer1/myfile mylocalfile
682 [file]: upload mylocalfile /mycontainer2/myfile -f
687 [file]: !rm mylocalfile
688 [file]: delete /mycontainer1/myfile
689 [file]: delete /mycontainer2/myfile
691 * check history entries *
696 2. file copy /mycontainer1/somefile /mycontainer1/myfile
697 3. file download /mycontainer1/myfile mylocalfile
698 4. file upload mylocalfile /mycontainer2/myfile -f
699 5. file delete /mycontainer1/myfile
700 6. file delete /mycontainer2/myfile
704 *repeat the process *
706 <file copy /mycontainer1/somefile /mycontainer1/myfile>
707 <file download /mycontainer1/myfile mylocalfile>
709 <file upload mylocalfile /mycontainer2/myfile>
712 The suggested best practice for scripting is python scripts that import the
713 `kamaki.clients` library. Another option is host shell scripting (e.g., bash)
714 with kamaki one-command. Still, the history-run functionality might prove handy
720 Kamaki shell features the ability to execute OS-shell commands from any
721 context. This can be achieved by typing *!* or *shell*::
723 [kamaki_context]: !<OS shell command>
724 ... OS shell command output ...
726 [kamaki_context]: shell <OS shell command>
727 ... OS shell command output ...
729 .. code-block:: console
732 Example 4.7.1: Run unix-style shell commands from kamaki shell
737 drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
738 drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
739 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
741 [kamaki]: shell cp kamaki-logo.png logo-copy.png
743 [kamaki]: shell ls -al
745 drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
746 drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
747 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
748 -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
751 Kamaki shell commits command strings to the outside shell and prints the
752 results, without interacting with it. After a command is finished, kamaki shell
753 returns to its initial state, which involves the current directory, as shown in
756 .. code-block:: console
759 Example 4.8.2: Attempt (and fail) to change working directory