NAME

Shell::Carapace - Simple realtime output for ssh and shell commands

SYNOPSIS

            

              
              
use Shell::Carapace::Local;
# A callback is required.  It can be used to log commands, output, errors
my $shell_callback = sub {
    my ($category, $message, $host) = @_;
    print "  $host $message\n"  if $category =~ /output/ && $message;
    print "Running $message\n"  if $category eq 'command';
    print "ERROR: cmd failed\n" if $category eq 'error';
};
my $shell = Shell::Carapace->shell(callback => $callback);
$shell->run(@cmd); # throws an exception if @cmd fails
my $ssh  = Shell::Carapace->ssh(
    callback    => $callback,    # required
    host        => $hostname,    # required
    ssh_options => $ssh_options, # a hash for Net::OpenSSH
);
$ssh->run(@cmd); # throws an exception if @cmd fails
            
          

DESCRIPTION

Ever run a script that takes 30 minutes to run and have to wait 30 minutes to see the output? This module solve that problem.

Shell::Carapace is a small wrapper around IPC::Open3::Simple and Net::OpenSSH. It provides a callback so you can easily log or process cmd output in realtime.

METHODS

shell(%options)

Creates and returns a Shell::Carapace::Shell object. All parameters are optional except 'callback'. The following parameters are accepted:

            

              
              
callback    : Required.  A coderef which is executed in realtime as output
            
          

ssh(%options)

Creates and returns a Shell::Carapace::SSH object. All parameters are optional except 'callback'. The following parameters are accepted:

            

              
              
callback    : Required.  A coderef which is executed in realtime as output
              is emitted from the command.
host        : Required.  A string like 'localhost' or 'user@hostname' which
              is passed to Net::OpenSSH.  Net::OpenSSH defaults the username
              to the current user.
ssh_options : A hash which is passed to Net::OpenSSH.
            
          

$shell->run(@cmd)

Execute the command locally via IPC::Open3::Simple. Calls the callback in realtime for each line of output emitted from the command.

$ssh->run(@cmd)

Execute the command on a remote host via Net::OpenSSH. Calls the callback in realtime for each line of output emitted from the command.

ABOUT THE NAME

Carapace: n. A protective, shell-like covering likened to that of a turtle or crustacean

LICENSE

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

AUTHOR

Eric Johnson <eric.git@iijo.org>