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

VERSION
    version 2.142720

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) 2014 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.