Quick Start Guide

This guide provides a practical, step-by-step walkthrough of transferring files between your local machine and a remote server using the trzsz toolchain.

Before you begin, ensure you have followed the Installation steps to place the trzsz wrapper on your local machine, and the trz/tsz binaries on your remote server.

Step 1: Connecting via the Wrapper

The fundamental concept of trzsz relies on the local wrapper (trzsz) monitoring the text stream of your remote session. Therefore, you must launch your SSH session through the trzsz command.

Open your local terminal and connect to your server:

trzsz ssh [email protected]

Behind the scenes: The trzsz command allocates a pseudo-terminal (PTY) and proxies your input and output. It watches the output stream for specific protocol signatures (e.g., ::TRZSZ:TRANSFER:R:1.2.0).

Pro-Tip: Enable Drag and Drop

To make uploads seamless, pass the -d (or --dragfile) flag when wrapping your SSH connection:

trzsz -d ssh [email protected]

Step 2: Uploading Files to the Server (`trz`)

You are now logged into your remote server. Let's upload a file from your local computer to the remote machine's /tmp directory.

Navigate to your desired remote directory:
```
user@remote:~$ cd /tmp
```
Execute the upload command:
```
user@remote:/tmp$ trz
```
Action Required: A native file selection dialog will pop up on your local computer's graphical interface. (This relies on tools like zenity on Linux, or native APIs on macOS/Windows).
Select the file(s) you wish to upload.
Once selected, you will see a text-based progress bar appear in your terminal, showing percentage, transferred bytes, transfer speed, and ETA.
```
my-local-file.zip [████████████████░░░] 85% | 85.0 MB | 10.5 MB/s | 00:02 ETA
```

The file is now securely transferred to the remote /tmp directory!

Step 3: Downloading Files to Local (`tsz`)

Now, let's reverse the process. Assume there is a log file on the remote server that you want to analyze locally.

Execute the download command, passing the file path as an argument:
```
user@remote:~$ tsz /var/log/syslog
```
Action Required: A directory selection dialog will open on your local computer. Choose the folder where you want to save the downloaded file (e.g., your local ~/Downloads folder).
The terminal will display the download progress bar. Once complete, you will find syslog in your local directory.

Step 4: Streamlining your Workflow (Aliases)

Typing trzsz -d ssh every time is tedious. The best practice is to set an alias in your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish).

Open your local shell configuration file and add:

# Wrap standard SSH with trzsz and enable drag-and-drop
alias ssh="trzsz -d ssh"

Reload your shell configuration (source ~/.bashrc). Now, whenever you type ssh user@server, you are automatically protected by the trzsz wrapper, and drag-and-drop is ready to go!

Common Pitfalls

Command Not Found: If you type trz and get command not found, you forgot to install the binaries on the remote server. Check the Installation guide.
Hanging / Freezing: If you type trz on the server and it prints a weird string like ::TRZSZ:TRANSFER:R:1.2.0:013... and hangs, this means you forgot to run the local trzsz wrapper before SSHing. Press Ctrl+C to cancel, exit the server, and reconnect using trzsz ssh ....