SFTP(1)

🎀 SFTP(1) — General Commands Manual ✨

okay bestie, this is the manual page for sftp 💖 It's the General Commands Manual, and we're gonna go through the whole thing together 🫶

🌸 NAME 🌸

sftp — OpenSSH secure file transfer 🦋

💅 SYNOPSIS 💅

sftp [-46AaCfNpqrv] [-B buffer_size] [-b batchfile] [-c cipher]
     [-D sftp_server_command] [-F ssh_config] [-i identity_file]
     [-J destination] [-l limit] [-o ssh_option] [-P port]
     [-R num_requests] [-S program] [-s subsystem | sftp_server]
     [-X sftp_option] destination

✨ DESCRIPTION ✨

okay so sftp is a file transfer program, kinda like ftp(1), except it does everything over an encrypted ssh(1) transport 🔐 It can also borrow a bunch of ssh features, like public key authentication and compression. iconic behavior tbh 👑

The destination can be written as [user@]host[:path], or as a URI that looks like sftp://[user@]host[:port][/path] 🧚

If the destination has a path and that path isn't a directory, sftp will grab the files for you automatically when you're using a non-interactive authentication method. If you're doing interactive authentication instead, it waits until you've logged in successfully and then does the fetching 🙈

If there's no path, or the path is a directory, sftp logs you into the host and drops you into interactive command mode. If you gave it a remote directory, it'll change into that directory first 💜 You can add a trailing slash to force the path to be treated as a directory, which is a super handy little trick 🍓

Heads up: the destination formats use colons to separate host names from path names or port numbers. So IPv6 addresses have to be wrapped in square brackets, otherwise things get ambiguous and nobody wants that 😭

Here are the options, bestie 🌈

---

🌷 OPTIONS 🌷

• -4 — Forces sftp to use IPv4 addresses only. Strictly IPv4, no exceptions 🫶
• -6 — Forces sftp to use IPv6 addresses only. IPv6 or bust 💅
• -A — Lets you forward ssh-agent(1) to the remote system. By default, no authentication agent gets forwarded, so you have to ask for it explicitly ✨
• -a — Tries to pick up interrupted transfers where they left off, instead of overwriting the partial or complete copies that are already there 🦋

⚠️ Be careful with this one! If the partial contents don't match what's being transferred, the resulting file is likely to be corrupt 💀

• -B buffer_size — Sets the size of the buffer sftp uses when it transfers files. Bigger buffers need fewer round trips, but they eat more memory. The default is 32768 bytes 🧚
• -b batchfile — batch mode reads a list of commands from an input batchfile instead of stdin. There's no user interaction in batch mode, so you should pair it with non-interactive authentication. That way you won't have to type a password when connecting. (Check sshd(8) and ssh-keygen(1) for the deets 🔑)

A batchfile of - means standard input 🎀 sftp will abort if any of these commands fail: get, put, reget, reput, rename, ln, rm, mkdir, chdir, ls, lchdir, copy, cp, chmod, chown, chgrp, lpwd, df, symlink, and lmkdir.

You can suppress the abort-on-error behavior for a single command by starting that command with a - character. For example: -rm /tmp/blah*. And if you don't want the command echoed, start it with an @ character instead. You can combine these two prefixes in any order, like -@ls /bsd 💅

• -C — Turns on compression, using ssh's -C flag 🌈
• -c cipher — Picks the cipher used to encrypt the data transfers. This option gets passed straight through to ssh(1) ✨
• -D sftp_server_command — Connects directly to a local sftp server, skipping ssh(1) entirely. You can give it a command and its arguments, like "/path/sftp-server -el debug3". This one's really useful when you're debugging the client and server together 🔍
• -F ssh_config — Points ssh(1) at an alternative per-user configuration file. This gets passed straight through to ssh(1) 🫧
• -f — Asks for files to be flushed to disk right after the transfer finishes. When you're uploading, this only kicks in if the server implements the "fsync@openssh.com" extension 💾
• -i identity_file — Picks the file where the identity (private key) for public key authentication gets read from. This option is passed straight through to ssh(1) 🔑
• -J destination — Connects to the target host by first making an sftp connection to the jump host described by destination. From there, it sets up a TCP forwarding to the final destination. You can chain several jump hops by separating them with commas. This is a shortcut for the ProxyJump configuration directive, and the option is passed straight through to ssh(1) 🦋
• -l limit — Limits how much bandwidth gets used, measured in Kbit/s 🐢
• -N — Turns quiet mode off. This is handy when you want to override the implicit quiet mode that the -b flag sets 🎀
• -o ssh_option — Lets you pass options to ssh using the format from ssh_config(5). This is great for options that don't have their own sftp command-line flag. For example, to use an alternate port, you'd write sftp -oPort=24. For the full details on the options below and what values they accept, check out ssh_config(5) 🧚

