z, ?	toggle help (this)
space, →	next slide
shift-space, ←	previous slide
d	toggle debug mode
## <ret>	go to slide #
r	reload slides
n	toggle notes

loading presentation...

Hello everyone! I'm super happy to be here to talk about using a thin CLIent approach to build command line interfaces that interact with web services.

The

Thin

CLIent

Approach

2025 San Francisco Ruby Conference

My name is Jeremy Evans. I'm a Ruby committer. I'm also the maintainer of Sequel, Roda, Rodauth, and many other gems.

GitHub: jeremyevans

Twitter: @jeremyevans0

I am a principal software engineer at Ubicloud. We are building an open source alternative to Amazon Web Services.

@

Since shortly after Ubicloud was founded in 2023, it supported provisioning resources such as virtual machines using both a browser interface and an API.

Web

API

@

Earlier this year, we decided to add a command line interface that used that API, so users can do things like add and remove virtual machines from the command line, without any custom programming.

Web

API

CLI

@

I was assigned responsibility for implementing the command line interface. While I've written numerous command line programs in my career, I had not yet written one that was nearly as large as the intended scope.

CLI

One way to create such a command line program is to use what I'll call the traditional approach.

Traditional

Approach

Here's what the traditional approach looks like.

In this diagram, client is the command line program running on the user's machine.

And target is the API endpoint the client needs to send the request to.

When you run the client, it processes the array of arguments, determines what type of request is being made, and determines the target endpoint to contact.

After determining the endpoint to contact, the client prepares the body of the request, assuming the request needs a body. Then it sends the request to the target endpoint.

The target endpoint handles the request and performs the appropriate action,

and then returns a response in json format.

The client parses the json response, and formats the text to display to the user.|So this is what the traditional approach looks like when creating a command line interface to interact with web services.

I think the biggest advantage of the traditional approach

Advantage

is that it is simple. There are only two parts involved, the client and the target endpoint. All else being equal, simpler solutions are better than more complex solutions.

Simple

However, all else is not equal in this case, as there are some significant disadvantages to the traditional approach.

Disadvantages

I think the main disadvantage when using the traditional approach is that if you add a new API feature, such as a new target endpoint,

the client running on the user's machine cannot use it. The user would need to update their client to a version that supports the new API feature. Forcing users to update their client to use new API features results in increased friction.

One approach to addressing this disadvantage is to use an auto-updating program. However, this adds complexity and opens up security issues for users, and many users would not want a command line program like this to auto-update.

Auto

Update?

With the traditional approach, you lose the primary advantage of web-based software development over traditional software development, which is as soon as you put a new feature into production, it is immediately usable by users of the web site.|Now, imagine if every time you added a feature to your website, you had to have your users update their browser in order to use it. Preposterous, right? And yet, that's basically what the traditional approach requires.

No

Instant

Deployment

The other, less important disadvantage is in error handling. With the traditional approach, errors that occur in parsing the command line arguments, building the request body, and parsing the response from the target endpoint all occur on the user's machine. You have to hope the users report the errors.

Error

Handling

You can have errors auto reported, but many users are against that kind of telemetry, and there can always be bugs in the auto reporter that prevent notifications about the errors.

Auto

Report

Errors?

Now that I've discussed the traditional approach,

Traditional

Approach

let's examine the thin CLIent approach, and see how it compares.

Thin

CLIent

Approach

Here's what the thin CLIent approach looks likes.

The client in this diagram is still the command line program, and the target is still the API endpoint.

The thin CLIent approach introduces the idea of the gateway endpoint. Most of the logic that is in the client program in the traditional approach is performed by the gateway endpoint in the thin CLIent approach.

With the thin CLIent approach, the client doesn't even parse the array of arguments it receives. Instead, it formats them as a json array, and sends a POST request to the gateway endpoint with that json array in the request body.

The gateway endpoint is a single HTTP route that accepts a JSON array of strings, which are the command line arguments passed to the client. The gateway endpoint parses this JSON array and determines the target endpoint to contact.

The gateway endpoint formats a request body if needed and then sends the request to the target endpoint.|There is no requirement that the gateway endpoint be running in the same process as the target endpoint, though they are in Ubicloud's case. In Ubicloud's implementation, instead of sending an HTTP request to the target endpoint, the gateway endpoint calls the target endpoint Rack application directly with a rack environment hash.|However, you could easily implement a gateway endpoint that ran on a different machine and contacted the target endpoints using HTTP requests.

