1Net::CLI::Interact(3) User Contributed Perl DocumentationNet::CLI::Interact(3)
2
3
4

NAME

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

PURPOSE

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

SYNOPSIS

13        use Net::CLI::Interact;
14
15        my $s = Net::CLI::Interact->new({
16           personality => 'cisco',
17           transport   => 'Telnet',
18           connect_options => { host => '192.0.2.1' },
19        });
20
21        # respond to a usename/password prompt
22        $s->macro('to_user_exec', {
23            params => ['my_username', 'my_password'],
24        });
25
26        my $interfaces = $s->cmd('show ip interfaces brief');
27
28        $s->macro('to_priv_exec', {
29            params => ['my_password'],
30        });
31        # matched prompt is updated automatically
32
33        # paged output is slurped into one response
34        $s->macro('show_run');
35        my $config = $s->last_response;
36

DESCRIPTION

38       Automating command line interface (CLI) interactions is not a new idea,
39       but can be tricky to implement. This module aims to provide a simple
40       and manageable interface to CLI interactions, supporting:
41
42       •   SSH, Telnet and Serial-Line connections
43
44       •   Unix and Windows support
45
46       •   Reuseable device command phrasebooks
47
48       If you're a new user, please read the Tutorial. There's also a Cookbook
49       and a Phrasebook Listing. For a more complete worked example check out
50       the Net::Appliance::Session distribution, for which this module was
51       written.
52

INTERFACE

54   new( \%options )
55       Prepares a new session for you, but will not connect to any device. On
56       Windows platforms, you must download the "plink.exe" program, and pass
57       its location to the "app" parameter. Other options are:
58
59       "personality => $name" (required)
60           The family of device command phrasebooks to load. There is a built-
61           in library within this module, or you can provide a search path to
62           other libraries. See Net::CLI::Interact::Manual::Phrasebook for
63           further details.
64
65       "transport => $backend" (required)
66           The name of the transport backend used for the session, which may
67           be one of Telnet, SSH, or Serial.
68
69       "connect_options => \%options"
70           If the transport backend can take any options (for example the
71           target hostname), then pass those options in this value as a hash
72           ref. See the respective manual pages for each transport backend for
73           further details.
74
75       "log_at => $log_level"
76           To make using the "logger" somewhat easier, you can pass this
77           argument the name of a log level (such as "debug", "info", etc) and
78           all logging in the library will be enabled at that level. Use
79           "debug" to learn about how the library is working internally. See
80           Net::CLI::Interact::Logger for a list of the valid level names.
81
82       "timeout => $seconds"
83           Configures a default timeout value, in seconds, for interaction
84           with the remote device. The default is 10 seconds. You can also set
85           timeout on a per-command or per-macro call (see below).
86
87           Note that this does not (currently) apply to the initial
88           connection.
89
90   cmd( $command )
91       Execute a single command statement on the connected device, and consume
92       output until there is a match with the current prompt. The statement is
93       executed verbatim on the device, with a newline appended.
94
95       In scalar context the "last_response" is returned (see below). In list
96       context the gathered response is returned as a list of lines. In both
97       cases your local platform's newline character will end all lines.
98
99   macro( $name, \%options? )
100       Execute the commands contained within the named Macro, which must be
101       loaded from a Phrasebook. Options to control the output, including
102       variables for substitution into the Macro, are passed in the %options
103       hash reference.
104
105       In scalar context the "last_response" is returned (see below). In list
106       context the gathered response is returned as a list of lines. In both
107       cases your local platform's newline character will end all lines.
108
109   last_response
110       Returns the gathered output after the most recent "cmd" or "macro". In
111       scalar context all data is returned. In list context the gathered
112       response is returned as a list of lines. In both cases your local
113       platform's newline character will end all lines.
114
115   transport
116       Returns the Transport backend which was loaded based on the "transport"
117       option to "new". See the Telnet, SSH, or Serial documentation for
118       further details.
119
120   phrasebook
121       Returns the Phrasebook object which was loaded based on the
122       "personality" option given to "new". See Net::CLI::Interact::Phrasebook
123       for further details.
124
125   set_phrasebook( \%options )
126       Allows you to (re-)configure the loaded phrasebook, perhaps changing
127       the personality or library, or other properties. The %options Hash ref
128       should be any parameters from the Phrasebook module, but at a minimum
129       must include a "personality".
130
131   set_default_contination( $macro_name )
132       Briefly, a Continuation handles the slurping of paged output from
133       commands.  See the Net::CLI::Interact::Phrasebook documentation for
134       further details.
135
136       Pass in the name of a defined Contination (Macro) to enable paging
137       handling as a default for all sent commands. This is an alternative to
138       describing the Continuation format in each Macro.
139
140       To unset the default Continuation, call the
141       "clear_default_continuation" method.
142
143   logger
144       This is the application's Logger object. A powerful logging subsystem
145       is available to your application, built upon the Log::Dispatch
146       distribution. You can enable logging of this module's processes at
147       various levels, or add your own logging statements.
148
149   set_global_log_at( $level )
150       To make using the "logger" somewhat easier, you can pass this method
151       the name of a log level (such as "debug", "info", etc) and all logging
152       in the library will be enabled at that level. Use "debug" to learn
153       about how the library is working internally. See
154       Net::CLI::Interact::Logger for a list of the valid level names.
155

FUTHER READING

157   Prompt Matching
158       Whenever a command statement is issued, output is slurped until a
159       matching prompt is seen in that output. Control of the Prompts is
160       shared between the definitions in Net::CLI::Interact::Phrasebook
161       dictionaries, and methods of the Net::CLI::Interact::Role::Prompt core
162       component. See that module's documentation for further details.
163
164   Actions and ActionSets
165       All commands and macros are composed from their phrasebook definitions
166       into Actions and ActionSets (iterable sequences of Actions).  See those
167       modules' documentation for further details, in case you wish to
168       introspect their structures.
169

COMPOSITION

171       See the following for further interface details:
172
173       •   Net::CLI::Interact::Role::Engine
174

AUTHOR

176       Oliver Gorwits <oliver@cpan.org>
177
179       This software is copyright (c) 2017 by Oliver Gorwits.
180
181       This is free software; you can redistribute it and/or modify it under
182       the same terms as the Perl 5 programming language system itself.
183
184
185
186perl v5.36.0                      2023-01-20             Net::CLI::Interact(3)
Impressum