tsz Command Reference
The tsz command is the sending agent. It is executed on the remote server to push files from the server down to your local machine.
When executed, it reads the requested files, chunks the data, and streams it to stdout. The local trzsz wrapper catches this stream, opens a directory selection dialog (unless DefaultDownloadPath is configured), and reconstructs the files locally.
Syntax
tsz [options] file [file ...]file: One or more file or directory paths on the remote server that you wish to download. Unliketrz, this argument is required.
Command-Line Options
| Flag | Long Flag | Description | Trade-offs & Notes |
|---|---|---|---|
-h |
--help |
Show the help message and exit. | - |
-v |
--version |
Show the version number and exit. | - |
-q |
--quiet |
Quiet mode. Suppresses the progress bar. | Useful for automated scripts running on the server. |
-y |
--overwrite |
Overwrite existing local files. | If omitted, the local wrapper will automatically rename downloaded files to prevent data loss (e.g., file.txt becomes file.txt.1). |
-b |
--binary |
Force binary transfer mode. | Faster, but can be corrupted by overzealous terminal multiplexers filtering stdout. |
-e |
--escape |
Escape all known control characters. | Trades a small amount of speed for a massive increase in stream reliability. |
-d |
--directory |
Enable downloading entire directories. | Packages the directory recursively. Required if a target argument is a folder. |
-r |
--recursive |
Same as -d. |
Provided for parity with Unix conventions. |
-f |
--fork |
Fork the transfer process into the background. | Implies -q. Returns control of the remote shell to you while the download completes silently. |
-B N |
--bufsize N |
Set the max buffer chunk size. | Accepts K, M, or G suffixes. Default is 10M. |
-t N |
--timeout N |
Timeout in seconds for each buffer chunk. | Default is 20. Set to 0 to disable timeouts for highly erratic connections. |
-c TYPE |
--compress TYPE |
Set compression behavior. | Options: yes, no, auto. Default is auto. Reduces bandwidth usage for text/log files using zstd. |
Common Use Cases & Examples
1. Download a Single File Pull a configuration file down to your local machine.
tsz /etc/nginx/nginx.conf2. Download Multiple Files Pull several distinct files in a single operation.
tsz /var/log/syslog /var/log/auth.log3. Download a Full Directory
Download a directory tree. The -d flag is required; otherwise, tsz will reject the directory path.
tsz -d /var/www/html/images/4. Background Download Initiate a large database dump download, but return control of the terminal to the user immediately so they can continue working.
tsz -f database_dump.sql.gz5. Safe Transfer over Unstable Telnet/Serial
If you are using trzsz over a flaky serial console or a nested telnet connection where raw bytes might be dropped, force character escaping.
tsz -e /var/log/dmesg