Terminalwire

Terminalwire streams terminal I/O between a web server and client over WebSockets. This means you can use your preferred command-line parser, like Thor, Rake, or OptParser, on Rails to deliver a delightful command-line application experience to your users.

Getting Started

Terminalwire is in private beta. This section illustrates how it will integrate with Rails apps when it’s released to the public. Terminalwire will be available for other popular web frameworks outside of Rails and Ruby.

Install Terminalwire

Add the Terminalwire Rails gem to your app.

$ bundle add terminalwire

Then install Terminalwire in your Rails app.

$ rails g terminalwire:install my-app

Configure the terminal

The rails g terminalwire:install my-app command creates files that you may configure for your application’s needs.

Thor command-line parser

The ./app/terminals folder has a application_terminal.rb that’s a Thor command-line parser.

# ./app/terminals/application_terminal.rb
class ApplicationTerminal < Thor
  # Replacs $stdio with Terminalwire's WebSocket IO streams.
  include Terminalwire::Thor

  # Name of your app's binary. Thor uses this to generate help messages.
  self.basename = "my-app"

  # It's always good to include a version for your CLI so users know what they're running.
  desc "version", "Prints the version of your app"
  def version
    puts "1.0.0"
  end

  # Example CLI application command that lists blog posts from a current user.
  desc "posts", "Prints a list of all blog posts"
  def posts
    current_user.posts.each do |post|
      puts post.title
    end
  end
end

Routes configuration

The ./config/routes.rb file mounts the ApplicationTerminal in a Terminalwire::Thor::Server WebSocket server to the /terminal endpoint. This is the URL your client will connect to.

# ./config/routes.rb
Rails.application.routes.draw do
  match '/terminal',
    to: Terminalwire::Thor::Server.new(ApplicationTerminal),
    via: [:get, :connect]
end

Terminalwire binary stub configuration

Terminalwire generates a binary stub in the Rails ./bin folder that you may use to interact with your application in a development environment. You may need to change the host if the server is running on a different port.

#!/usr/bin/env terminalwire-exec
url: "ws://localhost:3000"

To test the intergration, restart your Rails server, then run ./bin/my-app version in your terminal and you should see the following:

$ ./bin/my-app version
1.0.0

Going to production

Production distributions require a Terminalwire client license per endpoint.

1. Get a license.

   $ terminalwire client my-app.com/terminal
   The endpoint wss://my-app.com/terminal is not licensed.
   
   We'll email you a license agreement.
   
   What is your email address? me@example.com
   

   If you don’t have a license for this endpoint, Terminalwire will prompt you to request one. Licenses for non-commercial use are available at no cost.

2. Build a client.

   Once you have a license, Terminalwire will build the client binaries for the platforms you need.

   $ terminalwire client my-app.com/terminal
   Building terminalwire client for my-app.com/terminal. We'll email you when it's ready.
   Terminal wire clients are available for macOS, Windows, and Linux.
   

   When the build is done, we’ll send you a page with instructions onw how to download the client.

That’s it! When users run the terminal app, it streams input and output to the Terminalwire middleware running on your web server. Updates on the server are automatically reflected on the client side.