The target endpoint does the same processing it did previously. There is no difference in how the target endpoint handles requests.

There is also no difference in the json response returned by the target endpoint. No changes to the target endpoint are needed when introducing the thin CLIent approach. The gateway endpoint is operating as a normal client from the perspective of the target endpoint.

Instead of the client parsing the json response and formatting it, the gateway parses the json response and formats it as a plain text response that is suitable for the client to print directly.

The gateway then sends the plain text response to the client program.

All the client needs to do is print that preformatted text response to the standard output, or if the HTTP response status indicates there was an error, to the standard error.

Because the client does so little when using the thin CLIent approach, it can be very small. It only needs to know how to submit an HTTPS request, how to format JSON, and how to print to the standard output or standard error.|It doesn't need to know how to parse JSON or how to format the text to be printed. It does not need to have any logic specific to the api being contacted. It just prints the response body to the terminal.|A minimal thin CLIent in Ruby could probably be under 50 lines, and probably under a couple hundred lines in a lower level language.

Almost all logic that was in the client in the traditional approach is moved to the gateway endpoint in the thin CLIent approach. This is what gives the thin CLIent approach its advantages.

The main advantage is instant deployment. When adding a new target endpoint, you can update the gateway endpoint to allow CLI access to the new target endpoint at the same time. Users can use the new CLI features without updating their client program. This brings the advantages of web deployment to command line interfaces.

Instant

Deployment

Most non-network errors that occur in the client program in the traditional approach instead occur on the gateway endpoint in the thin CLIent approach.|This is better, because the gateway endpoint is running on a server you control, and you can record and process any exceptions raised by the gateway endpoint in the same manner you would handle any errors that occur during server-side processing.

Error

Handling

As the client is small, it is simple to port to other languages. This is useful, because in general it is best to provide dependency-free static executables to users, and not all languages make that easy.|If all of the logic has to be in the client, you have a tough choice between wanting to use a friendly language for that logic, versus needing to use a language that can build dependency-free static executables.

Small

Client

Because all of the logic moves from the client to the gateway endpoint, you can implement the logic in the same language that you use to implement the target endpoints, which for Ubicloud, and I assume for most of you, is Ruby.|When you consider command line argument parsing, determining the target endpoints, handling responses from the target endpoints, and formatting those responses into plain text, I think it's vastly more preferable to use Ruby for those things than it would be to use a lower-level language that makes it easy to build dependency-free static executables.

Use

Ruby

A small advantage of the thin CLIent approach is less latency if the command requires accessing multiple target endpoints. With the traditional approach, if the client needs to send multiple requests to separate target endpoints, where the output of the first target endpoint is necessary to determine the next target endpoint, each of those requests could have significant latency.|With the thin CLIent approach, the client only needs to make a single request to the gateway endpoint, and gateway endpoint handles the internal requests to the target endpoints. In general, the gateway has much less latency to the target endpoint than the client does, so any requests that require multiple target endpoints generally have lower overall latency with the thin CLIent approach.

Less

Latency

The flip side of this is that since there is no logic on the client, all program executions require a request to the gateway endpoint. This includes commands for help or to get the program version. In the traditional approach, the client can provide the expected output without submitting a request, but when using the thin CLIent approach, it requires a request.|Additionally, if a command requires confirmation, the traditional approach can ask for the confirmation up front, before submitting a request, while the thin CLIent approach requires multiple requests, since the server must respond to the original request asking for confirmation.

Latency

If the client needs to execute external programs, you have other issues to consider.

Program

Execution

For example, Ubicloud's client supports executing ssh, sftp, and scp to connect to created virtual machines.

Program

Execution

VMs: `ssh sftp scp`

It also supports executing psql, pg_dump, and pg_dumpall to connect to created PostgreSQL databases.

Program

Execution

VMs: `ssh sftp scp`

PostgreSQL: `psql pg_dump pg_dumpall`

When executing external programs based on a server response, you cannot trust the server.

Program

Execution

Security

If the server tells the client to delete all files in the user's home directory, you don't want the client to do that.

Program

Execution

`rm -rf ~/* ~/.*`

Safe external program execution requires deviating from a pure thin CLient approach, and implementing API-specific logic in the client.|The majority of logic in Ubicloud's CLI program deals with checking the program and arguments the server is asking the client to execute.

