trzsz-go: Modern Terminal File Transfers

Welcome to the unofficial documentation for trzsz-go, the Go-based implementation of the trzsz protocol. trzsz-go makes all terminals that support a local shell natively support trzsz (trz / tsz).

At its core, trzsz is a simple, highly performant file transfer tool designed to replace legacy tools like lrzsz (rz / sz). It is engineered from the ground up to be completely compatible with tmux (including tmux Control Mode) and provides modern conveniences like drag-and-drop uploads and high-speed binary transfers.

⭐ Best Practice Recommendation: It is highly recommended to use the Go version of trzsz on your remote servers for receiving/sending, and trzsz-ssh (tssh) on your local computer for the ultimate, seamless client experience.

Why Choose trzsz?

If you regularly work with remote Linux or macOS environments via SSH, you likely need to move files back and forth. While scp and sftp are standard, they require opening a new terminal tab and re-authenticating. Legacy tools like rz/sz work over the active SSH session, but they corrupt your terminal when used inside terminal multiplexers like tmux.

trzsz-go solves these problems by offering:

  • Flawless tmux Compatibility: Works seamlessly within standard tmux sessions and tmux -CC (Control Mode). It intelligently parses terminal control sequences to ensure your UI never breaks during a transfer.
  • Intuitive Drag and Drop: Forget typing out long local file paths. Simply drag files and directories from your local file explorer and drop them directly into the terminal window to upload them to the remote server.
  • High Performance: Written purely in Go. It supports a dedicated binary transfer mode (-b) and maximum buffer scaling to provide massive throughput improvements over traditional Zmodem.
  • Directory Support: Unlike legacy tools, trzsz can transfer entire directory trees cleanly and recursively without requiring you to manually tar and untar archives.
  • Rich Progress Indicators: Features a beautiful, customizable, text-based progress bar indicating real-time transfer speed, accurate percentage, and Estimated Time of Arrival (ETA).
  • Zmodem Fallback: Native support for falling back to Zmodem (rz / sz) to ensure maximum backward compatibility with older tools or specific client environments.
  • Clipboard Integration: Allows the remote server to securely write data directly to your local clipboard utilizing OSC52 escape sequences.

When to Use trzsz-go

  • System Administrators: Rapidly pull logs from a remote server to your local machine for analysis without opening new SFTP sessions.
  • Developers: Push compiled binaries or configuration files to a staging environment directly through an active, tmux-multiplexed SSH connection.
  • DevOps Engineers: Automate server-side deployments by leveraging the trzsz Go API to build custom, file-transfer-aware SSH clients.

Architectural Overview

The trzsz-go project provides three primary executable commands that work together in a client-server model over standard standard input/output (stdio):

  1. trzsz (Local Wrapper): Prepend this to your SSH or shell command on your local machine (e.g., trzsz ssh my-server). It runs a background routine that intercepts the terminal output looking for specific trzsz protocol triggers while passing all normal shell interactions through untouched. See trzsz (Wrapper).
  2. trz (Remote Upload): Executed on the remote server to receive files from the local computer. It emits a trigger string that the local trzsz wrapper catches to open a file selection dialog. See trz (Upload).
  3. tsz (Remote Download): Executed on the remote server to send files to the local computer. It reads the files, chunks them, and sends them over the stdout stream to the local wrapper. See tsz (Download).

If you want to integrate trzsz into your own Go-based SSH client, trzsz-go also exposes a robust public Go API. Learn more in the Go API Reference.

Next Steps

Ready to get started? Head over to the Installation Guide to set up your environment, then jump into the Quick Start tutorial.