TYO Reach CLI reference
The TYO Reach desktop app is a single binary, tyoreach, that runs as a tray app when
started with no arguments and as a command-line tool when given a subcommand. The
CLI today covers one thing: Reach Sessions — hosting terminal
sessions and attaching to them from any of your devices — plus the Windows install flags.
Everything else (proxy on/off, browsers, gateways, Share this PC) is driven from the tray.
reach vs tyoreach
On Linux, the .deb/.rpm packages install /usr/bin/tyoreach and, from 1.9.54, a
reach symlink pointing at it — created only if nothing else already owns /usr/bin/reach,
and removed again on uninstall. reach host and tyoreach host are the same command.
On Windows and macOS there is no reach alias on your PATH. Use the full path:
| Platform | Binary |
|---|---|
| Linux (apt / dnf / zypper) | /usr/bin/tyoreach (alias /usr/bin/reach) |
| Windows, per-user install | %LOCALAPPDATA%\TYO Lab\TYO Reach\tyoreach.exe |
| Windows, all-users install | C:\Program Files\TYO Lab\TYO Reach\tyoreach.exe |
| macOS (notarized DMG) | /Applications/TYOReach.app/Contents/MacOS/tyoreach |
The examples across these docs use reach …; substitute the path above where needed.
Subcommands
| Command | What it does |
|---|---|
reach host [flags] | Host terminal sessions from this machine, headlessly (no tray click). |
reach sessions | List your online session hosts and the sessions on each. |
reach connect <session> / reach connect <host> <session> | Dial a host (peer-to-peer if same LAN, otherwise via the gateway) and attach in this terminal. |
reach attach --port P --session NAME | Low-level: attach to a local relay port the tray already dialed. Used internally by the tray's "Remote Machines" launcher. |
tyoreach --install / --install-user / --uninstall | Windows only — install to Program Files (elevated) or %LOCALAPPDATA% (no admin), or remove. |
Details and examples: Sessions commands and Windows install flags.
Sign-in comes from the tray
The CLI has no login command. It reads the credentials the tray app saved in your
system keyring, so sign in once via the tray on that machine first. If you haven't,
every subcommand exits with:
not signed in — sign in via the TYO Reach tray first
Environment variables
| Variable | Effect |
|---|---|
REACH_DEBUG=1 (also true, on, yes, all, *) | Verbose logging for every area. |
REACH_DEBUG=tunnel,ssm,iap,rdp | Verbose logging for specific areas only (comma-separated). tunnel covers the WebSocket/Trojan transport; ssm and iap cover AWS and Google Cloud remote-target tunnels. |
Logs go to the tray's log file; on Linux you'll also see them on stderr when running a subcommand from a terminal.
Exit codes
| Code | Meaning |
|---|---|
0 | Success — for connect/attach, includes a clean Ctrl-] detach. |
1 | Runtime error: not signed in, host offline, no matching session, dial failed. |
2 | Usage error (missing arguments). |
Common questions
Is there a reach --version?
Not yet. The version is shown at the top of the tray menu, and the tray log starts with
tyoreach <version> starting.
Can I turn the proxy on or off from the command line?
No — the proxy toggle, gateway selection and browser switches are tray-only today. The
local proxy ports (HTTP 127.0.0.1:8082, SOCKS5 127.0.0.1:1080) are only listening
while the tray has the proxy switched on.
Does the CLI work on Windows?
Yes. tyoreach.exe host, sessions, connect and attach all work from PowerShell or
cmd using the full path to the executable. Windows hosts serve fresh shells only — see
the Windows notes on Reach Sessions.