Program

Execution

Checks

In order to execute an external program, Ubicloud's client requires the program name to exactly match one of these 6. It also requires that the program name requested by the server be one of the command line arguments passed to the client, so there is a clear indication the user running the client is expecting external program execution.

Program

Ruby

We want to provide the user a dependency-free static executable. While Ruby is great at a lot of things, building dependency-free static executables is not one of them.

Dependency-free

Static

Executables

That may be changing in the future due to Tebako, a recently developed packaging tool. However, packaging Ruby applications with Tebako produces relatively large executables, and using Tebako requires some other restrictions that make it suboptimal for our usage.

Tebako

Now, while the standard Ruby implementation is not good at building dependency-free static executables, mruby allows you to compile your Ruby code to C, and then build a dependency-free static executable using a C compiler.|This static executable will embed the mruby virtual machine to execute the Ruby code, but from a user perspective, it is similar to other static executables, and it does not require any dependencies installed on the user's machine.

mruby

Unfortunately, I quickly found that while mruby is for the most part syntax compatible with Ruby, it is not library compatible with Ruby. There is no require, and the net/http and json libraries are not standard libraries in mruby.

mruby

≠

Ruby

For json, I found an mruby-json library, which worked fine and was API compatible for my usage.

mruby-json

Replacing net/http was slightly more challenging, but after trying a couple mruby libraries, I did get mruby-curl to work. It is not API compatible with net/http, so it required some code changes, but they weren't extensive.

mruby-curl

When building an executable that embeds mruby, the recommended approach is to use mrbc with -B to compile your Ruby code to mruby bytecode that is stored in a C array. Then you write a small C program that sets up the mruby virtual machine, and then has the virtual machine execute the bytecode stored in the C array. Then you use a C compiler to compile that C program. As long as you tell the C compiler to compile a static executable, you should end up with a dependency-free static executable.

mrbc -Bsym file.rb

However, that didn't work on my system, because I didn't have static libraries for libcurl or libssl installed. It would likely have worked if I did, but I realized something before trying that.

mruby-curl

We didn't just want a dependency-free static executable for the operating system and platform I was running. We wanted dependency-free static executables for all common operating systems and platforms. What we really wanted,

Dependency-free

Static

Executables

was cross compiled dependency-free static executables. Because when building 7 separate executables to provide to users, it's much simpler to cross compile them from a single machine than it is to maintain 7 separate build machines.

Cross Compiled

Dependency-free

Static

Executables

Doing that with mruby-curl would require building cross compilation environments for libcurl and libssl. Not having significant experience in cross compiling C code, and honestly not eager to get experience with it, I decided to try other another language that supports cross compilation as a built-in feature.

No Segfault!

Additionally, the test suite ran 30x faster with the Go version than with the prototype Ruby version, mostly due to avoiding Ruby startup overhead.

Ruby →

Go

30x Faster

Command Line

Argument

Parsing

Here are examples of the type of commands we want to support.


ubi help [options] [command [subcommand]]
ubi pg list [options]
ubi pg (location/pg-name | pg-id) add-firewall-rule cidr
ubi pg (location/pg-name | pg-id) add-metric-destination username password url
ubi pg location/pg-name create [options]
ubi pg (location/pg-name | pg-id) delete-firewall-rule rule-id
ubi pg (location/pg-name | pg-id) delete-metric-destination md-id
ubi pg (location/pg-name | pg-id) destroy [options]
ubi pg (location/pg-name | pg-id) [options] pg_dump [pg_dump-options]
ubi pg (location/pg-name | pg-id) [options] pg_dumpall [pg_dumpall-options]
ubi pg (location/pg-name | pg-id) [options] psql [psql-options]
ubi pg (location/pg-name | pg-id) reset-superuser-password new-password
ubi pg (location/pg-name | pg-id) restart
ubi pg (location/pg-name | pg-id) restore new-db-name restore-time
ubi pg (location/pg-name | pg-id) show [options]

We want to support top-level commands, mainly for easy help output. Each command needs to be able to support options and either a fixed or variable number of arguments.


