Thanks for the suggestion. This module seems to have a lot of functionality, so I definitely thought the try worth the effort. I'm calling it differently now and get a different error:

Permission denied (publickey,password).
object created, back in main
[download]

sub get_ftp_object{
use strict;
use Net::SFTP::Foreign;
use 5.01;
my $sub_hash = "my_sftp";
my $domain = $config{$sub_hash}->{'domain'};
my $username = $config{$sub_hash}->{'username'};
my $password = $config{$sub_hash}->{'password'};
my $port = 22;
#dial up the server

say "values are $domain $username $password";
my $sftp = Net::SFTP::Foreign->new( $domain, user => $username,
port => $port, password => $password)
  or die "Can't connect: $!\n";

  return $sftp;
}
[download]

I seem to have gotten farther but don't understand why I didn't die here, as execution goes back to main. (?)

Net::SFTP::Foreign, by default, never dies when some error happens. Instead it keeps an internal error status that can be queried using the error method. For instance:

$s = Net::SFTP::Foreign->new(...);
if ($s->error) { die "Unable to connect to remote host: " . $s->error 
+}
[download]

Alternatively, you can activate the autodie mode. It makes the object die, when some error happens:

$s = Net::SFTP::Foreign->new(..., autodie => 1);
[download]

I finally got my little template working with this module. I found all the discussion and example code necessary, including cpan paragraph

I'm trying to use github to post bulky modules. author's github repo is the greater context in which this works:

sub get_html_filename{
use Net::SFTP::Foreign;
use File::Basename;
use Cwd;
use 5.01;

my $sftp = shift;
# get working directory
my $dir = getcwd();
my $word = basename($dir);
say "word is $word";
# get files from /pages
my $ls = $sftp->ls("/pages", wanted => qr/$word/)     
or warn "unable to retrieve ".$sftp->error;
print "$_->{filename}\n" for (@$ls);

my @remote_files = map  { $_->{filename} } @$ls;
say "files are @remote_files";
my $rref = \@remote_files;
my $filetype = "html";
my $old_num = highest_number($rref, $filetype, $word);
print "old num is $old_num\n";
my $new_num = $old_num + 1;
my $html_file = $word.$new_num.'.'.$filetype;
return $html_file;
}
[download]

Abridged output from stdout:

$ perl powell1.pl 
title is powell
values are [correct]
object created, back in main
word is powell
powell1.html
powell2.html
files are powell1.html powell2.html
old num is 2
new file is powell3.html
$
[download]

The page, populated by mundane matters, accomplishes its humble task: page posted (no porn). How to dereference a reference to an array of hashrefs is something that runrig posted on 2013 node, to wit:

my $ls = $sftp->ls('/home/ftptest/inbound', no_wanted => qr/^\./ );
my @names_and_sizes = map { { filename => $_->{filename}, size => $_->
+{a}->size } } @$ls;

# or...

my %size = map { $_->{filename} => $_->{a}->size } @$ls;
[download]

To shoehorn this into an array of filenames, I turned this into:

my @remote_files = map  { $_->{filename} } @$ls;

and I was back in business. Thanks all for comments and code.