SFTP File Transfer

SFTP cheatsheet — transfer files securely over SSH. sftp user@host, put to upload, get to download, ls/cd to navigate. Interactive file transfer with SSH authentication.

7 min read

What it is

SFTP (SSH File Transfer Protocol) is a secure way to transfer files between a local and remote machine over an SSH connection. You reach for it when you need to upload or download files to/from a server where you have SSH access.

Installation

SFTP is typically included as part of your SSH client.

Linux: Usually pre-installed. If not, install openssh-client:

sudo apt update && sudo apt install openssh-client
# or
sudo dnf install openssh-client

Mac: Included with macOS. No installation needed.
Windows:
- Windows 10/11 (OpenSSH Client):
```
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
```
- Alternatively, use a GUI client like FileZilla or WinSCP.

Core Concepts

Remote Host: The server you are connecting to.
Local Host: Your current machine.
SSH Connection: SFTP uses the underlying SSH protocol for authentication and encryption. This means you’ll use the same credentials (username, password, or SSH key) as you would for SSH.
sftp> prompt: Once connected, you’ll see an sftp> prompt, indicating you are in the SFTP interactive shell.

Commands / Usage

Connecting to a Remote Host

Connect using username and password:
```
sftp user@example.com
```
Connects to example.com as user user and prompts for a password.
Connect using username and password to a specific port:
```
sftp -P 2222 user@example.com
```
Connects to example.com on port 2222 as user user.
Connect using an SSH key:
```
sftp -i ~/.ssh/id_rsa user@example.com
```
Connects to example.com as user user using the private key ~/.ssh/id_rsa.
Connect to a hostname with a specific port:
```
sftp -P 2222 example.com
```
Connects to example.com on port 2222 using your current local username.

Navigating the Remote System (within the `sftp>` prompt)

List files and directories on the remote system:
```
ls
```
Shows the contents of the current remote directory.
List files and directories with details:
```
lls
```
Shows the contents of the current local directory with details.
Change directory on the remote system:
```
cd /var/www/html
```
Changes the current remote directory to /var/www/html.
Change directory on the local system:
```
lcd ..
```
Changes the current local directory to the parent directory.
Print working directory on the remote system:
```
pwd
```
Displays the current remote directory path.
Print working directory on the local system:
```
lpwd
```
Displays the current local directory path.

Transferring Files

Download a file from remote to local:
```
get remote_file.txt local_file.txt
```
Downloads remote_file.txt from the remote server to your current local directory, saving it as local_file.txt.
Download a file and keep the same name:
```
get /path/to/remote/file.zip
```
Downloads file.zip from /path/to/remote/ on the server to your current local directory.
Download multiple files (using wildcards):
```
mget *.log
```
Downloads all files ending in .log from the current remote directory to the current local directory. You will be prompted for each file.
Upload a file from local to remote:
```
put local_file.txt remote_file.txt
```
Uploads local_file.txt from your current local directory to the current remote directory, saving it as remote_file.txt.
Upload a file and keep the same name:
```
put /path/to/local/image.jpg
```
Uploads image.jpg from /path/to/local/ on your machine to the current remote directory.
Upload multiple files (using wildcards):
```
mput *.config
```
Uploads all files ending in .config from the current local directory to the current remote directory. You will be prompted for each file.

Advanced Transfer Options

Download a file recursively (directory):
```
get -r /path/to/remote/directory
```
Downloads the entire directory and its contents from the remote server to your current local directory.
Upload a directory recursively:
```
put -r /path/to/local/directory
```
Uploads the entire directory and its contents from your local machine to the current remote directory.
Resume interrupted transfers:
```
get -r remote_large_file.zip
put -r local_backup.tar.gz
```
The -r flag also enables resuming interrupted transfers for files.
Force overwrite existing files:
```
put -o local_script.sh
get -o remote_config.yaml
```
The -o flag forces overwriting existing files on the destination without prompting.