ubi help [options] [command [subcommand]]
ubi pg list [options]
ubi pg (location/pg-name | pg-id) add-firewall-rule cidr
ubi pg (location/pg-name | pg-id) add-metric-destination username password url
ubi pg location/pg-name create [options]
ubi pg (location/pg-name | pg-id) delete-firewall-rule rule-id
ubi pg (location/pg-name | pg-id) delete-metric-destination md-id
ubi pg (location/pg-name | pg-id) destroy [options]
ubi pg (location/pg-name | pg-id) [options] pg_dump [pg_dump-options]
ubi pg (location/pg-name | pg-id) [options] pg_dumpall [pg_dumpall-options]
ubi pg (location/pg-name | pg-id) [options] psql [psql-options]
ubi pg (location/pg-name | pg-id) reset-superuser-password new-password
ubi pg (location/pg-name | pg-id) restart
ubi pg (location/pg-name | pg-id) restore new-db-name restore-time
ubi pg (location/pg-name | pg-id) show [options]

We want to support subcommands, and have the same ability for subcommands that we have for commands.


ubi help [options] [command [subcommand]]
ubi pg list [options]
ubi pg (location/pg-name | pg-id) add-firewall-rule cidr
ubi pg (location/pg-name | pg-id) add-metric-destination username password url
ubi pg location/pg-name create [options]
ubi pg (location/pg-name | pg-id) delete-firewall-rule rule-id
ubi pg (location/pg-name | pg-id) delete-metric-destination md-id
ubi pg (location/pg-name | pg-id) destroy [options]
ubi pg (location/pg-name | pg-id) [options] pg_dump [pg_dump-options]
ubi pg (location/pg-name | pg-id) [options] pg_dumpall [pg_dumpall-options]
ubi pg (location/pg-name | pg-id) [options] psql [psql-options]
ubi pg (location/pg-name | pg-id) reset-superuser-password new-password
ubi pg (location/pg-name | pg-id) restart
ubi pg (location/pg-name | pg-id) restore new-db-name restore-time
ubi pg (location/pg-name | pg-id) show [options]

We also want an approach where subcommands can follow command arguments. This allows the user to think about the object being modified, and then the action to take on that object, which in many cases is more natural than thinking about what action to take and then thinking about which object to perform the action on. I consider this a more object-oriented command line style.


ubi help [options] [command [subcommand]]
ubi pg list [options]
ubi pg (location/pg-name | pg-id) add-firewall-rule cidr
ubi pg (location/pg-name | pg-id) add-metric-destination username password url
ubi pg location/pg-name create [options]
ubi pg (location/pg-name | pg-id) delete-firewall-rule rule-id
ubi pg (location/pg-name | pg-id) delete-metric-destination md-id
ubi pg (location/pg-name | pg-id) destroy [options]
ubi pg (location/pg-name | pg-id) [options] pg_dump [pg_dump-options]
ubi pg (location/pg-name | pg-id) [options] pg_dumpall [pg_dumpall-options]
ubi pg (location/pg-name | pg-id) [options] psql [psql-options]
ubi pg (location/pg-name | pg-id) reset-superuser-password new-password
ubi pg (location/pg-name | pg-id) restart
ubi pg (location/pg-name | pg-id) restore new-db-name restore-time
ubi pg (location/pg-name | pg-id) show [options]

When using this style, we want to be able to provide options between command arguments and subcommands, so that subcommands can share option parsing.


ubi help [options] [command [subcommand]]
ubi pg list [options]
ubi pg (location/pg-name | pg-id) add-firewall-rule cidr
ubi pg (location/pg-name | pg-id) add-metric-destination username password url
ubi pg location/pg-name create [options]
ubi pg (location/pg-name | pg-id) delete-firewall-rule rule-id
ubi pg (location/pg-name | pg-id) delete-metric-destination md-id
ubi pg (location/pg-name | pg-id) destroy [options]
ubi pg (location/pg-name | pg-id) [options] pg_dump [pg_dump-options]
ubi pg (location/pg-name | pg-id) [options] pg_dumpall [pg_dumpall-options]
ubi pg (location/pg-name | pg-id) [options] psql [psql-options]
ubi pg (location/pg-name | pg-id) reset-superuser-password new-password
ubi pg (location/pg-name | pg-id) restart
ubi pg (location/pg-name | pg-id) restore new-db-name restore-time
ubi pg (location/pg-name | pg-id) show [options]

There are numerous Ruby libraries dedicated to parsing command line arguments, and I did a review of the most popular ones to determine whether they would meet our needs.

Command Line

Argument

Parsing

