NAME

       Net::CLI::Interact::Manual::Tutorial - Guide for new users

Introduction

       Automating command line interface (CLI) interactions is not a new idea, but can be tricky to implement.
       Net::CLI::Interact aims to provide a simple and manageable interface to CLI interactions, supporting:

       •   SSH, Telnet and Serial-Line connections

       •   Unix and Windows support

       •   Reusable device command phrasebooks

       The  module exists to support developers of applications and libraries which must interact with a command
       line interface. The SYNOPSIS section of Net::CLI::Interact has an overview of the  commands  demonstrated
       in this document.

Getting Started

       Like  many  other  Perl  modules,  you  need  to load the module and then create a new Net::CLI::Interact
       instance (which is $s in the example, below):

        use Net::CLI::Interact;

        my $s = Net::CLI::Interact->new({
            transport   => 'Serial',
            personality => 'cisco',
        });

       Your application can have multiple independent instances (that is, connect to different  devices  at  the
       same time); simply repeat the above example more times for variables other than $s.

       Note  that  at  the time you create the instance, as in the example above, the module does not connect to
       the device. That comes later.

       There were two options provided to the "new" call,  above,  both  of  which  are  required  for  all  new
       instances. Let's look at them in turn:

       transport
           How  do  you want to connect to your CLI? The current choices are Telnet, SSH and a Serial line (that
           is, a console cable). In this option you need to tell the module which underlying transport is to  be
           used.

           Some  of  the  transports have additional options that are either required, or optional. For example,
           the Telnet and SSH transports both need to know which post name or IP address  should  be  contacted.
           You pass this in another option to "new", like so:

            my $s = Net::CLI::Interact->new({
                transport       => 'Telnet',
                connect_options => { host => 'my.server.example.com' },

                personality     => 'cisco',
            });

           See the manual page of the transport module for the option details.

       personality
           What  language  does  the  connected  device  speak?   In  this option you need to pass the name of a
           personality that's used to load a Phrasebook.  For instance one common format is Cisco's  IOS,  which
           is widely cloned on other vendor equipment CLIs.

           A  phrasebook  is  simply a library, or dictionary, of pre-configured phrases you can use on the CLI.
           This makes life simple, because Net::CLI::Interact then can  automate  some  of  the  more  difficult
           tasks.  For  example,  if you issue a command and the output is "paged" so you hit Space or Return to
           see the next page, the phrasebook can tell Net::CLI::Interact how to slurp all these pages  into  one
           body of output before returning it to you.

           This  module  ships  with many phrasebooks which have been contributed by other users over the years.
           You can also write and use your own phrasebooks, which might replace, or add to, those  shipped  with
           the  module.  See the Phrasebook user guide for a list of phrasebooks shipped with this distribution,
           and their corresponding "personality" names.  See  also  the  "add_library"  option  to  "new()"  for
           specifying a path to your own phrasebooks.

Connecting

       This is done automatically for you the first time you send a command to the device, so skip this step and
       move on!

Sending Commands

   But first, Prompts
       The idea of sending a command is, usually, to see some output. The most important part of this process is
       knowing when the output has all been sent, otherwise the module would sit forever, waiting to gather more
       text!

       Between  each  command  sent,  the  connected  device  prints a CLI Prompt. This prompt is where you type
       commands, and it's what tells us that all the output has been sent from our  last  command.  Prompts  are
       loaded in the phrasebook, and given friendly names.

       If  your  personality's phrasebook is sufficiently mature, then the prompts might be fully automated, and
       just like the Connecting step above, you can skip doing anything manually. Consult  the  Phrasebook  user
       guide for details.

       However if you need to set it manually, do the following:

        $s->set_prompt('friendly_name');

       Sometimes  you  might  not know what state the CLI is in; typically this applies to Serial lines. In that
       case you can ask to find the matching prompt:

        $s->find_prompt($wake_up);

       This method gets some output from the connected session and then tries to match  it  against  any  loaded
       prompts,  returning  if  successful.  If  not  successful,  and  the  $wake_up  value  is  non-zero, then
       "find_prompt" will "hit the return key" to try to get some output. This process is retried  according  to
       the value of $wake_up (i.e. 1, 2, 3, etc), and of not successful will die.

   Literal Commands
       There's  not  a lot to it. Remember that with a mature personality loaded, you were probably able to skip
       the previous prompt step and go straight to:

        my $output = $s->cmd('show ip interfaces brief');

       Here you will get all the output from the command together in one variable, $output.  If  you  prefer  an
       array where each item is one line of output, simply use @output instead in the above example.

   Macros
       Life  gets  more  complicated  when  your command has things like confirmation steps (e.g. reboot), other
       prompts (e.g. extended ping), etc. For these situations we have Macros in the phrasebook.

       A macro is simply a sequence of commands we could issue using "$s->cmd()", bundled together and  given  a
       friendly  name. Macros are also smart enough either to handle simple confirmation steps themselves, or to
       allow you to pass in parameters. Some examples probably help:

        # saves config, accepting the default "startup-config" when prompted
        $s->macro('write_mem');

        # logs in, passing a username and password at the prompts
        $s->macro('to_user_exec', {
            params => ['my_username', 'my_password'],
        });

        # simply a parameterized command
        $s->macro('show_interfaces_x', {
            params => ['GigabitEthernet 3/4'],
        });

Slurping Output

       As mentioned above, output at the CLI is often "paged" with the user hitting Space or Return to show  the
       next page. Most macros can deal with this automatically if well implemented.

       If  the  Phrasebook  user guide says your personality has a named default Continuation for handling paged
       output, then set it like so:

        $s->set_default_continuation('friendly_name');

Disconnecting

       This is nothing more fancy than issuing the appropriate CLI commands to close the network connection.  In
       the  case of the Serial line transport you can usually only log out, and not fully disconnect. Simply end
       your application and the module will tidy things up as best it can.

perl v5.36.0                                       2023-10-28             Net::CLI::Inter...anual::Tutorial(3pm)