vmfloaty 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f04ad5dd857d55ff4d7dfa42eb344952bb2eac10d4601a911d8e7255e212d09
-  data.tar.gz: 6b2b56d9cd35e5d48062116a7c17129ed0c4404d2fe9c00461fbc6ab90570181
+  metadata.gz: 4cf673c0a3e005fc4ef5102d232206f3105215de4f19cd76725de335b62937fd
+  data.tar.gz: e4791593e75d31d42a8f05cfb28b3655e42218ac1a7191ae1c8391ccdad5133b
 SHA512:
-  metadata.gz: b1785b87fc949e6088f0a8d0d17ce0a599a75bf6d117758adba8583c6aeeb88ff56b4ab3dff217cfc8029ae2115254a3a7a02e864db29a60ab6dac6d7b1eb597
-  data.tar.gz: 2d5ebc3d83665e5fcf5f6bc7ef362f5d8a340e95e456ca859579264eae7d8fa3cd447f880355efec03e31a6de4daba2a816ad46b4e0bf69b5a692949e71ba753
+  metadata.gz: b22ad1332f3a663407a6ce964525606938134925e0b91ccd151a8f9a4abc265cab53cddd9509ce92555abb357dc213f2beef50a02ea72eb501db31c9e3936983
+  data.tar.gz: 8436c38cc6a99b76c4e65da0dfa653edbbdbe9b7fcefb9607942983cd24014c40ab14f556b06e7d6a449dc57f84740e09df2668e15129cdb5dccbb3b6e746eff

data/README.md

