Net::C...torial(3pm)

🦋 Net::CLI::Interact::Manual::Tutorial 💅

okay bestie, so this is the tutorial page from the Net::CLI::Interact docs — it's literally your Guide for new users, and honestly? it's giving "welcome to the group chat, here's how everything works". it lives in the User Contributed Perl Documentation corner of your perl man pages. let's GO 🎀

---

✨ NAME ✨

Net::CLI::Interact::Manual::Tutorial — Guide for new users 🫶

---

🌸 Introduction 🌸

so, automating command line interface (CLI) interactions? not a new idea, bestie. but it is tricky to actually implement 😭. Net::CLI::Interact is here to give you a simple, manageable interface for CLI interactions, and it's out here supporting:

• SSH, Telnet and Serial-Line connections 🔌
• Unix and Windows support 🖥️
• Reusable device command phrasebooks 📖

this module exists to support the devs of applications and libraries that have to talk to a command line interface. and the SYNOPSIS section of Net::CLI::Interact has an overview of all the commands we're demoing in this doc. iykyk ✨

---

🚀 Getting Started 🚀

like many other Perl modules, step one is loading the module, step two is making a new Net::CLI::Interact instance (which is $s in the example below, mwah):

use Net::CLI::Interact;

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

your app can have multiple independent instances — yes, that means connecting to different devices at the same time, main character energy 💅. just repeat that example for variables other than $s.

heads up: when you create the instance (like above), the module does not connect to the device yet. that comes later, babe. patience 🧘

there were two options passed to the new call up there, and both are required for all new instances. let's go through them one at a time 🍓

🌈 transport 🌈

how do you wanna connect to your CLI? current choices are Telnet, SSH, and a Serial line (that's a console cable, bestie). this option is where you tell the module which underlying transport is getting used.

some transports have extra options that are either required or optional. for example, the Telnet and SSH transports both need to know which port name or IP address should be contacted 👀. you pass that 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 pass the name of a personality, which gets used to load a Phrasebook. for instance, one common format is Cisco's IOS, which is widely cloned on other vendor equipment CLIs. iconic behavior honestly.

a phrasebook is simply a library — or a dictionary, if you will — of pre-configured phrases you can use on the CLI 📖✨. this makes life simple, because then Net::CLI::Interact 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 those pages into one body of output before returning it to you. ate. 💅

this module ships with many phrasebooks that other users contributed over the years 🫶. you can also write and use your own phrasebooks, which might replace, or add to, the ones shipped with the module. see the Phrasebook user guide for a list of phrasebooks shipped with this distribution and their corresponding "personality" names. also check the add_library option to new() for specifying a path to your own phrasebooks 📁.

---

🔌 Connecting 🔌

this happens automatically the first time you send a command to the device. so skip this step and move on! no cap 🏃♀️

---

💬 Sending Commands 💬

🙈 But first, Prompts 🙈

the idea of sending a command is, usually, to see some output. and the most important part of this whole process is knowing when the output has all been sent — otherwise the module would just sit there 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 from our last command has been sent. 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 this:

$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 it's 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 if not successful, will die. 💀

✍️ Literal Commands ✍️

there's not a lot to it, bestie. 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'll 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. slay 🎀

🧚 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 they're 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 🧹✨.

---

and that's the whole tutorial, bestie!! you're literally a CLI automation girlie now 💅

this page came to you from perl v5.36.0, dated 2023-10-28, under the name Net::C...torial(3pm) — stay iconic, mwah 🎀💖✨