Transfer files

.. only:: man

Overview
--------------

.. versionadded:: 0.30.0

.. _rsync: https://en.wikipedia.org/wiki/Rsync

Transfer files to and from remote computers over the TTY device itself. This means that file transfer works over nested SSH sessions, serial links, etc. Anywhere you have a terminal device, you can transfer files.

.. image:: ../screenshots/transfer.png :alt: The transfer kitten at work

This kitten supports transferring entire directory trees, preserving soft and hard links, file permissions, times, etc. It even supports the rsync_ protocol to transfer only changes to large files.

.. seealso:: See the :doc:remote_file kitten

Basic usage

Simply ssh into a remote computer using the :doc:ssh kitten </kittens/ssh> and run the this kitten (which the ssh kitten makes available for you on the remote computer automatically). Some illustrative examples are below. To copy a file from a remote computer::

<local computer>  $ kitten ssh my-remote-computer
<remote computer> $ kitten transfer some-file /path/on/local/computer

This, will copy :file:some-file from the computer into which you have SSHed to your local computer at :file:/path/on/local/computer. kitty will ask you for confirmation before allowing the transfer, so that the file transfer protocol cannot be abused to read/write files on your computer.

To copy a file from your local computer to the remote computer::

<local computer>  $ kitten ssh my-remote-computer
<remote computer> $ kitten transfer --direction=upload /path/on/local/computer remote-file

For more detailed usage examples, see the command line interface section below.

.. note:: If you dont want to use the ssh kitten, you can install the kitten binary on the remote machine yourself, it is a standalone, statically compiled binary available from the kitty releases page <https://github.com/kovidgoyal/kitty/releases>__. Or you can write your own script/program to use the underlying :doc:file transfer protocol </file-transfer-protocol>.

Avoiding the confirmation prompt

Normally, when you start a file transfer kitty will prompt you for confirmation. This is to ensure that hostile programs running on a remote machine cannot read/write files on your computer without your permission. If the remote machine is trusted, then you can disable the confirmation prompt by:

#. Setting the :opt:file_transfer_confirmation_bypass option to some password.

#. When invoking the kitten use the :option:--permissions-bypass <kitty +kitten transfer --permissions-bypass> to supply the password you set in step one.

.. warning:: Using a password to bypass confirmation means any software running on the remote machine could potentially learn that password and use it to gain full access to your computer.

Delta transfers

This kitten has the ability to use the rsync_ protocol to only transfer the differences between files. To turn it on use the :option:--transmit-deltas <kitty +kitten transfer --transmit-deltas> option. Note that this will actually be slower when transferring small files or on a very fast network, because of round trip overhead, so use with care.

.. include:: ../generated/cli-kitten-transfer.rst