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

# Learn how to use Thor at http://whatisthor.com.
class ApplicationTerminal < Thor
  include Terminalwire::Thor

  def self.basename = "my-app"

  desc "hello NAME", "say hello to NAME"
  def hello(name)
    puts "Hello #{name}"
  end

  desc "login", "Login to your account"
  def login
    print "Email: "
    email = gets

    print "Password: "
    password = getpass

    if self.current_user = User.authenticate(email, password)
      puts "Successfully logged in as #{current_user.email}."
    else
      puts "Could not find a user with that email and password."
    end
  end

  desc "whoami", "Displays current user information."
  def whoami
    if self.current_user
      puts "Logged in as #{current_user.email}."
    else
      puts "Not logged in. Run `#{self.class.basename} login` to login."
    end
  end

  desc "logout", "Logout of your account"
  def logout
    session.reset
    puts "Successfully logged out."
  end

  private

  def current_user=(user)
    # The Session object is a hash-like object that encrypts and signs a hash that's
    # stored on the client's file sytem. Conceptually, it's similar to Rails signed
    # and encrypted client-side cookies.
    session["user_id"] = user.id
  end

  def current_user
    @current_user ||= User.find(session.fetch("user_id"))
  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

Terminalwire can be distributed through the Terminalwire command-line application via terminalwire install <my-app>.

1. Install the Terminalwire CLI.

   $ gem install terminalwire
   

2. Add the Terminalwire binary path to your $PATH environment variable by adding the following to your ~/.bashrc file (or equivalent).

   # Add to your ~/.bashrc, ~/.zshrc, ~/.shrc, or equivalent file.
   export PATH=$HOME/.terminalwire/bin:$PATH
   

3. Sign up for a Terminalwire account.

4. Create a new Terminalwire application entry with the following information:

   • Name - The name of the application, like “My App”
   • URL - The URL where your Terminalwire application can be accessed. Likely at wss://example.com/terminal.
   • Binary Name - The command people will run to execute your application, like my-app.
   • Description - A brief overview of your app that’s displayed in terminalwire apps.

5. Install the Terminalwire app.

   $ terminalwire install my-app
   

6. Run the app.

   $ my-app
   

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