code.grnet.gr Git - kamaki/blob - docs/usage.rst

   1 Usage
   2 =====
   3
   4 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.
   5
   6 What's more, kamaki offers a clients API that allows the development of external applications for synnefo. The clients API is listed in the `Clients lib <developers/code.html#the-clients-api>`_ section.
   7
   8 Quick Setup
   9 -----------
  10
  11 Kamaki interfaces rely on a list of configuration options. In the initial state, kamaki is configured to communicate with the Okeanos IaaS. A detailed guide for setting up kamaki can be found in the `Setup <setup.html>`_ section.
  12
  13 It is essential for users to get a valid configuration token that works with for a synnefo-compliant Identity Manager service (okeanos.grnet.gr users go `here <https://accounts.okeanos.grnet.gr/im/>`_) and provide it to kamaki:
  14
  15 .. code-block:: console
  16     :emphasize-lines: 1
  17
  18     Example 1.1: Set user token to myt0k3n==
  19
  20     $ kamaki config set token myt0k3n==
  21
  22 Shell vs one-command
  23 --------------------
  24 Kamaki users can access synnefo services through either the interactive shell or the one-command behaviors. 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.
  25
  26 In favor of interactive shell behavior:
  27
  28 * tab completion for commands (mostly on (X)nix OSs)
  29 * session history with "up" / "down" keys
  30 * shorter commands with command context switching
  31 * re-run old commands with /history
  32
  33 In favor of one-command behavior:
  34
  35 * can be used along with advanced shell features (pipelines, redirection, etc.)
  36 * can be used in shell scripts
  37 * prints debug and verbose messages if needed
  38
  39 Run as shell
  40 ^^^^^^^^^^^^
  41 To use kamaki as a shell, run:
  42
  43 * without any parameters or arguments
  44
  45 .. code-block:: console
  46     :emphasize-lines: 1
  47
  48     Example 2.2.1: Run kamaki shell
  49
  50     $ kamaki
  51
  52 * with any kind of '-' prefixed arguments, except '-h', '--help'.
  53
  54 .. code-block:: console
  55     :emphasize-lines: 1
  56
  57     Example 2.2.2: Run kamaki shell with custom configuration file
  58
  59     $ kamaki --config myconfig.file
  60
  61
  62 Run as one-command
  63 ^^^^^^^^^^^^^^^^^^
  64 To use kamaki as an one-command tool, run:
  65
  66 * with the '-h' or '--help' arguments (help for kamaki one-command)
  67
  68 .. code-block:: console
  69     :emphasize-lines: 1
  70
  71     Example 2.3.1: Kamaki help
  72
  73     $kamaki -h
  74
  75 * with one or more command parameters:
  76
  77 .. code-block:: console
  78     :emphasize-lines: 1
  79
  80     Example 2.3.2: List VMs managed by user
  81
  82     $ kamaki server list
  83
  84 One-command interface
  85 ---------------------
  86
  87 Using help
  88 ^^^^^^^^^^
  89
  90 Kamaki help is used to list available commands with description, syntax and corresponding optional arguments.
  91
  92 To see the command groups, use -h or --help like in example 1.3.1. In the same way, help information for command groups and commands is printed. In the following examples, the help messages of kamaki, of a command group (server) and of a command in that group (list) are shown.
  93
  94 .. code-block:: console
  95     :emphasize-lines: 1
  96
  97     Example 3.1.1: kamaki help shows available parameters and command groups
  98
  99
 100     $ kamaki -h
 101     usage: kamaki <cmd_group> [<cmd_subbroup> ...] <cmd>
 102         [-s] [-V] [-i] [--config CONFIG] [-o OPTIONS] [-h]
 103
 104     optional arguments:
 105       -v, --verbose         More info at response
 106       -s, --silent          Do not output anything
 107       -V, --version         Print current version
 108       -d, --debug           Include debug output
 109       -i, --include         Include protocol headers in the output
 110       --config CONFIG       Path to configuration file
 111       -o OPTIONS, --options OPTIONS
 112                             Override a config value
 113       -h, --help            Show help message
 114
 115     Options:
 116      - - - -
 117     user:   Astakos API commands
 118     config: Configuration commands
 119     flavor: Compute/Cyclades API flavor commands
 120     history:    Command history
 121     image:  Plankton (and Compute) Image API commands
 122     network:    Compute/Cyclades API network commands
 123     server: Compute/Cyclades API server commands
 124     file:  Pithos+ storage commands
 125
 126 .. code-block:: console
 127     :emphasize-lines: 1
 128
 129     Example 3.1.2: Cyclades help contains all first-level commands of Cyclades command group
 130
 131
 132     $ kamaki server -h
 133     usage: kamaki server <...> [-v] [-s] [-V] [-d] [-i] [--config CONFIG]
 134                                [-o OPTIONS] [-h]
 135
 136     optional arguments:
 137       -v, --verbose         More info at response
 138       -s, --silent          Do not output anything
 139       -V, --version         Print current version
 140       -d, --debug           Include debug output
 141       -i, --include         Include protocol headers in the output
 142       --config CONFIG       Path to configuration file
 143       -o OPTIONS, --options OPTIONS
 144                             Override a config value
 145       -h, --help            Show help message
 146
 147     Options:
 148      - - - -
 149     addmeta :  Add server metadata
 150     addr    :  List a server's nic address
 151     console :  Get a VNC console
 152     create  :  Create a server
 153     delete  :  Delete a server
 154     delmeta :  Delete server metadata
 155     firewall:  Set the server's firewall profile
 156     info    :  Get server details
 157     list    :  List servers
 158     meta    :  Get a server's metadata
 159     reboot  :  Reboot a server
 160     rename  :  Update a server's name
 161     setmeta :  Update server's metadata
 162     shutdown:  Shutdown a server
 163     start   :  Start a server
 164     stats   :  Get server statistics
 165     wait    :  Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
 166
 167 .. code-block:: console
 168     :emphasize-lines: 1
 169
 170     Example 3.1.3: Help for command "server list" with syntax, description and available user options
 171
 172
 173     $ kamaki server list -h
 174     usage: kamaki server list [-V] [-i] [--config CONFIG] [-h] [-l]
 175
 176     List servers
 177
 178     optional arguments:
 179       -v, --verbose         More info at response
 180       -s, --silent          Do not output anything
 181       -V, --version         Print current version
 182       -d, --debug           Include debug output
 183       -i, --include         Include protocol headers in the output
 184       --config CONFIG       Path to configuration file
 185       -o OPTIONS, --options OPTIONS
 186                             Override a config value
 187       -h, --help            Show help message
 188       -l                    show detailed output
 189
 190 .. _using-history-ref:
 191
 192 Using history
 193 ^^^^^^^^^^^^^
 194
 195 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>`_).
 196
 197 Every syntactically correct command is appended at the end of that file. In order to see how to use history, use the kamaki help system:
 198
 199 .. code-block:: console
 200     :emphasize-lines: 1
 201
 202     Example 3.2.1: Available history options
 203
 204
 205     $ kamaki history -h
 206     Options:
 207      - - - -
 208     clean:  Clean up history (permanent)
 209     run  :  Run previously executed command(s)
 210     show :  Show intersession command history
 211
 212 The following example showcases how to use history in kamaki
 213
 214 .. code-block:: console
 215     :emphasize-lines: 1
 216
 217     Example 3.2.2: Clean up everything, run a kamaki command, show full and filtered history
 218
 219
 220     $ kamaki history clean
 221     $ kamaki server list
 222     ...
 223     $ kamaki history show
 224     1.  kamaki server list
 225     2.  kamaki history show
 226     $ kamaki history show --match server
 227     1. kamaki server list
 228     3. kamaki history show --match server
 229
 230 Debug
 231 ^^^^^
 232
 233 In case of errors, kamaki in debug mode shows useful debug information, like the stack trace. Kamaki in debug mode cancels suppression of warning messages.
 234
 235 To run kamaki in debug mode use the -d or --debug option (can be combined with any other parameters or options)
 236
 237 Verbose and Include
 238 """""""""""""""""""
 239
 240 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.
 241
 242 To run kamaki in verbose mode use the -v or --verbose option
 243
 244 Be default, kamaki in verbose mode prints down only the headers and the address information, thus hiding the data body of the request or response. To see the data body, the -i option can be used.
 245
 246 One-command features
 247 ^^^^^^^^^^^^^^^^^^^^
 248
 249 Kamaki commands can be used along with advanced shell features.
 250
 251 .. code-block:: console
 252     :emphasize-lines: 1
 253
 254     Example 3.4.1: Print username for token us3rt0k3n== using grep
 255
 256
 257     $ kamaki user authenticate -o token=us3rt0k3n== | grep userame
 258     userame        : user@synnefo.org
 259
 260 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 (a.k.a. the configuration file is not modified).
 261
 262 The user-authenticate command in example 3.4.1 runs with an explicitly provided token, which temporarily overrides the token provided in the configuration file.
 263
 264 Interactive shell
 265 -----------------
 266
 267 Command Contexts
 268 ^^^^^^^^^^^^^^^^
 269
 270 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).
 271
 272 .. code-block:: console
 273     :emphasize-lines: 1
 274
 275     Example 4.1.1: Enter file commands context / group
 276
 277
 278     $ kamaki
 279     [kamaki]: file
 280     [file]:
 281
 282 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.
 283
 284 .. code-block:: console
 285     :emphasize-lines: 1
 286
 287     Example 4.1.2: Exit file context and then exit kamaki
 288
 289     [file]: exit
 290     [kamaki]: exit
 291     $
 292
 293 A user might **browse** through different contexts during one session.
 294
 295 .. code-block:: console
 296     :emphasize-lines: 1
 297
 298     Example 4.1.3: Execute list command in different contexts
 299
 300     $ kamaki
 301     [kamaki]: config
 302     [config]: list
 303     ... (configuration options listing) ...
 304     [config]: exit
 305     [kamaki]: file
 306     [file]: list
 307     ... (storage containers listing) ...
 308     [file]: exit
 309     [kamaki]: server
 310     [server]: list
 311     ... (VMs listing) ...
 312     [server]: exit
 313     [kamaki]:
 314
 315 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.
 316
 317 .. code-block:: console
 318     :emphasize-lines: 1
 319
 320     Example 4.1.4: Execute different "list" commands from top context
 321
 322
 323     [kamaki]: config list
 324     ... (configuration options listing) ...
 325     [kamaki]: file list
 326     ... (storage container listing) ...
 327     [kamaki]: server list
 328     ... (VMs listing) ...
 329     [kamaki]:
 330
 331 Using Help
 332 ^^^^^^^^^^
 333
 334 There are two help mechanisms: a context-level and a command-level.
 335
 336 **Context-level help** lists the available commands in a context and can also offer a short description for each command.
 337
 338 Context-level help syntax::
 339
 340     * Show available commands in current context *
 341     [context]: help
 342     [context]: ?
 343
 344     * Show help for command cmd *
 345     [context]: help cmd
 346     [context]: ?cmd
 347
 348 The context-level help results change from context to context
 349
 350 .. code-block:: console
 351     :emphasize-lines: 1
 352
 353     Example 4.2.1: Get available commands, pick a context and get help there as well
 354
 355
 356     [kamaki]: help
 357
 358     kamaki commands:
 359     ================
 360     user  config  flavor  history  image  network  server  file
 361
 362     interactive shell commands:
 363     ===========================
 364     exit  help  shell
 365
 366     [kamaki]: ?config
 367     Configuration commands (config -h for more options)
 368
 369     [kamaki]: config
 370
 371     [config]: ?
 372
 373     config commands:
 374     ================
 375     delete  get  list  set
 376
 377     interactive shell commands:
 378     ===========================
 379     exit  help  shell
 380
 381     [config]: help set
 382     Set a configuration option (set -h for more options)
 383
 384 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.
 385
 386 **Command-level help** prints the syntax, arguments and description of a specific (terminal) command
 387
 388 Command-level help syntax::
 389
 390     * Get help for command cmd1 cmd2 ... cmdN *
 391     [context]: cmd1 cmd2 ... cmdN -h
 392     <syntax>
 393
 394     <description>
 395
 396     <arguments and possible extensions>
 397
 398 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.
 399
 400 .. code-block:: console
 401     :emphasize-lines: 1
 402
 403     Example 4.2.2: Get command-level help for config and config-set
 404
 405
 406     [kamaki]: config --help
 407     config: Configuration commands
 408     delete:  Delete a configuration option (and use the default value)
 409     get   :  Show a configuration option
 410     list  :  List configuration options
 411     set   :  Set a configuration option
 412
 413     [kamaki]: config
 414
 415     [config]: set -h
 416     usage: set <option> <value> [-v] [-d] [-h] [-i] [--config CONFIG] [-s]
 417
 418     Set a configuration option
 419
 420     optional arguments:
 421       -v, --verbose    More info at response
 422       -d, --debug      Include debug output
 423       -h, --help       Show help message
 424       -i, --include    Include protocol headers in the output
 425       --config CONFIG  Path to configuration file
 426       -s, --silent     Do not output anything
 427
 428 There are many ways of producing a help message, as shown in example 4.2.3
 429
 430 .. code-block:: console
 431     :emphasize-lines: 1
 432
 433     Example 4.2.3: Equivalent calls of command-level help for config-set
 434
 435
 436     [config]: set -h
 437     [config]: set --help
 438     [kamaki]: config set -h
 439     [kamaki]: config set --help
 440     [file]: /config set -h
 441     [server]: /config set --help
 442
 443 .. _accessing-top-level-commands-ref:
 444
 445 Accessing top-level commands
 446 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 447
 448 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::
 449
 450     * access a command "anothercontext cmd1 cmd2 ... cmdN"
 451     [context]: /anothercontext cmd1 cmd2 ... cmdN
 452
 453 An example (4.3.1) that showcases how top-level access improves user experience is the creation of a VM. A VM is created with the command server-create. This command is called with three parameters:
 454
 455 * the name of the new VM
 456 * the flavor id
 457 * the image id
 458
 459 It is often the case that a user who works in the context command, needs to create a new VM, but hasn't selected a flavor or an image id, or cannot recall the id of that flavor or image. Therefore, it is necessary to list all available flavors (flavor-list) or images (image-compute-list). Both commands belong to different contexts.
 460
 461 .. code-block:: console
 462     :emphasize-lines: 1
 463
 464     Example 4.3.1: Create a VM from server context
 465
 466     [server]: create -h
 467     create <name> <flavor id> <image id> ...
 468     ...
 469
 470     [server]: /flavor list
 471     ...
 472     43 AFLAVOR
 473         SNF:disk_template:  drbd
 474         cpu              :  4
 475         disk             :  10
 476         ram              :  2048
 477
 478     [server]: /image compute list
 479     1580deb4-edb3-7a246c4c0528 (Ubuntu Desktop)
 480     18a82962-43eb-8f8880af89d7 (Windows 7)
 481     531aa018-9a40-a4bfe6a0caff (Windows XP)
 482     6aa6eafd-dccb-67fe2bdde87e (Debian Desktop)
 483
 484     [server]: create 'my debian' 43 6aa6eafd-dccb-67fe2bdde87e
 485     ...
 486
 487 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.
 488
 489 .. code-block:: console
 490     :emphasize-lines: 1
 491
 492     Example 4.3.2: Set a new token from file context
 493
 494
 495     [file]: list
 496     (401) UNAUTHORIZED Access denied
 497
 498     [file]: /user authenticate
 499     (401) UNAUTHORIZED Invalid X-Auth-Token
 500
 501     [file]: /config get token
 502     my3xp1r3dt0k3n==
 503
 504     [file]: /config set token myfr35ht0k3n==
 505
 506     [file]: /config get token
 507     myfr35ht0k3n==
 508
 509     [file]: list
 510     1.  pithos (10MB, 2 objects)
 511     2.  trash (0B, 0 objects)
 512
 513 .. note:: The error messages on this example where shortened for clarity. Actual kamaki error messages are more helpful and descriptive.
 514
 515 The following example compares some equivalent calls that run *user-authenticate* after a *file-list* 401 failure.
 516
 517 .. code-block:: console
 518     :emphasize-lines: 1,3,10,17,26
 519
 520     Example 4.3.3: Equivalent user-authenticate calls after a file-list 401 failure
 521
 522     * without kamaki interactive shell *
 523     $ kamaki file list
 524     (401) UNAUTHORIZED Access denied
 525     $ kamaki user authenticate
 526     ...
 527     $
 528
 529     * from top-level context *
 530     [kamaki]: file list
 531     (401) UNAUTHORIZED Access denied
 532     [kamaki]: user authenticate
 533     ...
 534     [kamaki]
 535
 536     * maximum typing *
 537     [file]: list
 538     (401) UNAUTHORIZED Access denied
 539     [file]: exit
 540     [kamaki]: user
 541     [user]: authenticate
 542     ...
 543     [user]:
 544
 545     * minimum typing *
 546     [file]: list
 547     (401) UNAUTHORIZED Access denied
 548     [file]: /user authenticate
 549     ...
 550     [file]:
 551
 552 .. hint:: To exit kamaki shell while in a context, try */exit*
 553
 554 Using config
 555 ^^^^^^^^^^^^
 556
 557 The configuration mechanism of kamaki is detailed at the `setup section <setup.html>`_ and it is common for both interaction modes. In specific, the configuration mechanism is implemented as a command group, namely *config*. Using the config commands is as straightforward as any other kamaki commands.
 558
 559 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.
 560
 561 .. Note:: config updates in kamaki shell persist even after the session is over.
 562
 563 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.
 564
 565 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. This is possible by setting a *file.container* setting.
 566
 567 .. code-block:: console
 568     :emphasize-lines: 1
 569
 570     Example 4.4.1: Set default storage container
 571
 572
 573     [file]: list
 574     1.  mycontainer (32MB, 2 objects)
 575     2.  pithos (0B, 0 objects)
 576     3.  trash (2MB, 1 objects)
 577
 578     [file]: list mycontainer
 579     1.  D mydir/
 580     2.  20M mydir/rndm_local.file
 581
 582     [file]: /config set file.container mycontainer
 583
 584     [file]: list
 585     1.  D mydir/
 586     2.  20M mydir/rndm_local.file
 587
 588 After a while, the user needs to work with multiple containers, therefore a default container is no longer needed. The *file.container* setting can be deleted, as shown in example 4.4.2 .
 589
 590 .. code-block:: console
 591     :emphasize-lines: 1
 592
 593     Example 4.4.2: Delete a setting option
 594
 595
 596     [file]: /config delete file.container
 597
 598     [file]: list
 599     1.  mycontainer (32MB, 2 objects)
 600     2.  pithos (0B, 0 objects)
 601     3.  trash (2MB, 1 objects)
 602
 603 Using history
 604 ^^^^^^^^^^^^^
 605
 606 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.
 607
 608 Session history is only available in interactive shell mode. Users can iterate through past commands in the same session with the *up* and *down* keys. Session history is not stored, although syntactically correct commands are recorded through the permanent history mechanism
 609
 610 Permanent history is implemented as a command group and is common to both the one-command and shell interfaces. In specific, every syntactically correct 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).
 611
 612 Scripting
 613 ^^^^^^^^^
 614
 615 The history-run feature allows the sequential run of previous command executions in kamaki shell.
 616
 617 The following sequence copies and downloads a file from *mycontainer1* , uploads it to *mycontainer2* , then undo the proccess and repeats it with history-run
 618
 619 .. code-block:: console
 620     :emphasize-lines: 1,12,19,32
 621
 622     * Download mycontainer1:myfile and upload it to mycontainer2:myfile
 623     [kamaki]: file
 624     [file]: copy mycontainer1:somefile mycontainer1:myfile
 625     [file]: download mycontainer1:myfile mylocalfile
 626     Download completed
 627     [file]: upload mylocalfile mycontainer2:myfile
 628     Upload completed
 629
 630     * undo the process *
 631     [file]: !rm mylocalfile
 632     [file]: delete mycontainer1:myfile
 633     [file]: delete mycontainer2:myfile
 634
 635     * check history entries *
 636     [file]: exit
 637     [kamaki]: history
 638     [history]: show
 639     1.  file
 640     2.  file copy mycontainer1:somefile mycontainer1:myfile
 641     3.  file download mycontainer1:myfile mylocalfile
 642     4.  file upload mylocalfile mycontainer2:myfile
 643     5.  file delete mycontainer1:myfile
 644     6.  file delete mycontainer2:myfile
 645     7.  history
 646     8.  history show
 647
 648     *repeat the process *
 649     [history]: run 2-4
 650     <file copy mycontainer1:somefile mycontainer1:myfile>
 651     <file download mycontainer1:myfile mylocalfile>
 652     Download completed
 653     <file upload mylocalfile mycontainer2:myfile>
 654     Upload completed
 655
 656 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.
 657
 658 Tab completion
 659 ^^^^^^^^^^^^^^
 660
 661 Kamaki shell features tab completion for the first level of command terms of the current context. Tab completion pool changes dynamically when the context is switched. Currently, tab completion is not supported when / is used (see :ref:`accessing-top-level-commands-ref` ).
 662
 663 OS Shell integration
 664 ^^^^^^^^^^^^^^^^^^^^
 665
 666 Kamaki shell features the ability to execute OS-shell commands from any context. This can be achieved by typing *!* or *shell*::
 667
 668     [kamaki_context]: !<OS shell command>
 669     ... OS shell command output ...
 670
 671     [kamaki_context]: shell <OS shell command>
 672     ... OS shell command output ...
 673
 674 .. code-block:: console
 675     :emphasize-lines: 1
 676
 677     Example 4.7.1: Run unix-style shell commands from kamaki shell
 678
 679
 680     [kamaki]: !ls -al
 681     total 16
 682     drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
 683     drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
 684     -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
 685
 686     [kamaki]: shell cp kamaki-logo.png logo-copy.png
 687
 688     [kamaki]: shell ls -al
 689     total 24
 690     drwxrwxr-x 2 username username 4096 Nov 27 16:47 .
 691     drwxrwxr-x 7 username username 4096 Nov 27 16:47 ..
 692     -rw-rw-r-- 1 username username 8063 Jun 28 14:48 kamaki-logo.png
 693     -rw-rw-r-- 1 username username 8063 Jun 28 14:48 logo-copy.png
 694
 695
 696 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 show in example 4.8.2 .
 697
 698 .. code-block:: console
 699     :emphasize-lines: 1
 700
 701     Example 4.8.2: Attempt (and fail) to change working directory
 702
 703
 704     [kamaki]: !pwd
 705     /home/username
 706
 707     [kamaki]: !cd ..
 708
 709     [kamaki]: shell pwd
 710     /home/username