Libraries

Two popular libraries, commander and gli, appeared to support commands but not subcommands.

commander

gli

dry-cli supports both commands and subcommands. However, it didn't appear to be support options between commands and subcommands, or subcommands after command arguments.

dry-cli

Thor is the most popular command line argument processor for Ruby, and it supports both commands and subcommands, and supports option parsing at each level. However, it did not appear to support subcommands after command arguments.

thor

So I did what any self-respecting programmer does when they cannot find a library to do what they need, and wrote my own argument parsing library.

DIY

Parsing command line arguments is in many ways similar to parsing paths for web requests, and I have a lot of experience doing that in Roda. I originally played around with writing the argument parsing library as a Roda plugin. While it worked, it was suboptimal, mostly because it is expensive to build the option parsers per request. That is a problem you don't have when parsing paths.

Roda

I ultimately ended up building a Roda-ish library to handle the argument parsing. This allows for a separation of the static and dynamic parts of parsing command line arguments.|The static parts would be the help text and option parser. The dynamic parts would be handling the parsed options and command arguments, and returning results or calling subcommands.

Roda-ish

This library was originally developed as part of Ubicloud, but earlier this year, it was released as a separate library named rodish. In addition to being Roda-ish, the sh part of the name indicates it is related to the command line.

Rodish

Let's look at a rodish Hello World.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

Rodish is designed to be installed into an existing class. Instances of this class serve as the context for the argument parsing.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

Installing rodish into a class requires calling Rodish.processor with that class.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

Starting a new argument parse is done by calling the process class method with the array of arguments. This creates a new instance of CliExample that will be used for the argument parsing.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

The class-level on method sets up the root of the command parsing. If you don't have separate commands or subcommands, you can use the root command to handle all argument parsing. The block to on is executed in the context of the root command, and is used for configuring the command.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

The run method sets the code to be executed when this command is run. The block is executed in the context of the CliExample instance that was created in the CliExample.process call.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

So if you run this program with no arguments, it will print Hello World.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb
Hello World!

Let's add support for a command named hello. This will allow us to say hello to a specific person.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

This command will accept 1 argument, instead of the default of 0 arguments.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

This subcommand will have its own run block, which will be called when the subcommand is executed.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)

We can run the program with hello and Jeremy as the arguments.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb hello Jeremy

The root command will dispatch to the hello subcommand, because the first argument is hello.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb hello Jeremy

The remaining command line argument is Jeremy, which is yielded to the hello command's run block.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb hello Jeremy

So this will print Hello Jeremy. You can nest subcommands inside commands, with no limit on the depth of nesting. However, this doesn't show the unique feature of Rodish, which is subcommands after command arguments.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb hello Jeremy
Hello Jeremy!

Let's change this to support an object-oriented style, where you pass the object to operate on, before the action to take on the object.


require 'rodish'

class CliExample
  Rodish.processor(self)

  on do
    on "hello" do
      args 1
      run do |person|
        puts "Hello #{person}!"
      end
    end

    run do
      puts "Hello World!"
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

Here's what that looks like.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

We start with loading the post_commands plugin. Rodish, like Roda, Rodauth, and Sequel, ships with many plugins. Not all programs need to support this object-oriented style, so it is included in a plugin that ships with Rodish, instead of being part of the core Rodish functionality.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

The hello command now uses run_on instead of on. This will register it as a post subcommand and not a normal subcommand.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

Because post subcommands may support both options and arguments, when using post subcommands, you generally want to accept a range of arguments. Typically, you would require at least two, the first to specify the object to operate on, the second to specify the subcommand name.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

As you allow a range of arguments and not a fixed number of arguments, the arguments are yielded to the run block as an array.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

The options argument would be the options hash parsed by the option parser. There are no options for this command,


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

but in general you pass the same options hash from commands to subcommands, and the option parsing supports disambiguating which command the options came from.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

The final argument is the command object,


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

which will be used to dispatch to subcommands.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

In this case, we take the first command line argument and assign it to an instance variable.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

Then we dispatch to the post subcommands.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

As the subcommand given was hello, this will dispatch to the hello post subcommand.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

This run block is executed in the same context as the run block for the root subcommand,


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

so it can use the instance variable already defined. So this will print Hello Jeremy.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)


$ ruby cli-example.rb Jeremy hello
Hello Jeremy!