@@ -1,40 +1,64 @@
-vmfloaty
-========
-
-[![Gem Version](https://badge.fury.io/rb/vmfloaty.svg)](https://badge.fury.io/rb/vmfloaty) [![Build Status](https://travis-ci.org/briancain/vmfloaty.svg?branch=master)](https://travis-ci.org/briancain/vmfloaty)
-
-A CLI helper tool for [Puppet Labs vmpooler](https://github.com/puppetlabs/vmpooler) to help you stay afloat.
-
-<img src="http://i.imgur.com/xGcGwuH.jpg" width=200 height=200>
-
-This project is still supported by @briancain and @demophoon. Ping either of us if you'd like something merged and released.
+# vmfloaty
+
+[![Gem Version](https://badge.fury.io/rb/vmfloaty.svg)](https://badge.fury.io/rb/vmfloaty)
+[![Build Status](https://travis-ci.com/puppetlabs/vmfloaty.svg?branch=master)](https://travis-ci.com/puppetlabs/vmfloaty)
+[![Coverage Status](https://coveralls.io/repos/github/puppetlabs/vmfloaty/badge.svg?branch=master)](https://coveralls.io/github/puppetlabs/vmfloaty?branch=master)
+[![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=puppetlabs/vmfloaty)](https://dependabot.com)
+
+A CLI helper tool for [Puppet's vmpooler](https://github.com/puppetlabs/vmpooler) to help you stay afloat.
+
+![float image](float.jpg)
+
+- [Install](#install)
+- [Usage](#usage)
+  - [Example workflow](#example-workflow)
+  - [vmfloaty dotfile](#vmfloaty-dotfile)
+    - [Basic configuration](#basic-configuration)
+    - [Using multiple services](#using-multiple-services)
+    - [Using backends besides VMPooler](#using-backends-besides-vmpooler)
+    - [Valid config keys](#valid-config-keys)
+  - [Tab Completion](#tab-completion)
+- [vmpooler API](#vmpooler-api)
+- [Using the Pooler class](#using-the-pooler-class)
+  - [Example Projects](#example-projects)
+- [Special thanks](#special-thanks)
 
 ## Install
 
 Grab the latest from ruby gems...
 
-```
-$ gem install vmfloaty
-...
-...
-$ floaty --help
+```bash
+gem install vmfloaty
 ```
 
 ## Usage
 
-```
-    delete   Schedules the deletion of a host or hosts
-    get      Gets a vm or vms based on the os argument
-    help     Display global or [command] help documentation
-    list     Shows a list of available vms from the pooler or vms obtained with a token
-    modify   Modify a vms tags, time to live, and disk space
-    query    Get information about a given vm
-    revert   Reverts a vm to a specified snapshot
-    snapshot Takes a snapshot of a given vm
-    ssh      Grabs a single vm and sshs into it
-    status   Prints the status of pools in vmpooler
-    summary  Prints a summary of vmpooler
-    token    Retrieves or deletes a token or checks token status
+```plain
+$ floaty --help
+  NAME:
+
+    floaty
+
+  DESCRIPTION:
+
+    A CLI helper tool for Puppet's vmpooler to help you stay afloat
+
+  COMMANDS:
+
+    completion Outputs path to completion script
+    delete     Schedules the deletion of a host or hosts
+    get        Gets a vm or vms based on the os argument
+    help       Display global or [command] help documentation
+    list       Shows a list of available vms from the pooler or vms obtained with a token
+    modify     Modify a VM's tags, time to live, disk space, or reservation reason
+    query      Get information about a given vm
+    revert     Reverts a vm to a specified snapshot
+    service    Display information about floaty services and their configuration
+    snapshot   Takes a snapshot of a given vm
+    ssh        Grabs a single vm and sshs into it
+    status     Prints the status of pools in the pooler service
+    summary    Prints a summary of a pooler service
+    token      Retrieves or deletes a token or checks token status
 
   GLOBAL OPTIONS:
 
@@ -52,7 +76,7 @@ $ floaty --help
 
 Grabbing a token for authenticated pooler requests:
 
-```
+```bash
 floaty token get --user username --url https://vmpooler.example.net/api/v1
 ```
 
@@ -60,108 +84,54 @@ This command will then ask you to log in. If successful, it will return a token
 
 Grabbing vms:
 
-```
+```bash
 floaty get centos-7-x86_64=2 debian-7-x86_64 windows-10=3 --token mytokenstring --url https://vmpooler.example.net/api/v1
 ```
 
 ### vmfloaty dotfile
 
-If you do not wish to continually specify various config options with the cli, you can have a dotfile in your home directory for some defaults. For example:
+If you do not wish to continually specify various config options with the cli, you can `~/.vmfloaty.yml` for some defaults. You can get a list of valid service types and example configuration files via `floaty service types` and `floaty service examples`, respectively.
 
 #### Basic configuration
 
+This is the simplest type of configuration where you only need a single service:
+
 ```yaml
-# file at /Users/me/.vmfloaty.yml
+# file at ~/.vmfloaty.yml
 url: 'https://vmpooler.example.net/api/v1'
 user: 'brian'
 token: 'tokenstring'
 ```
 
-Now vmfloaty will use those config files if no flag was specified.
-
-#### Configuring multiple services
-
-Most commands allow you to specify a `--service <servicename>` option to allow the use of multiple vmpooler instances. This can be useful when you'd rather not specify a `--url` or `--token` by hand for alternate services.
+Run `floaty service examples` to see additional configuration options
 
-To configure multiple services, you can set up your `~/.vmfloaty.yml` config file like this:
+#### Using multiple services
 
-```yaml
-# file at /Users/me/.vmfloaty.yml
-user: 'brian'
-services:
-  main:
-    url: 'https://vmpooler.example.net/api/v1'
-    token: 'tokenstring'
-  alternate:
-    url: 'https://vmpooler.example.com/api/v1'
-    token: 'alternate-tokenstring'
-```
+Most commands allow you to specify a `--service <servicename>` option to allow the use of multiple pooler instances. This can be useful when you'd rather not specify a `--url` or `--token` by hand for alternate services.
 
 - If you run `floaty` without a `--service <name>` option, vmfloaty will use the first configured service by default.
-  With the config file above, the default would be to use the 'main' vmpooler instance.
 - If keys are missing for a configured service, vmfloaty will attempt to fall back to the top-level values.
-  With the config file above, 'brian' will be used as the username for both configured services, since neither specifies a username.
+  This makes it so you can specify things like `user` once at the top of your `~/.vmfloaty.yml`.
 
-Examples using the above configuration:
+#### Using backends besides VMPooler
 
-List available vm types from our main vmpooler instance:
-```sh
-floaty list --service main
-# or, since the first configured service is used by default:
-floaty list
-```
-
-List available vm types from our alternate vmpooler instance:
-```sh
-floaty list --service alternate
-```
-
-#### Using a Nonstandard Pooler service
-
-vmfloaty is capable of working with Puppet's [nonstandard pooler](https://github.com/puppetlabs/nspooler) in addition to the default vmpooler API. To add a nonstandard pooler service, specify an API `type` value in your service configuration, like this:
-
-```yaml
-# file at /Users/me/.vmfloaty.yml
-user: 'brian'
-services:
-  vm:
-    url: 'https://vmpooler.example.net/api/v1'
-    token: 'tokenstring'
-  ns:
-    url: 'https://nspooler.example.net/api/v1'
-    token: 'nspooler-tokenstring'
-    type: 'nonstandard'  # <-- 'type' is necessary for any non-vmpooler service
-  abs:
-    url: 'https://abs.example.net/'
-    token: 'abs-tokenstring'
-    type: 'abs'  # <-- 'type' is necessary for any non-vmpooler service
-
-```
-
-With this configuration, you could list available OS types from nspooler like this:
-
-```sh
-floaty list --service ns
-```
+vmfloaty supports additional backends besides VMPooler. To see a complete list, run `floaty service types`. The output of `floaty service examples` will show you how to configure each of the supported backends.
 
 #### Valid config keys
 
 Here are the keys that vmfloaty currently supports:
 
-- verbose
-  + Boolean
-- token
-  + String
-- user
-  + String
-- url
-  + String
-- services
-  + Map
+- verbose (Boolean)
+- token (String)
+- user (String)
+- url (String)
+- services (String)
+- type (String)
+- vmpooler_fallback (String)
 
 ### Tab Completion
 
-There is a basic completion script for Bash (and possibly other shells) included with the gem in the [extras/completions](https://github.com/briancain/vmfloaty/blob/master/extras/completions) folder. To activate, that file simply needs to be sourced somehow in your shell profile.
+There is a basic completion script for Bash (and possibly other shells) included with the gem in the [extras/completions](https://github.com/puppetlabs/vmfloaty/blob/master/extras/completions) folder. To activate, that file simply needs to be sourced somehow in your shell profile.
 
 For convenience, the path to the completion script for the currently active version of the gem can be found with the `floaty completion` subcommand. This makes it easy to add the completion script to your profile like so:
 
@@ -175,6 +145,12 @@ If you are running on macOS and use Homebrew's `bash-completion` formula, you ca
 ln -s $(floaty completion --shell bash) /usr/local/etc/bash_completion.d/floaty
 ```
 
+There is also tab completion for zsh:
+
+```zsh
+source $(floaty completion --shell zsh)
+```
+
 ## vmpooler API
 
 This cli tool uses the [vmpooler API](https://github.com/puppetlabs/vmpooler/blob/master/API.md).
@@ -186,6 +162,10 @@ vmfloaty providers a `Pooler` class that gives users the ability to make request
 ### Example Projects
 
 - [John McCabe: vmpooler-bitbar](https://github.com/johnmccabe/vmpooler-bitbar/)
-  + vmpooler status and management in your menubar with bitbar
+  - vmpooler status and management in your menubar with bitbar
 - [Brian Cain: vagrant-vmpooler](https://github.com/briancain/vagrant-vmpooler)
-  + Use Vagrant to manage your vmpooler instances
+  - Use Vagrant to manage your vmpooler instances
+
+## Special thanks
+
+Special thanks to [Brian Cain](https://github.com/briancain) as he is the original author of vmfloaty! Vast amounts of this code exist thanks to his efforts.

data/extras/completions/floaty.bash

@@ -7,7 +7,7 @@ _vmfloaty()
   cur="${COMP_WORDS[COMP_CWORD]}"
   prev="${COMP_WORDS[COMP_CWORD-1]}"
 
-  subcommands="delete get help list modify query revert snapshot ssh status summary token"
+  subcommands="delete get help list modify query revert service snapshot ssh status summary token"
   template_subcommands="get ssh"
   hostname_subcommands="delete modify query revert snapshot"
 
@@ -21,7 +21,7 @@ _vmfloaty()
 
     COMPREPLY=( $(compgen -W "${_vmfloaty_avail_templates}" -- "${cur}") )
   elif [[ $hostname_subcommands =~ (^| )$prev($| ) ]] ; then
-    _vmfloaty_active_hostnames=$(floaty list --active 2>/dev/null | grep '^-' | cut -d' ' -f2)
+    _vmfloaty_active_hostnames=$(floaty list --active --hostnameonly 2>/dev/null)
     COMPREPLY=( $(compgen -W "${_vmfloaty_active_hostnames}" -- "${cur}") )
   else
     COMPREPLY=( $(compgen -W "${subcommands}" -- "${cur}") )

data/extras/completions/floaty.zsh

@@ -0,0 +1,37 @@
+_floaty()
+{
+  local line subcommands template_subcommands hostname_subcommands
+
+  subcommands="delete get help list modify query revert snapshot ssh status summary token"
+
+  template_subcommands=("get" "ssh")
+  hostname_subcommands=("delete" "modify" "query" "revert" "snapshot")
+
+  _arguments -C \
+    "1: :(${subcommands})" \
+    "*::arg:->args"
+
+  if ((template_subcommands[(Ie)$line[1]])); then
+    _floaty_template_sub
+  elif ((hostname_subcommands[(Ie)$line[1]])); then
+    _floaty_hostname_sub
+  fi
+}
+
+_floaty_template_sub()
+{
+  if [[ -z "$_vmfloaty_avail_templates" ]] ; then
+    _vmfloaty_avail_templates=$(floaty list 2>/dev/null)
+  fi
+
+  _arguments "1: :(${_vmfloaty_avail_templates})"
+}
+
+_floaty_hostname_sub()
+{
+  _vmfloaty_active_hostnames=$(floaty list --active --hostnameonly 2>/dev/null)
+
+  _arguments "1: :(${_vmfloaty_active_hostnames})"
+}
+
+compdef _floaty floaty

data/lib/vmfloaty.rb

@@ -13,13 +13,14 @@ require 'vmfloaty/conf'
 require 'vmfloaty/utils'
 require 'vmfloaty/service'
 require 'vmfloaty/ssh'
+require 'vmfloaty/logger'
 
 class Vmfloaty
   include Commander::Methods
 
   def run # rubocop:disable Metrics/AbcSize
     program :version, Vmfloaty::VERSION
-    program :description, 'A CLI helper tool for Puppet Labs VM poolers to help you stay afloat'
+    program :description, "A CLI helper tool for Puppet's vmpooler to help you stay afloat.\n\nConfiguration may be placed in a ~/.vmfloaty.yml file."
 
     config = Conf.read_config
 
@@ -37,6 +38,7 @@ class Vmfloaty
       c.option '--notoken', 'Makes a request without a token'
       c.option '--force', 'Forces vmfloaty to get requested vms'
       c.option '--json', 'Prints retrieved vms in JSON format'
+      c.option '--ondemand', 'Requested vms are provisioned upon receival of the request, tracked by a request ID'
       c.action do |args, options|
         verbose = options.verbose || config['verbose']
         service = Service.new(options, config)
@@ -44,7 +46,7 @@ class Vmfloaty
         force = options.force
 
         if args.empty?
-          STDERR.puts 'No operating systems provided to obtain. See `floaty get --help` for more information on how to get VMs.'
+          FloatyLogger.error 'No operating systems provided to obtain. See `floaty get --help` for more information on how to get VMs.'
           exit 1
         end
 
@@ -53,19 +55,23 @@ class Vmfloaty
         max_pool_request = 5
         large_pool_requests = os_types.select { |_, v| v > max_pool_request }
         if !large_pool_requests.empty? && !force
-          STDERR.puts "Requesting vms over #{max_pool_request} requires a --force flag."
-          STDERR.puts 'Try again with `floaty get --force`'
+          FloatyLogger.error "Requesting vms over #{max_pool_request} requires a --force flag."
+          FloatyLogger.error 'Try again with `floaty get --force`'
           exit 1
         end
 
         if os_types.empty?
-          STDERR.puts 'No operating systems provided to obtain. See `floaty get --help` for more information on how to get VMs.'
+          FloatyLogger.error 'No operating systems provided to obtain. See `floaty get --help` for more information on how to get VMs.'
           exit 1
         end
 
-        response = service.retrieve(verbose, os_types, use_token)
+        response = service.retrieve(verbose, os_types, use_token, options.ondemand)
+        request_id = response['request_id'] if options.ondemand
+        response = service.wait_for_request(verbose, request_id) if options.ondemand
+
         hosts = Utils.standardize_hostnames(response)
-        if options.json
+
+        if options.json || options.ondemand
           puts JSON.pretty_generate(hosts)
         else
           puts Utils.format_host_output(hosts)
@@ -81,8 +87,11 @@ class Vmfloaty
       c.option '--verbose', 'Enables verbose output'
       c.option '--service STRING', String, 'Configured pooler service name'
       c.option '--active', 'Prints information about active vms for a given token'
+      c.option '--json', 'Prints information as JSON'
+      c.option '--hostnameonly', 'When listing active vms, prints only hostnames, one per line'
       c.option '--token STRING', String, 'Token for pooler service'
       c.option '--url STRING', String, 'URL of pooler service'
+      c.option '--user STRING', String, 'User to authenticate with'
       c.action do |args, options|
         verbose = options.verbose || config['verbose']
 
@@ -91,13 +100,30 @@ class Vmfloaty
 
         if options.active
           # list active vms
-          running_vms = service.list_active(verbose)
+          if service.type == "ABS"
+            # this is actually job_ids
+            running_vms = service.list_active_job_ids(verbose, service.url, service.user)
+          else
+            running_vms = service.list_active(verbose)
+          end
           host = URI.parse(service.url).host
           if running_vms.empty?
-            puts "You have no running VMs on #{host}"
+            if options.json
+              puts {}.to_json
+            else
+              FloatyLogger.info "You have no running VMs on #{host}"
+            end
           else
-            puts "Your VMs on #{host}:"
-            Utils.pretty_print_hosts(verbose, service, running_vms)
+            if options.json
+              puts Utils.get_host_data(verbose, service, running_vms).to_json
+            elsif options.hostnameonly
+              Utils.get_host_data(verbose, service, running_vms).each do |hostname, host_data|
+                Utils.print_fqdn_for_host(service, hostname, host_data)
+              end
+            else
+              puts "Your VMs on #{host}:"
+              Utils.pretty_print_hosts(verbose, service, running_vms)
+            end
           end
         else
           # list available vms from pooler
@@ -110,7 +136,7 @@ class Vmfloaty
     command :query do |c|
       c.syntax = 'floaty query hostname [options]'
       c.summary = 'Get information about a given vm'
-      c.description = 'Given a hostname from the pooler service, vmfloaty with query the service to get various details about the vm.'
+      c.description = 'Given a hostname from the pooler service, vmfloaty with query the service to get various details about the vm. If using ABS, you can query a job_id'
       c.example 'Get information about a sample host', 'floaty query hostname --url http://vmpooler.example.com'
       c.option '--verbose', 'Enables verbose output'
       c.option '--service STRING', String, 'Configured pooler service name'
@@ -146,10 +172,15 @@ class Vmfloaty
         modify_all = options.all
 
         if hostname.nil? && !modify_all
-          STDERR.puts 'ERROR: Provide a hostname or specify --all.'
+          FloatyLogger.error 'ERROR: Provide a hostname or specify --all.'
           exit 1
         end
-        running_vms = modify_all ? service.list_active(verbose) : hostname.split(',')
+        running_vms =
+            if modify_all
+              service.list_active(verbose)
+            else
+              hostname.split(',')
+            end
 
         tags = options.tags ? JSON.parse(options.tags) : nil
         modify_hash = {
@@ -167,13 +198,13 @@ class Vmfloaty
             begin
               modified_hash[vm] = service.modify(verbose, vm, modify_hash)
             rescue ModifyError => e
-              STDERR.puts e
+              FloatyLogger.error e
               ok = false
             end
           end
           if ok
             if modify_all
-              puts 'Successfully modified all VMs.'
+              puts "Successfully modified all #{running_vms.count} VMs."
             else
               puts "Successfully modified VM #{hostname}."
             end
@@ -185,15 +216,19 @@ class Vmfloaty
 
     command :delete do |c|
       c.syntax = 'floaty delete hostname,hostname2 [options]'
+      c.syntax += "\n    floaty delete job1,job2 [options] (only supported with ABS)"
       c.summary = 'Schedules the deletion of a host or hosts'
-      c.description = 'Given a comma separated list of hostnames, or --all for all vms, vmfloaty makes a request to the pooler service to schedule the deletion of those vms.'
+      c.description = 'Given a comma separated list of hostnames, or --all for all vms, vmfloaty makes a request to the pooler service to schedule the deletion of those vms. If you are using the ABS service, you can also pass in JobIDs here. Note that passing in a Job ID will delete *all* of the hosts in the job.' # rubocop:disable Layout/LineLength
       c.example 'Schedules the deletion of a host or hosts', 'floaty delete myhost1,myhost2 --url http://vmpooler.example.com'
+      c.example 'Schedules the deletion of a JobID or JobIDs', 'floaty delete 1579300120799,1579300120800 --url http://abs.example.com'
       c.option '--verbose', 'Enables verbose output'
       c.option '--service STRING', String, 'Configured pooler service name'
       c.option '--all', 'Deletes all vms acquired by a token'
       c.option '-f', 'Does not prompt user when deleting all vms'
+      c.option '--json', 'Outputs hosts scheduled for deletion as JSON'
       c.option '--token STRING', String, 'Token for pooler service'
       c.option '--url STRING', String, 'URL of pooler service'
+      c.option '--user STRING', String, 'User to authenticate with'
       c.action do |args, options|
         verbose = options.verbose || config['verbose']
         service = Service.new(options, config)
@@ -205,15 +240,25 @@ class Vmfloaty
         successes = []
 
         if delete_all
-          running_vms = service.list_active(verbose)
+          if service.type == "ABS"
+            # this is actually job_ids
+            running_vms = service.list_active_job_ids(verbose, service.url, service.user)
+          else
+            running_vms = service.list_active(verbose)
+          end
           if running_vms.empty?
-            STDERR.puts 'You have no running VMs.'
+            if options.json
+              puts {}.to_json
+            else
+              FloatyLogger.info "You have no running VMs."
+            end
           else
-            Utils.pretty_print_hosts(verbose, service, running_vms)
-            # Confirm deletion
-            puts
             confirmed = true
-            confirmed = agree('Delete all these VMs? [y/N]') unless force
+            unless force
+              Utils.pretty_print_hosts(verbose, service, running_vms, true)
+              # Confirm deletion
+              confirmed = agree('Delete all these VMs? [y/N]')
+            end
             if confirmed
               response = service.delete(verbose, running_vms)
               response.each do |hostname, result|
@@ -236,23 +281,28 @@ class Vmfloaty
             end
           end
         else
-          STDERR.puts 'You did not provide any hosts to delete'
+          FloatyLogger.info 'You did not provide any hosts to delete'
           exit 1
         end
 
         unless failures.empty?
-          STDERR.puts 'Unable to delete the following VMs:'
+          FloatyLogger.info 'Unable to delete the following VMs:'
           failures.each do |hostname|
-            STDERR.puts "- #{hostname}"
+            FloatyLogger.info "- #{hostname}"
           end
-          STDERR.puts 'Check `floaty list --active`; Do you need to specify a different service?'
+          FloatyLogger.info 'Check `floaty list --active`; Do you need to specify a different service?'
         end
 
         unless successes.empty?
-          puts unless failures.empty?
-          puts 'Scheduled the following VMs for deletion:'
-          successes.each do |hostname|
-            puts "- #{hostname}"
+          if options.json
+            puts successes.to_json
+          else
+            puts 'Scheduled the following VMs for deletion:'
+            output = ''
+            successes.each do |hostname|
+              output += "- #{hostname}\n"
+            end
+            puts output
           end
         end
 
@@ -277,7 +327,7 @@ class Vmfloaty
         begin
           snapshot_req = service.snapshot(verbose, hostname)
         rescue TokenError, ModifyError => e
-          STDERR.puts e
+          FloatyLogger.error e
           exit 1
         end
 
@@ -302,12 +352,12 @@ class Vmfloaty
         hostname = args[0]
         snapshot_sha = args[1] || options.snapshot
 
-        STDERR.puts "Two snapshot arguments were given....using snapshot #{snapshot_sha}" if args[1] && options.snapshot
+        FloatyLogger.info "Two snapshot arguments were given....using snapshot #{snapshot_sha}" if args[1] && options.snapshot
 
         begin
           revert_req = service.revert(verbose, hostname, snapshot_sha)
         rescue TokenError, ModifyError => e
-          STDERR.puts e
+          FloatyLogger.error e
           exit 1
         end
 
@@ -382,14 +432,14 @@ class Vmfloaty
             status = service.token_status(verbose, token_value)
             puts status
           when nil
-            STDERR.puts 'No action provided'
+            FloatyLogger.error 'No action provided'
             exit 1
           else
-            STDERR.puts "Unknown action: #{action}"
+            FloatyLogger.error "Unknown action: #{action}"
             exit 1
           end
         rescue TokenError => e
-          STDERR.puts e
+          FloatyLogger.error e
           exit 1
         end
         exit 0
@@ -413,13 +463,13 @@ class Vmfloaty
         use_token = !options.notoken
 
         if args.empty?
-          STDERR.puts 'No operating systems provided to obtain. See `floaty ssh --help` for more information on how to get VMs.'
+          FloatyLogger.error 'No operating systems provided to obtain. See `floaty ssh --help` for more information on how to get VMs.'
           exit 1
         end
 
         host_os = args.first
 
-        STDERR.puts "Can't ssh to multiple hosts; Using #{host_os} only..." if args.length > 1
+        FloatyLogger.info "Can't ssh to multiple hosts; Using #{host_os} only..." if args.length > 1
 
         service.ssh(verbose, host_os, use_token)
         exit 0
@@ -446,7 +496,71 @@ class Vmfloaty
           puts completion_file
           exit 0
         else
-          STDERR.puts "Could not find completion file for '#{shell}': No such file #{completion_file}"
+          FloatyLogger.error "Could not find completion file for '#{shell}': No such file #{completion_file}"
+          exit 1
+        end
+      end
+    end
+
+    command :service do |c|
+      c.syntax = 'floaty service <types examples>'
+      c.summary = 'Display information about floaty services and their configuration'
+      c.description = 'Display information about floaty services to aid in setting up a configuration file.'
+      c.example 'Print a list of the valid service types', 'floaty service types'
+      c.example 'Print a sample config file with multiple services', 'floaty service examples'
+      c.example 'list vms from the service named "nspooler-prod"', 'floaty list --service nspooler-prod'
+      c.action do |args, options|
+        action = args.first
+
+        example_config = Utils.strip_heredoc(<<-CONFIG)
+          # Sample ~/.vmfloaty.yml with just vmpooler
+          user: 'jdoe'
+          url: 'https://vmpooler.example.net'
+          token: '456def789'
+
+          # Sample ~/.vmfloaty.yml with multiple services
+          # Note: when the --service is not specified on the command line,
+          # the first service listed here is selected automatically
+          user: 'jdoe'
+          services:
+            abs-prod:
+              type: 'abs'
+              url: 'https://abs.example.net/api/v2'
+              token: '123abc456'
+              vmpooler_fallback: 'vmpooler-prod'
+            nspooler-prod:
+              type: 'nspooler'
+              url: 'https://nspooler.example.net'
+              token:  '789ghi012'
+            vmpooler-dev:
+              type: 'vmpooler'
+              url: 'https://vmpooler-dev.example.net'
+              token: '987dsa654'
+            vmpooler-prod:
+              type: 'vmpooler'
+              url: 'https://vmpooler.example.net'
+              token: '456def789'
+
+        CONFIG
+
+        types_output = Utils.strip_heredoc(<<-TYPES)
+          The values on the left below can be used in ~/.vmfloaty.yml as the value of type:
+
+          abs:       Puppet's Always Be Scheduling
+          nspooler:  Puppet's Non-standard Pooler, aka NSPooler
+          vmpooler:  Puppet's VMPooler
+        TYPES
+
+        case action
+        when 'examples'
+          FloatyLogger.info example_config
+        when 'types'
+          FloatyLogger.info types_output
+        when nil
+          FloatyLogger.error 'No action provided'
+          exit 1
+        else
+          FloatyLogger.error "Unknown action: #{action}"
           exit 1
         end
       end