Terminalwire makes it easier for web developers to build commmand-line applications for their web apps. It accomplishes this by streaming command-line I/O between a web server and client over WebSockets.

The Terminalwire client is a thin-client that users install on their workstation. It sends and recieves commands to and from the server to accomplish various command-line tasks like printing text to screen, launching a URL in the browser, or reading and writing files.

The Terminalwire Client connects to a Terminalwire Server over WebSockets. Once connected, the server is capable of issueing commands to the client to perform various tasks including reading and writing files, launching URLs in the browser, and printing text to the screen.

Terminalwire uses URL authorities to secure client workstations between different domains. This is similar to the way browsers secure cookies between different domains.

URL authorities are the domain name and non-standard port. For example, the URL https://example.com would resolve the authority example.com. The URL https://example.com:3000 would resolve the authority example.com:3000.

When the client connects to the server, it sends initialization message to establish and negotiate a connection. The client includes information about the opearating system version, Terminalwire client version, and protocol version to help the server determine how to best communicate with the client.

The server responds with a ready message to indicate that the client is ready to receive commands.

By default, the server does not have access to any resources on the workstation except for stdio, stdin, stderr and the ~/.terminalwire/authorities/$AUTHORITY/storage path, which is where cookies are stored by the server.

The client must grant the server permission to access resources on the workstation.

👮‍♂️ A future release of Terminalwire will include a permissions system that allows users to grant and revoke permissions with a terminalwire entitlement grant command.

The terminalwire.com is granted elevated entitlements by the client so it can perform installation, troubleshooting, and other administrative tasks on the client workstation. These entitlements are detailed in the Resources section below.

After the client sends the initialization message, the server then requests the following resources from the client:

• stdin: The standard input stream for the client.
• stdout: The standard output stream for the client.
• stderr: The standard error stream for the client.
• exit: The exit status of the client.
• browser: Launch a URL on the users workstation.
• file: The configuration file on the client used to store API credentails, session cookies, and other local configuration data for the endpoint.
• directory: Create, read, update, and check for existence of directories on client.

The client responds with messages on whether or not the resources are available. When all the devices are ready, the client & server can begin streaming commands between the resources.

The stdin, stdout, and stdin resources are part of the standard I/O streams. The client grants the server permission to read and write to these streams by default.

Terminalwire uses the files device to store API credentials, session cookies, and other local configuration data for the endpoint. These entitlements are implicitly granted by the client.

Files requires an entitlement to read and/or write files to a path on the client. The client must grant the server permission to read and/or write files to a path on the client with the exception of the ~/.terminalwire/authorities/$AUTHORITY/storage path, which is used to store API credentials, session cookies, and other local configuration data for the endpoint.

The terminalwire.com authority has an entitlement to the ~/.terminalwire/bin/** path by default to manage the installation, listing, and removal of Terminalwire apps.

API credentials, session cookies, and other local configuration data for the endpoint are stored in the files device on the client.

The terminalwire.com authority has an entitlement to the ~/.terminalwire/bin/** path by default to manage the installation, listing, and removal of Terminalwire apps. It also has an entitlement to shell initialization files in the ~ directory to aid users in appending the $PATH variable to their shell initialization file.

The client’s environment variables are not shared with the server by default, with the exception of the TERMINALWIRE_HOME path. This path is necessary to store API credentials, session cookies, and other local configuration data for the endpoint.

The client must grant the server permission to read and/or write environment variables.

The terminalwire.com authority has an entitlement to the PATH variable to manage the installation, listing, and removal of Terminalwire apps.

👮‍♂️ A future release of Terminalwire will further restrict this entitlement such that the server may only launch URLs on the client with the same authority as the server.

The Terminalwire server is capable of launching URLs on the client. By default, the client grants the server permission to launch http and https URLs on the client.