Other Useful Commands (within the `sftp>` prompt)

Create a directory on the remote system:
```
mkdir new_remote_directory
```
Creates a new directory named new_remote_directory on the remote server.
Remove a file on the remote system:
```
rm old_file.txt
```
Deletes old_file.txt from the remote server.
Remove a directory on the remote system (must be empty):
```
rmdir empty_directory
```
Deletes the empty directory empty_directory on the remote server.
Rename a file or directory on the remote system:
```
rename old_name.txt new_name.txt
```
Renames old_name.txt to new_name.txt on the remote server.
Get help:
```
help
# or
?
```
Displays a list of available SFTP commands.
Exit the SFTP session:
```
quit
# or
exit
# or
bye
```
Closes the SFTP connection and returns to your local shell.

Non-Interactive Usage (Command Line)

Download a file directly:
```
sftp user@example.com:/path/to/remote/file.txt ./local_destination/
```
Downloads file.txt from user@example.com to the specified local path.
Upload a file directly:
```
sftp ./local_file.txt user@example.com:/path/to/remote/destination/
```
Uploads local_file.txt to the specified remote path on user@example.com.
Upload a directory recursively:
```
sftp -r ./local_directory user@example.com:/path/to/remote/destination/
```
Uploads the entire local_directory and its contents to the remote server.
Download a directory recursively:
```
sftp -r user@example.com:/path/to/remote/directory ./local_destination/
```
Downloads the entire directory and its contents from the remote server.
Execute a single command remotely and exit:
```
sftp -oBatchMode=yes -b commands.txt user@example.com
```
Executes commands listed in commands.txt on the remote server and then exits. BatchMode=yes prevents interactive prompts.

Example commands.txt content:
```
cd /var/www
put index.html
quit
```

Common Patterns

Synchronize a local directory to a remote directory: This is often done with rsync over SSH, but for simpler cases or when rsync isn’t available, you can script SFTP. However, SFTP doesn’t have a built-in "sync" command. The most common approach is to use mget and mput with lcd and cd, or to use put -r and get -r for entire directories. For true synchronization, rsync is generally preferred.
Download all files from a remote directory:
```
sftp user@example.com <<EOF
cd /remote/path/to/files
lcd /local/path/to/save
mget *
quit
EOF
```
This uses a "here document" to send commands to sftp non-interactively.

Upload all files from a local directory:

sftp user@example.com <<EOF
cd /remote/path/to/upload
lcd /local/path/with/files
mput *
quit
EOF

Transferring a single file using a specific key and port:
```
sftp -P 2222 -i ~/.ssh/deploy_key deploy_user@app.example.com:/home/deploy_user/app.tar.gz ./builds/
```
Downloads app.tar.gz from the specified server and port using a specific key.

Gotchas

mget and mput prompt for each file: By default, mget and mput will ask for confirmation for every file. To disable this, you can use the -r flag with get or put for recursive operations, or the -o flag to force overwrite without prompting. For truly non-interactive batch operations, consider using a script with <<EOF or tools like rsync.
rmdir only works on empty directories: To remove a directory and its contents, you’ll need to rm the files inside it first, or use ssh user@host 'rm -rf /path/to/directory' non-interactively.
SFTP is not FTP: SFTP is a secure protocol that runs over SSH. It is distinct from FTP (File Transfer Protocol) and FTPS (FTP over SSL/TLS). SFTP commands are generally simpler and less feature-rich than FTP commands.
Permissions: SFTP transfers files with their original permissions by default. If you need to change permissions, you might need to use the chmod command on the remote server via SSH or after the transfer.
Local vs. Remote Commands: Remember the distinction between ls (remote) and lls (local), cd (remote) and lcd (local), pwd (remote) and lpwd (local). This is a common source of confusion.
Exiting the prompt: Don’t forget to quit or exit the sftp> prompt when you’re done, otherwise, your connection will remain open.