NAME

       Net::CLI::Interact - Toolkit for CLI Automation

PURPOSE

       This module exists to support developers of applications and libraries which must interact
       with a command line interface.

SYNOPSIS

        use Net::CLI::Interact;

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

        # respond to a usename/password prompt
        $s->macro('to_user_exec', {
            params => ['my_username', 'my_password'],
        });

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

        $s->macro('to_priv_exec', {
            params => ['my_password'],
        });
        # matched prompt is updated automatically

        # paged output is slurped into one response
        $s->macro('show_run');
        my $config = $s->last_response;

DESCRIPTION

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

       •   SSH, Telnet and Serial-Line connections

       •   Unix and Windows support

       •   Reuseable device command phrasebooks

       If you're a new user, please read the Tutorial. There's also a Cookbook and a Phrasebook
       Listing. For a more complete worked example check out the Net::Appliance::Session
       distribution, for which this module was written.

INTERFACE

   new( \%options )
       Prepares a new session for you, but will not connect to any device. On Windows platforms,
       you must download the "plink.exe" program, and pass its location to the "app" parameter.
       Other options are:

       "personality => $name" (required)
           The family of device command phrasebooks to load. There is a built-in library within
           this module, or you can provide a search path to other libraries. See
           Net::CLI::Interact::Manual::Phrasebook for further details.

       "transport => $backend" (required)
           The name of the transport backend used for the session, which may be one of Telnet,
           SSH, or Serial.

       "connect_options => \%options"
           If the transport backend can take any options (for example the target hostname), then
           pass those options in this value as a hash ref. See the respective manual pages for
           each transport backend for further details.

       "log_at => $log_level"
           To make using the "logger" somewhat easier, you can pass this argument the name of a
           log level (such as "debug", "info", etc) and all logging in the library will be
           enabled at that level. Use "debug" to learn about how the library is working
           internally. See Net::CLI::Interact::Logger for a list of the valid level names.

       "timeout => $seconds"
           Configures a default timeout value, in seconds, for interaction with the remote
           device. The default is 10 seconds. You can also set timeout on a per-command or per-
           macro call (see below).

           Note that this does not (currently) apply to the initial connection.

   cmd( $command )
       Execute a single command statement on the connected device, and consume output until there
       is a match with the current prompt. The statement is executed verbatim on the device, with
       a newline appended.

       In scalar context the "last_response" is returned (see below). In list context the
       gathered response is returned as a list of lines. In both cases your local platform's
       newline character will end all lines.

   macro( $name, \%options? )
       Execute the commands contained within the named Macro, which must be loaded from a
       Phrasebook. Options to control the output, including variables for substitution into the
       Macro, are passed in the %options hash reference.

       In scalar context the "last_response" is returned (see below). In list context the
       gathered response is returned as a list of lines. In both cases your local platform's
       newline character will end all lines.

   last_response
       Returns the gathered output after the most recent "cmd" or "macro". In scalar context all
       data is returned. In list context the gathered response is returned as a list of lines. In
       both cases your local platform's newline character will end all lines.

   transport
       Returns the Transport backend which was loaded based on the "transport" option to "new".
       See the Telnet, SSH, or Serial documentation for further details.

   phrasebook
       Returns the Phrasebook object which was loaded based on the "personality" option given to
       "new". See Net::CLI::Interact::Phrasebook for further details.

   set_phrasebook( \%options )
       Allows you to (re-)configure the loaded phrasebook, perhaps changing the personality or
       library, or other properties. The %options Hash ref should be any parameters from the
       Phrasebook module, but at a minimum must include a "personality".

   set_default_contination( $macro_name )
       Briefly, a Continuation handles the slurping of paged output from commands.  See the
       Net::CLI::Interact::Phrasebook documentation for further details.

       Pass in the name of a defined Contination (Macro) to enable paging handling as a default
       for all sent commands. This is an alternative to describing the Continuation format in
       each Macro.

       To unset the default Continuation, call the "clear_default_continuation" method.

   logger
       This is the application's Logger object. A powerful logging subsystem is available to your
       application, built upon the Log::Dispatch distribution. You can enable logging of this
       module's processes at various levels, or add your own logging statements.

   set_global_log_at( $level )
       To make using the "logger" somewhat easier, you can pass this method the name of a log
       level (such as "debug", "info", etc) and all logging in the library will be enabled at
       that level. Use "debug" to learn about how the library is working internally. See
       Net::CLI::Interact::Logger for a list of the valid level names.

FUTHER READING

   Prompt Matching
       Whenever a command statement is issued, output is slurped until a matching prompt is seen
       in that output. Control of the Prompts is shared between the definitions in
       Net::CLI::Interact::Phrasebook dictionaries, and methods of the
       Net::CLI::Interact::Role::Prompt core component. See that module's documentation for
       further details.

   Actions and ActionSets
       All commands and macros are composed from their phrasebook definitions into Actions and
       ActionSets (iterable sequences of Actions).  See those modules' documentation for further
       details, in case you wish to introspect their structures.

COMPOSITION

       See the following for further interface details:

       •   Net::CLI::Interact::Role::Engine

AUTHOR

       Oliver Gorwits <oliver@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2017 by Oliver Gorwits.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.