The key advantage is really this line. Using this approach, you can share logic easily, so that you don't need to repeat the logic in each subcommand. This brings the primary benefit of Roda's routing tree to command line argument parsing.|I don't have time to do a deeper dive into Rodish in this presentation, but hopefully you can see that Rodish is low ceremony and quite flexible. You may want to consider it if you are building a command line application.


require 'rodish'

class CliExample
  Rodish.processor(self)
  plugin :post_commands

  on do
    run_on "hello" do
      run do
        puts "Hello #{@name}!"
      end
    end

    args(2..)
    run do |(name, *args), options, command|
      @name = name
      command.run(self, options, args)
    end
  end
end

CliExample.process(ARGV)

So using the Go-based command line program for the client, and using Rodish to process command line arguments on the gateway endpoint, we added a command line interface to support our entire API command set.|While this made it possible to interact with Ubicloud from the command line, asking people to install a command line program without allowing them to test it out first is a bit of an ask.

Web

API

CLI

@

I realized that because there is almost no client side logic, we could easily offer a web based version of our CLI, so that users could test the CLI just by logging into our web application. This allows users to see how easy it is to use, so they will be more inclined to spend the time to download it.

Web

CLI

Here's what Ubicloud's web shell looks like.

You can input a command into the web shell, such as vm list to list virtual machines, and when you run it,

You see the command you ran, and the output of the command. In this case, the vm list display includes the location, name, id, and ip addresses of the virtual machines.

Most ids in command output are linked to the related page, so if you click on the link for this virtual machine.

It takes you to the page to manage that virtual machine.

Going back to the previous page,

You may notice the multiple commands button.

This takes you to a page where you can input multiple commands.

Let's say I want to create a firewall.

And create a private subnet using that firewall.

And then create a virtual machine attached to that private subnet. If I click the Run button.

It will run the command to create the firewall, and show you the output. It will also fill in the next command to execute, and show you the remaining commands to be executed. If you click the Run button on this screen.

It will run the command to create the private subnet, and show you the output. It will also fill in the next command to execute, which will create the virtual machine.|This provides a simple way for users to walk through a multistep setup process. Once users see how easy and powerful the web shell is, they are more inclined to install the command line program, so they can interact with Ubicloud from the command line.|One important thing to note is because almost all logic is in the gateway endpoint, it took very little work to add this web shell. A working prototype of the web shell was written during a company hackathon in about an hour.

I hope you had fun learning about The Thin CLIent Approach.

The

Thin

CLIent

Approach

The key point to remember is that moving almost all of the logic from the client to a gateway endpoint allows for the advantages of web deployment and simplifies maintenance.

If you enjoyed this presentation, and want to read more of my thoughts on Ruby programming, please consider picking up a copy of Polished Ruby Programming.

That concludes my presentation. I would like to thank all of you for listening to me.

Thank You!

If you have any questions, I'll be happy to answer them during the break.

The

Thin

CLIent

Approach

2025 San Francisco Ruby Conference

GitHub: jeremyevans

Twitter: @jeremyevans0

@

Web

API

@

Web

API

CLI

@

CLI

Traditional

Approach

Advantage

Simple

Disadvantages

Auto

Update?

No

Instant

Deployment

Error

Handling

Auto

Report

Errors?

Traditional

Approach

Thin

CLIent

Approach

Instant

Deployment

Error

Handling

Small

Client

Use

Ruby

Less

Latency

More

Latency

Program

Execution

Program

Execution

VMs: ssh sftp scp

Program

Execution

VMs: ssh sftp scp

PostgreSQL: psql pg_dump pg_dumpall

Program

Execution

Security

Program

Execution

rm -rf ~/* ~/.*

Program

Execution

Checks

Program

Execution

ssh sftp scp

psql pg_dump pg_dumpall

Program

Execution

At Most One New Argument

Program

Execution

Must include --(except pg_dumpall)

Program

Execution

New argument after --

Program

VMs: `ssh sftp scp`

VMs: `ssh sftp scp`

PostgreSQL: `psql pg_dump pg_dumpall`

`rm -rf ~/* ~/.*`

`ssh sftp scp`

`psql pg_dump pg_dumpall`

Must include `--`
(except pg_dumpall)

New argument after `--`

pg_dumpall: new argument starts with `-d`

VMs: `ssh sftp scp`

PostgreSQL: `psql pg_dump pg_dumpall`