rTerm CLI

The rTerm CLI connects to rTerm Agents and provides a remote terminal session. This terminal session is the same as any other ssh connection and allows a full terminal experience.

Installation

Ubuntu/Linux (x64)

Run the following command from the terminal and it will create a ~/rterm directory with all dependencies:

curl https://t.rterm.io/dist/rterm-cli/linux-x64/install.sh | bash

MacOS

Run the following command from the terminal and it will create a ~/rterm directory with all dependencies:

curl https://t.rterm.io/dist/rterm-cli/macos/install.sh | bash

Raspberry PI

Run the following command from the terminal and it will create a ~/rterm directory with all dependencies:

curl https://t.rterm.io/dist/rterm-cli/pi4/install.sh | bash

Docker

Follow OS instructions.

Windows

Are you interested in rTerm Agent for Windows? Let us know!

Usage

Prerequisites

Before any connections can be made, the rTerm CLI needs access to a private key to sign requests sent by the Agent. Use the following enironment variables to set the path with the private key:

RTERM_PRIVATE_KEY_PATH: Provide the full path the private key file. Example ~/.ssh/id_rsa. This can be any private key with a corresponding public key.

RTERM_SSH_PASSPHRASE: (optional) If the provided private key has a passphrase, use this variable to provide the passphrase to rTerm when autheicating.

RTERM_SETTINGS_FILE_PATH: (optional) Provide a path to the rTerm Settings file. This file can point to the Private Key and any Passphrase. See rTerm Settings below for more details.

Running rTerm CLI

To run the rTerm CLI the first time, run rterm-cli --sessionId <sessionId> from your teminal. The Session Id is provided by the rTerm Agent when it starts. Assuming the Session Id is valid and the public/private keys are also valid, then a remote terminal session will start.

Running rTerm CLI without Session Id

Running rterm-cli alone will provide a list of trusted devices. Once the list appears, enter the number you would like to connect to and press Enter. After valid key authentication a remote terminal session will start.

All Flags

To pass values to flags, use the following syntax:

--flagName flagValue

Connection Flags

Flags useful for connecting to rTerm Agents.

--sessionId: Connect to rTerm Agent using a specific Session Id.

--showDeviceId: Show the unique device id of the rTerm CLI client. This id can be added to a .trustedDevices file for the rTerm Agent.

--hostname: The hostname of the server running the rTerm Agent. The rTerm CLI will try and find online [trusted] devices based on the hostname provided.

--peerDeviceId: The unique device id of the rTerm Agent to connect to.

Execute remote commands

--execCommand: The remote command to execute on the remote server. Example: --execCommand apt update && apt upgrade -y.

Transfer Files

Send or receive files from the remote server.

--transferFile: This flag takes a string with the following items "l:[localpath]r:[remotepath] [direction]. Direction is local-to-remote by default, but rl will change to remote-to-local.

Example:

`--transferFile l:/path/to/localfolder r:/path/to/remote/folder lr:rl

Port Fowarding

--portFoward: Provide the local and remote ports to link. Syntax local:remote. Example: --portForward 8080:8080

Link Remote Folders

--linkRemoteFolder: The local and remote folders to link. The rTerm CLI agent will watch the local folder and send any changes, updates to the remote server.

--ignoreInitialWatchItems: Tells the rTerm CLI agent to only send file changes, not all files in the local folder to the remote server.

--watchEvents: Provide the file change events to watch before sending files to the remote server. The default value is "add;change;".

--hotReload: Tells rTerm CLI to setup a Websocket server to send updates to when the file events trigger. This is useful for web development to reload the browser when files are saved/changed or added. A port number can be provided as a value to this flag; port 8888 is default when no value is provided.

Additional Flags:

--waitForDevice: Tells the rTerm CLI to wait for the rTerm Agent to come online. By default the rTerm CLI will timeout after 30 seconds, but this flag will prevent that action. This flag does require that --hostname or --sessionId is provided.

--noStdin: Prevents the standard Stdin connection on the rTerm Agent.

Advanced

rTerm Settings File

An rTerm Settings file can be provided to rTerm CLI for private key location and any passphrase required. The file is .json format and looks like this:

{
  "RTERM_PRIVATE_KEY_PATH": "<path-to-private-key",
  "RTERM_SSH_PASSPHRASE": "<private-key-passphrase"
}

Once the file is created, use the RTERM_SETTINGS_FILE_PATH to provide the path to the rTerm CLI. For long term use, this can be put in the .bashrc file or equivalent.

Find Device Id

If you would like to populate .trustedDevies on the rTerm Agent, then having the rTerm CLI Device Id is necessary. To find your Device Id, run rterm-cli ----showDeviceId.

To generate a new Device Id, delete the file a restart rTerm CLI, a new id and file will be created.