In-Depth Usage Guide

While the Quick Start covers the basics, trzsz-go offers powerful capabilities for advanced workflows, complex architectures, and specialized terminal environments. This guide details how to leverage these features.

1. Using `trzsz` with Jump Servers (Relay Mode)

In many enterprise environments, you cannot SSH directly into your target server. Instead, you must first connect to a jump server (bastion host) and then initiate a second SSH session to the final destination.

If you run tmux on that jump server, the terminal control sequences used by trzsz can get swallowed or corrupted. To solve this, trzsz provides a Relay Mode.

The Relay Workflow

Local Machine: Connect to the jump server using the standard wrapper.
```
trzsz ssh jump_user@jump_server
```
Jump Server: Start or attach to your tmux session.
```
jump_user@jump:~$ tmux new -s deployment
```
Inside Tmux (on Jump Server): Use the --relay flag when initiating the final SSH connection.
```
jump_user@jump:~$ trzsz --relay ssh final_user@target_server
```

Why is this necessary? The --relay mode tells the trzsz instance running on the jump server to actively listen for trzsz signatures coming from the target_server. Instead of trying to process the file transfer locally on the jump server, the relay encapsulates the data and passes it safely through tmux back to your local machine.

2. Mastering Drag and Drop

The drag-and-drop feature allows you to upload files seamlessly by dragging them from your operating system's file manager directly into the terminal window.

Enabling Drag and Drop

Start your local wrapper with the -d or --dragfile flag:

trzsz --dragfile ssh remote_server

How it Works

When you drag a file into a terminal, the terminal emulator pastes the absolute path of the file (e.g., /Users/name/Desktop/file.txt). The trzsz wrapper intercepts this input. If it detects valid file paths, it silently sends the trz command to the remote server to initiate the upload phase automatically.

Overwriting Existing Files

By default, drag-and-drop executes trz on the remote server. If a file with the same name exists, it will fail or rename the file to avoid data loss. If you want drag-and-drop to always overwrite, configure the DragFileUploadCommand in your local ~/.trzsz.conf:

DragFileUploadCommand = trz -y

Terminal-Specific Quirks

Windows cmd / PowerShell: These consoles often only support dragging one file at a time. Dragging multiple files may result in only the one directly under the mouse cursor being processed.
Windows Terminal: You must drag the files specifically to the top left corner of the pane, waiting until the UI displays "Paste path to file" before releasing the mouse button.
Windows Administrator Mode: Running a terminal "As Administrator" modifies User Account Control (UAC) privileges, which often blocks drag-and-drop events from a standard-privilege Windows Explorer window.

3. Zmodem (`rz` / `sz`) Fallback Support

While trzsz protocol is vastly superior, you may interact with legacy systems, embedded devices, or network switches that only support traditional lrzsz (Zmodem) transfers.

trzsz can automatically detect Zmodem initialization signatures and handle the transfer seamlessly, acting as a modern frontend for lrzsz.

Enabling Zmodem

Use the -z or --zmodem flag on your local client:

trzsz --zmodem ssh remote_server

When you run rz or sz on the remote server, trzsz will catch it and execute the transfer.

Requirements

For this fallback to work, the legacy lrzsz package must be installed on your local machine (the computer running the wrapper).

macOS: brew install lrzsz
Ubuntu/Debian: sudo apt install lrzsz

Caveat for Windows Users: The --zmodem flag is generally incompatible with native Windows command prompts due to raw PTY IO handling. If you require Zmodem on Windows, you should transition to using the tssh (trzsz-ssh) binary instead.

4. Clipboard Integration (OSC52)

Modern terminal emulators support a control sequence called OSC52, which allows a remote host to write data securely directly into your local operating system's clipboard.

Enabling OSC52

Enable clipboard integration using the -o or --osc52 flag:

trzsz -o ssh remote_server

When active, any text the remote server formats using the OSC52 escape sequence will be caught by trzsz and placed in your local clipboard.

Requirements for Linux Desktop

If your local machine runs a Linux Desktop environment (e.g., GNOME, KDE), trzsz relies on underlying X11/Wayland clipboard utilities. You must install either xclip or xsel:

sudo apt install xclip

5. Dealing with Windows Environments

Windows consoles (Command Prompt, PowerShell) handle pseudo-terminals differently than Unix-like systems. If you use tools like MSYS2, Cygwin, or Git Bash, you must account for these differences.

The `Invalid Handle` Error

If you see The handle is invalid when starting trzsz inside MSYS2 or Git Bash, it means the wrapper cannot allocate the virtual terminal. You must prefix the command with winpty.

winpty trzsz ssh user@server

(Note: winpty is pre-installed in Git Bash. In MSYS2, you may need to run pacman -S winpty).

SSH Binary Compatibility

trzsz may fail to transfer files if you use the /usr/bin/ssh binary provided natively by MSYS2 or Cygwin, as they abstract file descriptors in a way trzsz cannot hook into. You should explicitly invoke the native Windows OpenSSH executable:

MSYS2 Example: winpty trzsz /c/Windows/System32/OpenSSH/ssh.exe user@server
Cygwin Example: trzsz "C:\Windows\System32\OpenSSH\ssh.exe" user@server