.\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: November 23 2022 $
.Dt KAMIFTP 1
.Os
.Sh NAME
.Nm kamiftp
.Nd 9p client
.Sh SYNOPSIS
.Nm
.Op Fl C Ar cert
.Op Fl K Ar key
.Op Fl o Ar output
.Oo 9p:// Oc Ns Oo Ar user Ns @ Oc Ns Ar host Ns Oo : Ns Ar port Oc Ns Op / Ns Ar path
.Sh DESCRIPTION
.Nm
is a
.Xr 9p 7
client.
If
.Ar path
names a remote file,
.Nm
downloads it in the current directory and exit, otherwise changes the
remote working directory and starts accepting commands.
.Pp
The options are as follows:
.Bl -tag -width Ds
If used,
.Fl C
is mandatory.
.It Fl C Ar certificate
Connect with TLS to the remote server and use the given
.Ar certificate
during the TLS handsahke.
.It Fl K Ar key
Specify the path to the client certificate
.Ar key
to be used during the TLS handshake.
If not given, the file passed to
.Fl C
will be used.
If used,
.Fl C
must be provided too.
.It Fl o Ar output
When fetching the file specified to the command line,
save its content in
.Ar output .
To write the content to standard output, use
.Sq - .
It's an error to specify
.Fl o
when not givin a
.Ar path
or when
.Ar path
names a directory.
.El
.Pp
.Nm
parses the input similarly to
.Xr sh .
Words are splitted on spaces, multiple spaces are collapsed into one.
Quoting with
.Sq '
or
.Sq \&"
can be used to preserve spaces and other quotes.
.Sq \e
can be used to quote the following character.
No special meaning is given to
.Sq \e
sequences
.Po i.e.\& Sq \en
is just the
.Sq n
character
.Pc .
.Pp
The following commands are recognized by
.Nm :
.Bl -tag -width Ds
.It Ic bell Oo Cm on | off Oc
Request terminal to sound a bell after each command.
Without arguments toggle the current state.
.It Ic bye
Terminate the session.
Synomym of
.Ic quit .
.It Ic cd Ar remote-path
Change the working directory on the remote machine to
.Ar remote-path .
.It Ic edit Ar remote-path
Download
.Ar remote-path
and open it with the preferred editor
.Po
.Ev VISUAL
or
.Ev EDITOR
with
.Xr ed 1
as fallback
.Pc
then attempt to re-upload it.
.It Ic get Ar remote-file Op Ar local-file
Fetch
.Ar remote-file
and save it locally as
.Ar local-file .
If
.Ar local-file
is not given, use the file name from
.Ar remote-file .
.It Ic hexdump Oo Cm on | off Oc
Print the packets sent from/to the server.
Without arguments, toggle the current state.
.It Ic lcd Op Ar local-directory
Change the local current working directory to
.Ar local-directory
or the
.Ev HOME
if not given.
.It Ic lpwd
Print the local working directory.
.It Ic ls Op Ar path
List the file in the remote current working directory or
.Ar path
if provided.
.It Ic page Ar remote-file
Download
.Ar remote-file
and open it with the
.Ev PAGER
.Pq Xr less 1 by default .
.It Ic pipe Ar remote-file Ar cmd Op Ar args...
Fetch
.Ar remote-file
and pass it as standard input for
.Ar cmd
(with optional
.Ar args Ns ).
.It Ic put Ar local-file Op Ar remote-file
Upload
.Ar local-file
to
.Ar remote-file .
If
.Ar remote-file
is not given,
use the file name from
.Ar local-file .
.It Ic quit
Terminate the session.
Synomym of
.Ic bye .
.It Ic rename Ar remote-file Ar new-remote-name
Renames
.Ar remote-file
to
.Ar new-remote-name
on the remote server.
.It Ic rm Ar
Remove the remote files.
.It Ic verbose Oo Cm on | off Oc
Print verbose information.
Without arguments toggle the current state.
.El
.Sh ENVIRONMENT
The following environment variables are inspected:
.Bl -tag -width Ds
.It Ev HOME
The user login directory.
.It Ev PAGER
The pager to use,
.Xr less 1
by default.
.It Ev VISUAL , Ev EDITOR
The program used to edit files.
.Ev VISUAL
is inspected first,
.Ev EDITOR
as a fallback.
If both are undefined,
.Xr ed 1
is given some love.
.It Ev USER
Default login, used if no
.Ar user
is given on the command line.
.El
.Sh SEE ALSO
.Xr 9p 7 ,
.Xr kamid 8
.Sh AUTHORS
The
.Nm
utility was written by
.An Omar Polo Aq Mt op@omarpolo.com .