These are the options you can pass this way:

• AddKeysToAgent
• AddressFamily
• BatchMode
• BindAddress
• BindInterface
• CASignatureAlgorithms
• CanonicalDomains
• CanonicalizeFallbackLocal
• CanonicalizeHostname
• CanonicalizeMaxDots
• CanonicalizePermittedCNAMEs
• CertificateFile
• ChannelTimeout
• CheckHostIP
• Ciphers
• ClearAllForwardings
• Compression
• ConnectTimeout
• ConnectionAttempts
• ControlMaster
• ControlPath
• ControlPersist
• DynamicForward
• EnableEscapeCommandline
• EnableSSHKeysign
• EscapeChar
• ExitOnForwardFailure
• FingerprintHash
• ForkAfterAuthentication
• ForwardAgent
• ForwardX11
• ForwardX11Timeout
• ForwardX11Trusted
• GSSAPIAuthentication
• GSSAPIDelegateCredentials
• GatewayPorts
• GlobalKnownHostsFile
• HashKnownHosts
• Host
• HostKeyAlgorithms
• HostKeyAlias
• HostbasedAcceptedAlgorithms
• HostbasedAuthentication
• Hostname
• IPQoS
• IdentitiesOnly
• IdentityAgent
• IdentityFile
• IgnoreUnknown
• Include
• KbdInteractiveAuthentication
• KbdInteractiveDevices
• KexAlgorithms
• KnownHostsCommand
• LocalCommand
• LocalForward
• LogLevel
• LogVerbose
• MACs
• NoHostAuthenticationForLocalhost
• NumberOfPasswordPrompts
• ObscureKeystrokeTiming
• PKCS11Provider
• PasswordAuthentication
• PermitLocalCommand
• PermitRemoteOpen
• Port
• PreferredAuthentications
• ProxyCommand
• ProxyJump
• ProxyUseFdpass
• PubkeyAcceptedAlgorithms
• PubkeyAuthentication
• RekeyLimit
• RemoteCommand
• RemoteForward
• RequestTTY
• RequiredRSASize
• RevokedHostKeys
• SecurityKeyProvider
• SendEnv
• ServerAliveCountMax
• ServerAliveInterval
• SessionType
• SetEnv
• StdinNull
• StreamLocalBindMask
• StreamLocalBindUnlink
• StrictHostKeyChecking
• SyslogFacility
• TCPKeepAlive
• Tag
• Tunnel
• TunnelDevice
• UpdateHostKeys
• User
• UserKnownHostsFile
• VerifyHostKeyDNS
• VisualHostKey
• XAuthLocation

✨ INTERACTIVE COMMANDS ✨

okay so once you're in interactive mode, sftp understands a bunch of commands that are basically like ftp(1)'s. 💅 Commands are case insensitive, so CD and cd are the same vibe. 🫶 If a pathname has spaces in it, it must be wrapped in quotes. Also, any special characters in a pathname that glob(3) recognizes need to be escaped with backslashes (\). no cap, that's the one thing that will trip you up 😭

• bye — quit sftp 👋
• cd [path] — changes the remote directory to path. If you don't give a path, it sends you back to the directory your session started in 🏠
• chgrp [-h] grp path — changes the group of the file at path to grp. path can use glob(7) characters and hit multiple files at once 🎯 grp has to be a numeric GID, bestie.
  • If you pass the -h flag, symlinks won't be followed. ⛓️‍💥 This only works on servers that implement the "lsetstat@openssh.com" extension, so check your server first 🔍
• chmod [-h] mode path — changes the permissions of the file at path to mode. path can use glob(7) characters and match multiple files 🔐
  • Same deal with -h: symlinks won't be followed. It's also only supported by servers that implement the "lsetstat@openssh.com" extension 💀
• chown [-h] own path — changes the owner of the file at path to own. path can use glob(7) characters and match multiple files 🧚 own has to be a numeric UID.
  • -h means symlinks aren't followed, and yep, it only works on servers with the "lsetstat@openssh.com" extension 🫠
• copy oldpath newpath — copies a remote file from oldpath to newpath 📄✨
  • This one is only supported by servers that implement the "copy-data" extension, so it's not guaranteed everywhere 🙈
• cp oldpath newpath — an alias for the copy command, so it does the exact same thing 👯
• df [-hi] [path] — shows usage info for the filesystem holding the current directory, or path if you give one 💾
  • -h shows the capacity info with "human-readable" suffixes, so you get nice big-unit numbers instead of a wall of digits 🍓
  • -i adds inode information on top of the capacity info 🔢
  • This command only works on servers that implement the “statvfs@openssh.com” extension, so if your server doesn't have it, it's gonna be a no-go 🥲
• exit — quit sftp 👋 (same as bye, literally)
• get [-afpR] remote-path [local-path] — downloads remote-path and saves it on your local machine 📥 If you don't name a local-path, it keeps the same name it had on the remote machine. remote-path can use glob(7) characters and match multiple files. If it does match multiple files and you give a local-path, then that local-path has to be a directory 📁
  • -a tries to resume partial transfers of existing files ⏯️ Heads up though: resuming assumes any partial local copy matches the remote copy. If the remote contents are different from the partial local copy, the final file is likely to be corrupt. 😭 Not a vibe.
  • -f tells sftp to call fsync(2) once the transfer finishes, which flushes the file out to disk 💧
  • -p copies over the full file permissions and access times too 🔐⏰
  • -R copies directories recursively 🌳 sftp does not follow symbolic links during recursive transfers, so those links stay links (no sneaky following) 🦋
• help — displays the help text 🆘
• lcd [path] — changes the local directory to path. If you don't give a path, it takes you to the local user's home directory 🏡
• lls [ls-options [path]] — displays a local directory listing of path, or of the current directory if you skip path 📂 ls-options can be any flags your local system's ls(1) command supports. path can use glob(7) characters and match multiple files 🎀
• lmkdir path — creates a local directory at path 🛠️
• ln [-s] oldpath newpath — creates a link from oldpath to newpath 🔗 With -s, the link is a symbolic link. Without it, you get a hard link. ✨
• lpwd — prints your local working directory 📍
• ls [-1afhlnrSt] [path] — displays a remote directory listing of path, or the current directory if you don't give one 🗂️ path can use glob(7) characters and match multiple files. These flags are recognized and change how ls behaves:
  • -1 — single column output, one thing per line 📜
  • -a — lists files that start with a dot (.), so the hidden ones show up 👀
  • -f — doesn't sort the listing. The default sort is lexicographical, so this one turns it off 🙅‍♀️
  • -h — when used with a long format option, it uses unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte. It keeps the number of digits to four or fewer by using powers of 2 for sizes (K=1024, M=1048576, etc.) 📏
  • -l — shows extra details, including permissions and ownership info 🔍
  • -n — gives you a long listing where user and group info is shown as numbers instead of names 🔢
  • -r — reverses the sort order 🔄
  • -S — sorts the listing by file size 🏋️
  • -t — sorts the listing by last modification time ⏳
• lumask umask — sets your local umask to umask 🎭
• mkdir path — creates a remote directory at path 🌸
• progress — toggles the progress meter on or off 📊
• put [-afpR] local-path [remote-path] — uploads local-path and stores it on the remote machine ☁️ If you don't give a remote-path, it keeps the same name it had locally. local-path can use glob(7) characters and match multiple files. If it does and you give a remote-path, then remote-path has to be a directory 📁
  • -a tries to resume partial transfers of existing files ⏯️ Resumption assumes any partial copy of the remote file matches the local copy. If the local contents are different from the remote copy, the result is likely to be corrupt. 💀
  • -f sends a request to the server to call fsync(2) after the file has been transferred. This only works on servers that implement the "fsync@openssh.com" extension 🧃
  • -p copies over full file permissions and access times too 🔐⏰
  • -R copies directories recursively 🌳 sftp does not follow symbolic links during recursive transfers, same as with get 🦋
• pwd — displays the remote working directory 📍
• quit — quit sftp 👋 (yep, another one that does the same thing)
• reget [-fpR] remote-path [local-path] — resumes the download of remote-path. It's equivalent to get with the -a flag set 🔁
• reput [-fpR] local-path [remote-path] — resumes the upload of local-path. It's equivalent to put with the -a flag set 🔁
• rename oldpath newpath — renames a remote file from oldpath to newpath ✏️
• rm path — deletes the remote file at path 🗑️
• rmdir path — removes the remote directory at path 🫧
• symlink oldpath newpath — creates a symbolic link from oldpath to newpath 🔗
• version — displays the sftp protocol version 🔢
• !command — runs command in your local shell 🐚
• ! — escapes to your local shell 🏃‍♀️
• ? — a synonym for help 🙋‍♀️

---

✨ SEE ALSO ✨

ftp(1), ls(1), scp(1), ssh(1), ssh-add(1), ssh-keygen(1), ssh_config(5), glob(7), sftp-server(8), sshd(8) 📚

The SFTP protocol itself comes from T. Ylonen and S. Lehtinen, SSH File Transfer Protocol, draft-ietf-secsh-filexfer-00.txt, January 2001, which is listed as work in progress material 🧪

---

Ok that's the whole page, bestie! 🫶 It's the Debian version from December 6, 2024, and the manual page is SFTP(1), so you're all set 💖✨